Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,300 @@
|
||||
# NetBox PowerDNS Sync Plugin Reference
|
||||
|
||||
*Source: <https://github.com/ArnesSI/netbox-powerdns-sync*>
|
||||
|
||||
## Overview
|
||||
|
||||
A NetBox plugin that automatically generates DNS records in PowerDNS based on NetBox IP Address and Device objects.
|
||||
|
||||
## Features
|
||||
|
||||
- Automatically generates A, AAAA & PTR records
|
||||
- Manages multiple DNS Zones across multiple PowerDNS servers
|
||||
- Flexible rules to match NetBox IP Addresses into DNS zones
|
||||
- Multiple options to generate DNS names from IP address or Device
|
||||
- Scheduled sync of DNS zones
|
||||
- Can add DNS records for new zones immediately
|
||||
- Per-zone synchronization schedule
|
||||
|
||||
## DNS Name Generation
|
||||
|
||||
### Zone Matching Priority
|
||||
|
||||
When determining the zone for an IP Address, match rules are evaluated in this order:
|
||||
|
||||
1. Check if `IPAddress.dns_name` matches any zone
|
||||
2. Check if IPAddress is assigned to Device/VirtualMachine and if its name matches any zone
|
||||
3. Check if IPAddress is assigned to FHRPGroup and if its name matches any zone
|
||||
4. Try to match based on assigned tags (in order):
|
||||
- `IPAddress.tags`
|
||||
- `Interface.tags`
|
||||
- `VMInterface.tags`
|
||||
- `Device.tags`
|
||||
- `VirtualMachine.tags`
|
||||
- `Device.device_role`
|
||||
- `VM.role`
|
||||
5. Use default zone if configured
|
||||
|
||||
### Name Generation Methods
|
||||
|
||||
Each zone can use multiple naming methods (tried in order):
|
||||
|
||||
1. **IP naming method** - Generate name from IP address
|
||||
2. **Device naming method** - Generate name from Device/VirtualMachine
|
||||
3. **FHRP group method** - Generate name from FHRP Group
|
||||
|
||||
## Installation
|
||||
|
||||
### Via pip
|
||||
|
||||
```bash
|
||||
# Activate NetBox virtual environment
|
||||
source /opt/netbox/venv/bin/activate
|
||||
|
||||
# Install plugin
|
||||
pip install netbox-powerdns-sync
|
||||
```
|
||||
|
||||
### From GitHub
|
||||
|
||||
```bash
|
||||
pip install git+https://github.com/ArnesSI/netbox-powerdns-sync.git@master
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Add to `/opt/netbox/netbox/netbox/configuration.py`:
|
||||
|
||||
```python
|
||||
PLUGINS = [
|
||||
'netbox_powerdns_sync'
|
||||
]
|
||||
|
||||
PLUGINS_CONFIG = {
|
||||
"netbox_powerdns_sync": {
|
||||
"ttl_custom_field": "",
|
||||
"powerdns_managed_record_comment": "netbox-powerdns-sync",
|
||||
"post_save_enabled": False,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Apply Migrations
|
||||
|
||||
```bash
|
||||
cd /opt/netbox/netbox/
|
||||
python3 manage.py migrate
|
||||
python3 manage.py reindex --lazy
|
||||
```
|
||||
|
||||
## Configuration Settings
|
||||
|
||||
| Setting | Default | Description |
|
||||
|---------|---------|-------------|
|
||||
| `ttl_custom_field` | `None` | Name of NetBox Custom field applied to IP Address objects for TTL |
|
||||
| `powerdns_managed_record_comment` | `"netbox-powerdns-sync"` | Plugin only touches records with this comment. Set to `None` to manage all records |
|
||||
| `post_save_enabled` | `False` | Immediately create DNS records when creating/updating IP Address, Device, or FHRP Group |
|
||||
|
||||
### Custom TTL Field
|
||||
|
||||
To set TTL per DNS record:
|
||||
|
||||
1. Create NetBox Custom Field:
|
||||
- Type: Integer
|
||||
- Apply to: IP Address objects
|
||||
- Name: e.g., "dns_ttl"
|
||||
|
||||
2. Set in plugin config:
|
||||
|
||||
```python
|
||||
"ttl_custom_field": "dns_ttl"
|
||||
```
|
||||
|
||||
3. Set TTL value on IP Address objects in NetBox
|
||||
|
||||
## Compatibility
|
||||
|
||||
| NetBox Version | Plugin Version |
|
||||
|---------------|----------------|
|
||||
| 3.5.0-7 | 0.0.1 - 0.0.6 |
|
||||
| 3.5.8 | 0.0.7 |
|
||||
| 3.6.x | 0.8.0 |
|
||||
|
||||
## Usage Workflow
|
||||
|
||||
### 1. Configure DNS Zones in NetBox
|
||||
|
||||
Create zones in the plugin interface with:
|
||||
|
||||
- Zone name (e.g., `spaceships.work`)
|
||||
- PowerDNS server connection
|
||||
- Tag matching rules
|
||||
- DNS name generation method
|
||||
|
||||
### 2. Tag Resources
|
||||
|
||||
Apply tags to IP Addresses, Devices, or Interfaces to match zones:
|
||||
|
||||
```python
|
||||
# Example: Tag IP for specific zone
|
||||
ipaddress.tags.add("production-dns")
|
||||
```
|
||||
|
||||
### 3. Schedule Sync
|
||||
|
||||
Configure sync schedule for each zone:
|
||||
|
||||
- Immediate (on save)
|
||||
- Scheduled (cron-style)
|
||||
- Manual only
|
||||
|
||||
### 4. Monitor Sync Results
|
||||
|
||||
View sync results in NetBox:
|
||||
|
||||
- Records created
|
||||
- Records updated
|
||||
- Records deleted
|
||||
- Sync errors
|
||||
|
||||
## Best Practices
|
||||
|
||||
### DNS Naming Conventions
|
||||
|
||||
For homelab naming like `docker-01-nexus.spaceships.work`:
|
||||
|
||||
1. Use Device name as base: `docker-01-nexus`
|
||||
2. Zone maps to domain: `spaceships.work`
|
||||
3. Set device naming method in zone config
|
||||
|
||||
### Tag Organization
|
||||
|
||||
```python
|
||||
# Production resources
|
||||
tags: ["production", "dns-auto"]
|
||||
|
||||
# Development resources
|
||||
tags: ["development", "dns-dev"]
|
||||
```
|
||||
|
||||
### TTL Strategy
|
||||
|
||||
- Default TTL in zone: 300 (5 minutes)
|
||||
- Override with custom field for specific records
|
||||
- Longer TTL for stable infrastructure (3600)
|
||||
- Shorter TTL for dynamic services (60-300)
|
||||
|
||||
### PowerDNS Server Management
|
||||
|
||||
- Configure multiple PowerDNS servers for HA
|
||||
- Use different servers for different zones
|
||||
- Monitor PowerDNS API connectivity
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### With Terraform
|
||||
|
||||
Use NetBox as data source, sync DNS automatically:
|
||||
|
||||
```hcl
|
||||
# Terraform creates resource in NetBox
|
||||
resource "netbox_ip_address" "server" {
|
||||
ip_address = "192.168.1.100/24"
|
||||
dns_name = "docker-01-nexus"
|
||||
tags = ["production-dns"]
|
||||
}
|
||||
|
||||
# Plugin automatically creates DNS in PowerDNS
|
||||
# A record: docker-01-nexus.spaceships.work -> 192.168.1.100
|
||||
# PTR record: 100.1.168.192.in-addr.arpa -> docker-01-nexus.spaceships.work
|
||||
```
|
||||
|
||||
### With Ansible
|
||||
|
||||
Use NetBox dynamic inventory with automatic DNS:
|
||||
|
||||
```yaml
|
||||
---
|
||||
# Ansible creates VM in Proxmox
|
||||
- name: Create VM
|
||||
proxmox_kvm:
|
||||
name: docker-01-nexus
|
||||
# ... vm config ...
|
||||
|
||||
# Add to NetBox via API
|
||||
- name: Register in NetBox
|
||||
netbox.netbox.netbox_ip_address:
|
||||
data:
|
||||
address: "192.168.1.100/24"
|
||||
dns_name: "docker-01-nexus"
|
||||
tags:
|
||||
- production-dns
|
||||
|
||||
# DNS records created automatically by plugin
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Records Not Syncing
|
||||
|
||||
1. Check zone matching rules
|
||||
2. Verify tags applied correctly
|
||||
3. Check PowerDNS API connectivity
|
||||
4. Review sync results for errors
|
||||
|
||||
### Duplicate Records
|
||||
|
||||
If `powerdns_managed_record_comment` is `None`, plugin manages ALL records. Set a comment to limit scope:
|
||||
|
||||
```python
|
||||
"powerdns_managed_record_comment": "netbox-managed"
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
|
||||
- Disable `post_save_enabled` for large environments
|
||||
- Use scheduled sync instead
|
||||
- Batch changes before sync
|
||||
|
||||
### Name Generation Not Working
|
||||
|
||||
1. Check zone name generation method configuration
|
||||
2. Verify Device/IP naming follows expected pattern
|
||||
3. Test with manual sync first
|
||||
|
||||
## API Endpoints
|
||||
|
||||
Plugin adds REST API endpoints:
|
||||
|
||||
- `/api/plugins/netbox-powerdns-sync/zones/` - List/manage zones
|
||||
- `/api/plugins/netbox-powerdns-sync/servers/` - PowerDNS servers
|
||||
- `/api/plugins/netbox-powerdns-sync/sync-results/` - Sync history
|
||||
|
||||
## Example Configuration
|
||||
|
||||
### Zone for Production
|
||||
|
||||
```python
|
||||
zone_config = {
|
||||
"name": "spaceships.work",
|
||||
"server": powerdns_server_prod,
|
||||
"default_ttl": 300,
|
||||
"naming_methods": ["device", "ip"],
|
||||
"tag_match": ["production-dns"],
|
||||
"auto_sync": True,
|
||||
"sync_schedule": "*/15 * * * *" # Every 15 minutes
|
||||
}
|
||||
```
|
||||
|
||||
### Zone for Lab
|
||||
|
||||
```python
|
||||
zone_config = {
|
||||
"name": "lab.spaceships.work",
|
||||
"server": powerdns_server_dev,
|
||||
"default_ttl": 60,
|
||||
"naming_methods": ["ip", "device"],
|
||||
"tag_match": ["lab-dns"],
|
||||
"auto_sync": False # Manual sync only
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user