zhongwei/gh-basher83-lunar-claude-plugins-homelab-netbox-powerdns-integration
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
26377bd9bee83b49ab048bf559dc7b0d9c483e45
gh-basher83-lunar-claude-pl…/skills/netbox-powerdns-integration/anti-patterns/common-mistakes.md
Zhongwei Li 26377bd9be Initial commit
2025-11-29 18:00:21 +08:00

10 KiB
Raw Blame History

Common Mistakes and Anti-Patterns

DNS naming convention violations and NetBox/PowerDNS integration pitfalls based on the spaceships.work infrastructure.

DNS Naming Convention Violations

Infrastructure Overview

Root Domain: spaceships.work

Cluster Domains:

  • matrix.spaceships.work - Nexus cluster (3 nodes)
  • quantum.spaceships.work - Quantum cluster (3 nodes)
  • nexus.spaceships.work - (Legacy naming reference)

Proxmox Node Domains (with master node designations):

Matrix Cluster (nexus.spaceships.work):

  • foxtrot.nexus.spaceships.work - Master Node (API Target)
  • golf.nexus.spaceships.work
  • hotel.nexus.spaceships.work

Quantum Cluster (quantum.spaceships.work):

  • charlie.quantum.spaceships.work
  • delta.quantum.spaceships.work - Master Node (API Target)
  • echo.quantum.spaceships.work

Matrix Cluster (matrix.spaceships.work):

  • alpha.matrix.spaceships.work
  • bravo.matrix.spaceships.work - Master Node (API Target)
  • charlie.matrix.spaceships.work

❌ Wrong Root Domain

Problem: Using incorrect root domain in DNS records.

# BAD - Wrong domain
hostname = "docker-01-nexus.internal.lan"
hostname = "k8s-master.homelab.local"

Solution: Always use spaceships.work as root domain.

# GOOD
hostname = "docker-01-nexus.spaceships.work"
hostname = "k8s-01-master.matrix.spaceships.work"

❌ Wrong Cluster Subdomain

Problem: Using non-existent cluster domains.

# BAD - Invalid cluster domains
hostname = "docker-01.homelab.spaceships.work"  # No 'homelab' cluster
hostname = "vm-01.lab.spaceships.work"          # No 'lab' cluster
hostname = "test.prod.spaceships.work"          # No 'prod' cluster

Solution: Use only valid cluster domains.

# GOOD - Valid cluster domains
hostname = "docker-01-nexus.matrix.spaceships.work"
hostname = "k8s-01-worker.quantum.spaceships.work"
hostname = "storage-01-ceph.nexus.spaceships.work"

Valid Clusters:

  • matrix.spaceships.work
  • quantum.spaceships.work
  • nexus.spaceships.work

❌ Wrong Node Domain

Problem: Using incorrect Proxmox node FQDNs.

# BAD - Incorrect node names
proxmox_host = "node1.spaceships.work"          # Not the naming pattern
proxmox_host = "foxtrot.spaceships.work"        # Missing cluster subdomain
proxmox_host = "foxtrot.matrix.spaceships.org"  # Wrong TLD

Solution: Use correct node FQDN pattern.

# GOOD - Correct node FQDNs
proxmox_host = "foxtrot.nexus.spaceships.work"    # Nexus cluster master
proxmox_host = "delta.quantum.spaceships.work"    # Quantum cluster master
proxmox_host = "bravo.matrix.spaceships.work"     # Matrix cluster master

❌ Targeting Non-Master Nodes

Problem: Sending API calls to non-master nodes in cluster.

# BAD - Not a master node
from proxmoxer import ProxmoxAPI

proxmox = ProxmoxAPI(
    'golf.nexus.spaceships.work',  # ❌ Not the master!
    user='root@pam',
    password='...'
)

Solution: Always target the designated master node for API operations.

# GOOD - Target master nodes
from proxmoxer import ProxmoxAPI

# Nexus cluster
proxmox_nexus = ProxmoxAPI(
    'foxtrot.nexus.spaceships.work',  # ✅ Master node
    user='root@pam',
    password='...'
)

# Quantum cluster
proxmox_quantum = ProxmoxAPI(
    'delta.quantum.spaceships.work',  # ✅ Master node
    user='root@pam',
    password='...'
)

# Matrix cluster
proxmox_matrix = ProxmoxAPI(
    'bravo.matrix.spaceships.work',  # ✅ Master node
    user='root@pam',
    password='...'
)

Master Nodes Quick Reference:

  • Nexus: foxtrot.nexus.spaceships.work
  • Quantum: delta.quantum.spaceships.work
  • Matrix: bravo.matrix.spaceships.work

❌ Violating Service-Number-Purpose Pattern

Problem: Not following the service-NN-purpose naming convention.

# BAD - Violates naming pattern
hostname = "nexus.spaceships.work"              # Missing service number
hostname = "docker-nexus.spaceships.work"       # Missing number
hostname = "docker1-nexus.spaceships.work"      # Wrong number format (1 vs 01)
hostname = "nexus-docker-01.spaceships.work"    # Wrong order

Solution: Follow service-NN-purpose.domain pattern.

# GOOD - Correct naming pattern
hostname = "docker-01-nexus.spaceships.work"      # ✅ service-01-purpose
hostname = "k8s-02-worker.matrix.spaceships.work" # ✅ service-02-purpose
hostname = "storage-03-ceph.nexus.spaceships.work"# ✅ service-03-purpose

Pattern: <service>-<NN>-<purpose>.<cluster>.<root-domain>

Components:

  • service: Infrastructure type (docker, k8s, proxmox, storage, db)
  • NN: Two-digit number (01, 02, 03, ... 99)
  • purpose: Specific role (nexus, master, worker, ceph, postgres)
  • cluster: Cluster subdomain (matrix, quantum, nexus)
  • root-domain: spaceships.work

❌ Improper Case in Hostnames

Problem: Using uppercase letters in DNS names.

# BAD - Uppercase not allowed
hostname = "Docker-01-Nexus.spaceships.work"
hostname = "K8S-01-MASTER.matrix.spaceships.work"

Solution: Always use lowercase.

# GOOD
hostname = "docker-01-nexus.spaceships.work"
hostname = "k8s-01-master.matrix.spaceships.work"

NetBox Integration Issues

❌ Not Setting DNS Name in NetBox

Problem: Creating IP address in NetBox without dns_name field.

# BAD - Missing DNS name
ip = nb.ipam.ip_addresses.create(
    address="192.168.3.100/24",
    description="Docker host",
    # Missing dns_name!
)

Solution: Always set dns_name when creating IPs.

# GOOD
ip = nb.ipam.ip_addresses.create(
    address="192.168.3.100/24",
    dns_name="docker-01-nexus.matrix.spaceships.work",  # ✅
    description="Docker host for Nexus registry",
    tags=["production-dns"]  # Triggers PowerDNS sync
)

❌ Missing PowerDNS Sync Tags

Problem: DNS record not created automatically because missing trigger tag.

# BAD - No sync tag
ip = nb.ipam.ip_addresses.create(
    address="192.168.3.100/24",
    dns_name="docker-01-nexus.matrix.spaceships.work",
    tags=["docker", "production"]  # Missing 'production-dns' tag!
)
# PowerDNS record NOT created automatically

Solution: Include appropriate sync tag.

# GOOD
ip = nb.ipam.ip_addresses.create(
    address="192.168.3.100/24",
    dns_name="docker-01-nexus.matrix.spaceships.work",
    tags=[
        "docker",
        "production",
        "production-dns"  # ✅ Triggers PowerDNS sync
    ]
)

Sync Tags:

  • production-dns - Auto-create in PowerDNS production zone
  • lab-dns - Auto-create in PowerDNS lab zone

❌ Inconsistent DNS Naming Between Tools

Problem: Different naming in OpenTofu vs NetBox vs Proxmox.

Note: Use tofu CLI (not terraform).

# OpenTofu
resource "proxmox_virtual_environment_vm" "docker_host" {
  name = "docker-nexus-01"  # ❌ Wrong order
}

# NetBox
dns_name = "nexus-docker-01.spaceships.work"  # ❌ Different order

# Proxmox
hostname = "docker01-nexus"  # ❌ Missing hyphen

Solution: Consistent naming everywhere.

# OpenTofu
resource "proxmox_virtual_environment_vm" "docker_host" {
  name = "docker-01-nexus"  # ✅ Consistent
}

# NetBox
dns_name = "docker-01-nexus.matrix.spaceships.work"  # ✅ Consistent

# Proxmox (via OpenTofu)
initialization {
  user_data_file_id = "local:snippets/user-data.yaml"
  # Inside user-data.yaml:
  # hostname: docker-01-nexus  # ✅ Consistent
  # fqdn: docker-01-nexus.matrix.spaceships.work
}

Validation Tools

Check DNS Naming Convention

# Validate hostname format
./tools/validate_dns_naming.py --name "docker-01-nexus.matrix.spaceships.work"
# ✅ Valid

./tools/validate_dns_naming.py --name "docker-nexus.spaceships.work"
# ❌ Invalid: Missing number in service-NN-purpose pattern

Check NetBox DNS Records

# Query NetBox for DNS records
./tools/netbox_api_client.py ips query --dns-name docker-01

# Verify PowerDNS sync
./tools/powerdns_sync_check.py --zone spaceships.work --verbose

Quick Reference

Correct Naming Patterns

VM Hostnames:

docker-01-nexus.matrix.spaceships.work
k8s-01-master.quantum.spaceships.work
storage-01-ceph.nexus.spaceships.work
db-01-postgres.matrix.spaceships.work

Proxmox Nodes:

foxtrot.nexus.spaceships.work (master)
delta.quantum.spaceships.work (master)
bravo.matrix.spaceships.work (master)

Service Types:

  • docker-NN-<app> - Docker hosts
  • k8s-NN-<role> - Kubernetes nodes (master, worker)
  • proxmox-<node>-<iface> - Proxmox infrastructure
  • storage-NN-<type> - Storage systems (ceph, nas)
  • db-NN-<dbtype> - Database servers (postgres, mysql)

Valid Domains

Clusters:

  • matrix.spaceships.work
  • quantum.spaceships.work
  • nexus.spaceships.work

Master Nodes (API targets):

  • Nexus: foxtrot.nexus.spaceships.work
  • Quantum: delta.quantum.spaceships.work
  • Matrix: bravo.matrix.spaceships.work

Troubleshooting

DNS Record Not Created in PowerDNS

Check:

  1. ✅ DNS name follows pattern? service-NN-purpose.cluster.spaceships.work
  2. ✅ Has production-dns or lab-dns tag in NetBox?
  3. ✅ NetBox PowerDNS sync plugin enabled?
  4. ✅ Zone exists in NetBox and matches domain?

Can't Connect to Proxmox API

Check:

  1. ✅ Using master node FQDN?
    • Nexus: foxtrot.nexus.spaceships.work
    • Quantum: delta.quantum.spaceships.work
    • Matrix: bravo.matrix.spaceships.work
  2. ✅ DNS resolves correctly? dig <master-node-fqdn>
  3. ✅ Cluster subdomain included? (not just <node>.spaceships.work)

Validation Script Fails

Common Issues:

# Missing number
❌ docker-nexus.spaceships.work
✅ docker-01-nexus.matrix.spaceships.work

# Wrong number format
❌ docker-1-nexus.spaceships.work
✅ docker-01-nexus.matrix.spaceships.work

# Missing cluster subdomain
❌ docker-01-nexus.spaceships.work
✅ docker-01-nexus.matrix.spaceships.work

# Wrong domain
❌ docker-01-nexus.local
✅ docker-01-nexus.matrix.spaceships.work

Run validation:

./tools/validate_dns_naming.py --name "your-hostname-here"
Reference in New Issue View Git Blame Copy Permalink