NetBox PowerDNS Integration

Expert guidance for implementing NetBox as your source of truth for infrastructure documentation and automating DNS record management with PowerDNS.

Quick Start

Common Tasks

Query NetBox API:

# List all sites
./tools/netbox_api_client.py sites list

# Get device details
./tools/netbox_api_client.py devices get --name foxtrot

# List VMs in cluster
./tools/netbox_api_client.py vms list --cluster matrix

# Query IPs
./tools/netbox_api_client.py ips query --dns-name docker-01

Create VM in NetBox:

# Create VM with auto-assigned IP
./tools/netbox_vm_create.py --name docker-02 --cluster matrix --vcpus 4 --memory 8192

# Create VM with specific IP
./tools/netbox_vm_create.py --name k8s-01-master --cluster matrix --ip 192.168.3.50/24

IPAM Queries:

# Get available IPs
./tools/netbox_ipam_query.py available --prefix 192.168.3.0/24

# Check prefix utilization
./tools/netbox_ipam_query.py utilization --site matrix

# View IP assignments
./tools/netbox_ipam_query.py assignments --prefix 192.168.3.0/24

Validate DNS Naming:

./tools/validate_dns_naming.py --name "docker-01-nexus.spaceships.work"

Deploy from NetBox Inventory:

cd ansible && uv run ansible-playbook -i tools/netbox-dynamic-inventory.yml deploy-from-netbox.yml

When to Use This Skill

Activate this skill when:

• Querying NetBox API - Sites, devices, VMs, IPs, prefixes, VLANs
• Setting up NetBox IPAM - Prefixes, IP management, VRFs
• Implementing automated DNS - PowerDNS sync plugin configuration
• Creating DNS naming conventions - service-NN-purpose.domain pattern
• Managing VMs in NetBox - Creating, updating, IP assignment
• Using Terraform with NetBox - Provider configuration and resources
• Setting up Ansible dynamic inventory - NetBox as inventory source
• Troubleshooting NetBox-PowerDNS sync - Tag matching, zone configuration
• Migrating to NetBox - From manual DNS or spreadsheet tracking
• Infrastructure documentation - Using NetBox as source of truth

Core Workflows

1. NetBox API Usage

Query infrastructure data:

#!/usr/bin/env -S uv run --script --quiet
# /// script
# requires-python = ">=3.11"
# dependencies = ["pynetbox>=7.0.0", "infisical-python>=2.3.3"]
# ///

import pynetbox
from infisical import InfisicalClient

# Get token from Infisical
client = InfisicalClient()
token = client.get_secret(
    secret_name="NETBOX_API_TOKEN",
    project_id="7b832220-24c0-45bc-a5f1-ce9794a31259",
    environment="prod",
    path="/matrix"
).secret_value

# Connect to NetBox
nb = pynetbox.api('https://netbox.spaceships.work', token=token)

# Query devices in Matrix cluster
site = nb.dcim.sites.get(slug='matrix')
devices = nb.dcim.devices.filter(site='matrix')

for device in devices:
    print(f"{device.name}: {device.primary_ip4.address if device.primary_ip4 else 'No IP'}")

See reference/netbox-api-guide.md for complete API reference.

2. DNS Naming Convention

This infrastructure uses the pattern: <service>-<number>-<purpose>.<domain>

Examples:

• docker-01-nexus.spaceships.work - Docker host #1 running Nexus
• proxmox-foxtrot-mgmt.spaceships.work - Proxmox node Foxtrot management interface
• k8s-01-master.spaceships.work - Kubernetes cluster master node #1

Implementation:

# tools/validate_dns_naming.py validates this pattern
pattern = r'^[a-z0-9-]+-\d{2}-[a-z0-9-]+\.[a-z0-9.-]+$'

See workflows/naming-conventions.md for complete rules.

3. NetBox + PowerDNS Sync Setup

Step 1: Install Plugin

# In NetBox virtualenv
pip install netbox-powerdns-sync

Step 2: Configure Plugin

# /opt/netbox/netbox/netbox/configuration.py
PLUGINS = ['netbox_powerdns_sync']

PLUGINS_CONFIG = {
    "netbox_powerdns_sync": {
        "powerdns_managed_record_comment": "netbox-managed",
        "post_save_enabled": True,  # Real-time sync
    },
}

Step 3: Create Zones in NetBox

Configure zones with:

• Zone name (e.g., spaceships.work)
• PowerDNS server connection
• Tag matching rules (e.g., production-dns)
• DNS name generation method

See reference/sync-plugin-reference.md for details.

4. Terraform Integration

Provider Setup:

terraform {
  required_providers {
    netbox = {
      source  = "e-breuninger/netbox"
      version = "~> 5.0.0"
    }
  }
}

provider "netbox" {
  server_url = "https://netbox.spaceships.work"
  api_token  = var.netbox_api_token
}

Create IP with Auto-DNS:

resource "netbox_ip_address" "docker_host" {
  ip_address  = "192.168.1.100/24"
  dns_name    = "docker-01-nexus.spaceships.work"
  description = "Docker host for Nexus registry"

  tags = [
    "terraform",
    "production-dns"  # Triggers auto DNS sync
  ]
}

DNS records created automatically by plugin!

See reference/terraform-provider-guide.md and examples/netbox-terraform-provider.tf.

5. Ansible Dynamic Inventory

Use NetBox as Inventory Source:

# tools/netbox-dynamic-inventory.yml
plugin: netbox.netbox.nb_inventory
api_endpoint: https://netbox.spaceships.work
token: !vault |
  $ANSIBLE_VAULT;...
group_by:
  - device_roles
  - tags

Deploy Using NetBox Data:

ansible-playbook -i tools/netbox-dynamic-inventory.yml deploy-from-netbox.yml

See workflows/ansible-dynamic-inventory.md.

Architecture Reference

DNS Automation Flow

1. Create/Update resource in NetBox
   └→ IP Address with dns_name and tags

2. NetBox PowerDNS Sync Plugin activates
   └→ Matches IP to zone based on tags
   └→ Generates DNS records

3. PowerDNS API called
   └→ 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

4. DNS propagates automatically
   └→ No manual DNS configuration needed

Integration with Proxmox

Terraform/Ansible
  ↓
Creates VM in Proxmox
  ↓
Registers in NetBox (via API)
  ├→ Device object
  ├→ IP Address with dns_name
  └→ Tags (production-dns)
  ↓
NetBox PowerDNS Sync
  ↓
DNS Records in PowerDNS
  ↓
Ansible Dynamic Inventory
  ↓
Automated configuration management

Tools Available

NetBox API Tools (Python + uv)

netbox_api_client.py - Comprehensive NetBox API client

# List sites, devices, VMs, IPs
./tools/netbox_api_client.py sites list
./tools/netbox_api_client.py devices get --name foxtrot
./tools/netbox_api_client.py vms list --cluster matrix
./tools/netbox_api_client.py ips query --dns-name docker-01
./tools/netbox_api_client.py prefixes available --prefix 192.168.3.0/24

netbox_vm_create.py - Create VMs in NetBox with IP assignment

# Create VM with auto IP
./tools/netbox_vm_create.py --name docker-02 --cluster matrix --vcpus 4 --memory 8192

# Create VM with specific IP
./tools/netbox_vm_create.py --name k8s-01-master --cluster matrix --ip 192.168.3.50/24

netbox_ipam_query.py - Advanced IPAM queries

# Available IPs
./tools/netbox_ipam_query.py available --prefix 192.168.3.0/24

# Prefix utilization
./tools/netbox_ipam_query.py utilization --site matrix

# IP assignments
./tools/netbox_ipam_query.py assignments --prefix 192.168.3.0/24

# IPAM summary
./tools/netbox_ipam_query.py summary --site matrix

validate_dns_naming.py - Validate DNS naming conventions

./tools/validate_dns_naming.py --name "docker-01-nexus.spaceships.work"

Terraform Modules

netbox-data-sources.tf - Examples using NetBox provider

• Query existing NetBox resources
• Use as data sources for other resources

Ansible Playbooks

deploy-from-netbox.yml - Deploy using NetBox inventory

• Dynamic inventory from NetBox
• Tag-based host selection
• Automatic IP and hostname discovery

See examples/ directory.

Troubleshooting

DNS Records Not Syncing

Check 1: Tag Matching

# Verify IP has correct tags
./tools/netbox_query.py --ip 192.168.1.100 | jq '.tags'

Check 2: Zone Configuration

• Ensure zone exists in NetBox
• Verify tag rules match
• Check PowerDNS server connectivity

Check 3: Sync Results

./tools/powerdns_sync_check.py --zone spaceships.work --verbose

Naming Convention Violations

Validate names before creating:

./tools/validate_dns_naming.py --name "my-proposed-name.domain"

Common mistakes:

• Uppercase letters (use lowercase only)
• Missing service number (must be XX format)
• Wrong domain
• Special characters (use hyphens only)

Terraform Provider Issues

Version mismatch:

Warning: NetBox version 4.3.0 not supported by provider 3.9.0

Solution: Update provider version:

version = "~> 5.0.0"  # Match NetBox 4.3.x

Dynamic Inventory Not Working

Check API connectivity:

curl -H "Authorization: Token YOUR_TOKEN" \
  https://netbox.spaceships.work/api/dcim/devices/

Verify inventory plugin:

ansible-inventory -i tools/netbox-dynamic-inventory.yml --list

See troubleshooting/ for more details.

Best Practices

1. Consistent naming - Always follow service-NN-purpose.domain pattern
2. Use tags - Tag resources for auto-DNS (production-dns, lab-dns)
3. Document in NetBox - Single source of truth for all infrastructure
4. Real-time sync - Enable post_save_enabled for immediate DNS updates
5. Terraform everything - Manage NetBox resources as IaC
6. Dynamic inventory - Never maintain static Ansible inventory
7. Audit regularly - Run dns_record_audit.py to verify sync

DNS Naming Patterns

Service Types

• docker-NN-<app> - Docker hosts
• k8s-NN-<role> - Kubernetes nodes
• proxmox-<node>-<iface> - Proxmox infrastructure
• storage-NN-<purpose> - Storage systems
• db-NN-<dbtype> - Database servers

Examples from This Infrastructure

docker-01-nexus.spaceships.work       # Nexus container registry
k8s-01-master.spaceships.work         # K8s control plane
k8s-02-worker.spaceships.work         # K8s worker node
proxmox-foxtrot-mgmt.spaceships.work  # Proxmox mgmt interface
proxmox-foxtrot-ceph.spaceships.work  # Proxmox CEPH interface
storage-01-nas.spaceships.work        # NAS storage
db-01-postgres.spaceships.work        # PostgreSQL database

Progressive Disclosure

For deeper knowledge:

NetBox API & Integration

• NetBox API Guide - Complete REST API reference with pynetbox examples
• NetBox Data Models - Data model relationships and hierarchy
• NetBox Best Practices - Security, performance, automation patterns

DNS & PowerDNS Integration

• Sync Plugin Reference - PowerDNS sync plugin installation and config
• Terraform Provider Guide - Complete provider documentation
• Naming Conventions - Detailed DNS naming rules
• DNS Automation - End-to-end automation workflows

Ansible Integration

• Ansible Dynamic Inventory - Using NetBox as inventory source

Anti-Patterns & Common Mistakes

• Common Mistakes - DNS naming violations, cluster domain errors, master node targeting, and NetBox integration pitfalls for spaceships.work infrastructure

Related Skills

• Proxmox Infrastructure - VMs auto-registered in NetBox with DNS
• Ansible Best Practices - Dynamic inventory and secrets management