PFVCluster/proxmox/docs/NAMING-POLICY.md

Naming and DNS Policy

Canonical naming policy for the PFVCluster fleet. Established: 2026-07-31

Rule

The Proxmox VM name is the canonical identifier. Everything else derives from it:

1. VM name (set via qm set <vmid> --name <name>) is the source of truth
2. DNS records (Technitium, forward + reverse) must match the VM name exactly
3. Tailscale node name must match the VM name
4. Monitoring/alerting (Beszel, Uptime Kuma, LibreNMS) uses the VM name
5. Inventory/k8s references use the VM name

Any mismatch between VM name and DNS/Tailscale name is a critical bug that must be fixed. The Technitium DNS API key is stored at ~/.secrets/api-keys.env for programmatic DNS management.

Tools

• Technitium DNS API key: ~/.secrets/api-keys.env
• Uptime Kuma API key: ~/.secrets/api-keys.env
• DNS audit: perf/scripts/probe-vm-dns.sh