feat: Add an automatic dns service for all devices & virtual machines in netbox

[33Fraise33]

There currently are a lot of devices in netbox but with the addition of native ipv6 to all devices it is hard to remember all. It would be handy that I can ping and ssh to .unitix.it. The domain has been assigned to me but I have not set up nameservers. Normally I would use cloudflare as nameservers. So we can decide to run the cloudflare nameserver and automate it there or run our own nameservers. it would be best to use public nameservers to prevent abuse of local nameservers for ddos'es.

Look into existing tools or if possible create a small docker container that subscribes on netbox changes and pushes those to the dns servers.
If the last option is chosen, make sure that we can also restart the container and do a manual sync.

[33Fraise33]

/oc plan please research this and come back with questions and remarks.

[opencode-agent]

Recommendation

Use Cloudflare as the authoritative nameserver for unitix.it and deploy a small, stateless NetBox-to-Cloudflare synchronization service.

Cloudflare would host the authoritative DNS; no Cloudflare nameserver is run locally. This avoids exposing the existing Unbound/AdGuard resolvers and avoids operating redundant public authoritative DNS servers.

A focused synchronization service fits better than the common alternatives:

• NetBox DNS plugins generally make DNS records separate objects managed inside NetBox; they do not automatically turn device and VM primary addresses into Cloudflare records.
• octoDNS-style reconciliation could provide some building blocks, but it would still need NetBox extraction, webhook handling, startup synchronization, and manual synchronization.
• Kubernetes ExternalDNS is not a natural fit for this Docker/Ansible environment.
• Extending ddclient would not handle inventory reconciliation or record deletion safely.

Repository findings

• playbooks/dns.yml already manages Cloudflare, ddclient, Unbound, and AdGuard.
• roles/cloudflare performs a one-shot Ansible reconciliation of manually declared records. It does not read NetBox or remove stale dynamically managed records.
• NetBox runs on BEOKPDCOVM01 and joins the external Docker services network.
• NetBox is currently exposed as netbox.unitix.be; there is no unitix.it configuration in the repository.
• Existing Cloudflare credentials are Vault-encrypted in group_vars/all.yml, but the synchronizer should preferably receive a dedicated, zone-scoped token.
• The existing public Cloudflare role uses both account email and token. A new service should only need a scoped API token.
• Current NetBox customization only installs netbox-plugin-prometheus-sd.
• The newer Photon role and root-level Molecule scenario provide the closest model for user isolation, health checks, runtime inspection, and container verification.

Questions requiring decisions

1. Is unitix.it definitely the intended zone?
   The repository currently uses unitix.be, while the issue explicitly requests unitix.it.

2. Which NetBox objects should publish records?

   • Active devices and active virtual machines only?
   • Should offline, planned, staged, failed, or decommissioning objects be excluded?
   • Should tenants, sites, roles, tags, or prefixes provide an allowlist?

3. Which addresses are authoritative?
   I recommend publishing only NetBox primary_ip4 and primary_ip6. Should the service fall back to assigned interface addresses when no primary address exists?

4. Should private IPv4 addresses be placed in public DNS?
   This is technically valid and useful to routed internal clients, but it exposes hostnames and addressing information publicly. Alternatives are:

   • Publish public/global addresses only.
   • Publish both private A and global AAAA records publicly.
   • Maintain split DNS, with Cloudflare receiving global addresses and AdGuard receiving private addresses.

5. Are globally routed IPv6 addresses intended to be reachable over SSH?
   DNS publication does not provide connectivity; host and perimeter firewall policy must still permit it.

6. How should naming conflicts be handled?
   Device and VM names can potentially collide. I recommend treating duplicate normalized names as an error and making no change for that name rather than selecting one arbitrarily.

7. Should DNS names be taken directly from NetBox names?
   Proposed behavior is lowercase normalization and strict rejection of names that cannot form a valid DNS label. Another option is an explicit NetBox custom field for the DNS label.

8. What should happen when an object or primary address is removed?
   I recommend deleting only Cloudflare records carrying a synchronizer ownership marker. Unmarked/manual records must never be removed.

9. Is a dedicated Cloudflare API token acceptable?
   It should have only Zone:Read and DNS:Edit for unitix.it.

10. Where should the synchronizer image be maintained?

    • Application source and Dockerfile in this repository, with an image published to GHCR.
    • A separate application repository, with this repository containing only its Ansible role.

    A separate application repository is cleaner, but keeping it here may be preferable for such a small infrastructure-specific service.

11. Should webhook/event-rule creation also be automated?
    Automating it requires a NetBox credential capable of managing event rules and webhooks. The synchronizer itself only needs a read-only NetBox API token.

12. Preferred manual synchronization interface?
    I suggest supporting both:

    • An authenticated internal POST /sync.
    • A sync --once container command, exposed through an Ansible netbox_dns_sync tag.

Proposed behavior

• Perform a complete reconciliation when the container starts.
• Receive internal NetBox webhooks and debounce them into a complete reconciliation.
• Perform a periodic full reconciliation as protection against missed events.
• Provide a health endpoint and authenticated manual-sync endpoint.
• Subscribe to changes affecting:
  • Devices
  • Virtual machines
  • IP addresses
  • Interfaces and VM interfaces
• Generate non-proxied Cloudflare A and AAAA records.
• Use a fixed ownership comment such as managed-by=netbox-cloudflare-dns.
• Update and delete only records carrying that marker.
• Fail safely on duplicate names, malformed addresses, or conflicting manually managed records.
• Use pagination and retry Cloudflare rate limits/transient failures.
• Log a concise reconciliation summary without tokens or webhook secrets.

Concrete implementation plan

1. Implement the synchronization application

   • Add NetBox pagination and filtering.
   • Extract and normalize device/VM names and primary addresses.
   • Build a deterministic desired record set.
   • Implement Cloudflare zone lookup and record reconciliation.
   • Add ownership markers and guarded stale-record deletion.
   • Add webhook signature validation, debouncing, periodic reconciliation, /healthz, /sync, and sync --once.
   • Run as a non-root user and provide a Docker health check.
   • Add unit tests for address selection, normalization, collisions, ownership, updates, and deletion safety.

2. Add a Galaxy-layout netbox_dns role

   • defaults/main.yml
   • tasks/main.yml, composed from deployment and optional manual-sync tasks
   • handlers/main.yml
   • templates/config.yml.j2
   • meta/main.yml
   • README.md
   • Create a mode-restricted configuration directory and bind-mount its generated configuration read-only.
   • Deploy the container on the existing services network with no published host ports.
   • Declare image, health check, restart policy, pull behavior, and state explicitly.
   • Keep Cloudflare token, NetBox token, and webhook secret as injected variables.

3. Integrate it with NetBox deployment

   • Add the role to playbooks/netbox.yml after NetBox, tagged netbox_dns.
   • Configure its internal NetBox URL using the Docker service name, avoiding Traefik and Authelia.
   • Provision the NetBox webhook/event rule through its API if that automation is selected.
   • Ensure changes to devices, VMs, addresses, and interfaces trigger synchronization.

4. Add inventory configuration

   • Set unitix.it, record TTL, NetBox URL, network name, and reconciliation interval in appropriate host variables/defaults.
   • Add new credentials only as Vault-encrypted values supplied by the operator.
   • Do not reuse the broader existing token unless its scope is confirmed suitable.

5. Add Molecule coverage

   • Create molecule/netbox_dns using the Docker driver.
   • Run mock NetBox and Cloudflare APIs on an isolated test network.
   • Verify initial A/AAAA creation, webhook-triggered updates, stale-record deletion, manual sync, and startup reconciliation after restart.
   • Verify unmarked Cloudflare records remain untouched.
   • Verify duplicate names fail safely.
   • Assert healthy/running state, restart policy, no host ports, read-only config mount, and non-root process.
   • Pause after convergence and inspect/assert clean application logs.
   • Retain Molecule idempotence verification.

6. Extend CI

   • Lint the new application and Ansible role.
   • Syntax-check playbooks/netbox.yml.
   • Run the new Molecule scenario without Vault or external inventory.
   • Include unit tests for the synchronizer.
   • Validate with pre-commit, yamllint, and ansible-lint.

The main design decision is whether private IPv4 records should be public. That choice determines whether this can be a single Cloudflare reconciliation service or should also synchronize the existing internal AdGuard DNS.

github run

[33Fraise33]

/oc plan here are my replies

1. unitix.it is a completely new domain specifically for this use case
2. All devices and virtual-machines with a primary ipv4 and ipv6. Even if they are in planned/staged/offline. Decommissioned devices can be skipped.
3. yes exactly, this was also what I had in mind
4. publish internal addresses, as the ipv6 addresses are as much internal as well but they are globally routable
5. networking & services will be handled, I just need dns records
6. device naming is required to be unique in netbox
7. lowercase is indeed the best idea, if any special characters are included in the hostname, replace them with a dash
8. when the primary ip is gone, change the dns record as such
9. A dedicated netbox and cloudflare api token make perfect sense
10. Depends on the solution chosen if we make something ourselves it might make sense to publish this service for other people to use. I can still move it after the fact as well
11. event rules and webhooks should be set up by the maintainer and require information of the permissions and exact outbound webhook events in the readme
12. a container command makes most sense, it would also be good that this is run at container startup to verify the state of the dns zone.

[opencode-agent]

Confirmed design

Use Cloudflare as authoritative DNS for the new unitix.it zone and add a small, stateless synchronizer to this repository. Keeping the application here initially allows it to be deployed and tested with the Ansible role; its source can later move into a standalone public repository without changing the protocol or configuration model.

The synchronizer will:

• Publish non-proxied A and AAAA records for every NetBox device and virtual machine with a corresponding primary address.
• Include planned, staged, offline, active, failed, and inventory objects.
• Exclude NetBox’s standard decommissioning status and tolerate a custom decommissioned status.
• Publish private IPv4 and globally routable IPv6 addresses in public DNS.
• Remove an A or AAAA record when the corresponding primary address disappears, while retaining the other address family.
• Run a complete reconciliation at startup, periodically, after relevant webhooks, and through a manual container command.
• Never modify or delete records it does not own.

Implementation plan

1. Add the synchronization application

Create services/netbox-cloudflare-dns/ containing the Python application, packaging metadata, Dockerfile, README, and tests.

Implement:

• Paginated reads of:
  • /api/dcim/devices/
  • /api/virtualization/virtual-machines/
• Selection of only primary_ip4 and primary_ip6; strip NetBox CIDR prefixes before publishing.
• Name normalization:
  • Convert to lowercase.
  • Replace each run of characters outside a-z, 0-9, and - with -.
  • Collapse repeated dashes and trim leading/trailing dashes.
  • Reject empty labels or labels longer than 63 characters.
• Detection of collisions introduced by normalization. Although names are unique in NetBox, names such as host_1 and host-1 normalize identically. Abort reconciliation before making changes if any collision exists.
• Cloudflare zone lookup for unitix.it and paginated DNS record retrieval.
• Non-proxied A/AAAA records with a configurable TTL.
• An ownership comment such as managed-by=netbox-cloudflare-dns.
• A preflight phase that rejects malformed addresses, normalized-name collisions, and conflicts with unmarked records before applying any mutations.
• Creation, update, and deletion limited strictly to records carrying the ownership comment.
• Independent address-family reconciliation so removing primary_ip4 deletes only A, and removing primary_ip6 deletes only AAAA.
• Retries with bounded backoff for rate limits and transient NetBox/Cloudflare failures.
• Secret-free structured summaries of created, updated, unchanged, and deleted records.

Expose:

• serve as the default command.
• sync --once for manual reconciliation.
• configure-netbox-events for one-shot webhook/event-rule provisioning with a temporary maintainer credential.
• GET /healthz for Docker health checks.
• POST /webhooks/netbox, authenticated with a dedicated bearer secret.

The server will perform a full sync before becoming healthy, debounce webhook bursts into one full reconciliation, and perform a configurable periodic reconciliation to recover from missed webhooks.

2. Define webhook behavior and permissions

Have configure-netbox-events idempotently maintain one webhook and associated event rules through the NetBox API. The elevated maintainer token will only be supplied to this one-shot command and will not be stored in the running container.

Subscribe to create, update, and delete events for:

• dcim.device
• dcim.interface
• virtualization.virtualmachine
• virtualization.vminterface
• ipam.ipaddress

The webhook will send only inside the existing Docker services network to:

http://netbox-dns:8080/webhooks/netbox

The application does not rely on webhook payload contents; every accepted event schedules a complete reconciliation.

Document these exact permissions:

• Runtime NetBox account:
  • dcim.view_device
  • virtualization.view_virtualmachine
  • Any additional view permission proven necessary for primary-IP serialization, expected to be ipam.view_ipaddress.
• Maintainer account used by Ansible:
  • View/add/change/delete permissions for NetBox webhooks.
  • View/add/change/delete permissions for NetBox event rules.
• Cloudflare token:
  • Zone:Read
  • DNS:Edit
  • Restricted to unitix.it.
• Outbound requests:
  • NetBox REST reads.
  • Cloudflare zone and DNS-record API calls.
  • NetBox-originated HTTP POSTs to the internal webhook URL.

3. Add the netbox_dns Ansible role

Create the required Galaxy layout:

roles/netbox_dns/
├── defaults/main.yml
├── handlers/main.yml
├── meta/main.yml
├── README.md
├── tasks/
│   ├── main.yml
│   ├── deploy.yml
│   ├── configure_events.yml
│   └── sync.yml
└── templates/
    └── config.yml.j2

The role will:

• Assert that the three dedicated secrets are defined:
  • Runtime NetBox API token.
  • NetBox webhook secret.
  • Cloudflare zone-scoped token.
• Create a dedicated netbox-dns system user and obtain its numeric UID/GID.
• Create a restricted configuration directory and render the configuration with no_log protection and mode 0600.
• Deploy ghcr.io/33fraise33/netbox-cloudflare-dns:v1, with an image override for Molecule.
• Run under the dedicated numeric UID:GID.
• Join the existing external services network.
• Use http://netbox:8080 directly rather than Traefik or Authelia.
• Publish no host ports.
• Bind-mount configuration read-only.
• Declare state: healthy, restart policy, pull behavior, health check, and container command explicitly.
• Configure WUD to stay within major version v1.
• Restart/recreate the container when configuration changes.

Place event-rule configuration in a one-shot task using the maintainer token with no_log: true. The token will not appear in the rendered config or persistent container environment.

Place manual synchronization in a task tagged:

tags:
  - never
  - netbox_dns_sync

That task will execute sync --once inside the running container, allowing an operator to request reconciliation through the existing playbook without exposing an HTTP manual-sync endpoint.

4. Integrate with the NetBox playbook and inventory

Update playbooks/netbox.yml to run netbox_dns after netbox, tagged netbox_dns.

Add non-secret host-specific settings to playbooks/host_vars/beokpdcovm01.yml, including:

• Zone: unitix.it
• NetBox URL: http://netbox:8080
• Docker network: services
• Reconciliation interval
• Record TTL
• Excluded status slugs: decommissioning and decommissioned

Keep dedicated tokens and the webhook secret undefined until the operator supplies Vault-encrypted values. Do not reuse cloudflare_api_token or netbox_superuser_api_token.

The role README will also state that unitix.it must first exist as a Cloudflare zone and be delegated to the assigned Cloudflare nameservers.

5. Add automated application tests

Unit-test:

• Device and VM extraction.
• Inclusion of planned, staged, offline, failed, inventory, and active statuses.
• Exclusion of decommissioning/decommissioned objects.
• IPv4 and IPv6 CIDR removal.
• Lowercase and special-character normalization.
• Normalization collisions.
• Missing one or both primary addresses.
• A-only and AAAA-only deletion.
• Record creation and address changes.
• Ownership-marker enforcement.
• Conflicts with manually managed records.
• Pagination, retries, and Cloudflare rate limiting.
• Webhook authentication and debounce behavior.
• Startup and manual reconciliation.

6. Add Molecule coverage

Create molecule/netbox_dns/ using the Docker driver and repository-standard sequence, including idempotence.

Use mock NetBox and Cloudflare APIs on an isolated Docker network to verify:

• Startup reconciliation creates expected A and AAAA records.
• Private IPv4 addresses are published.
• Planned/staged/offline objects are included.
• Decommissioned objects are omitted.
• Webhook events trigger reconciliation.
• Removing one primary address removes only its record type.
• Manual sync --once works.
• Restarting the service performs another complete sync.
• Stale owned records are deleted.
• Unmarked records remain untouched.
• Normalized-name collisions fail before mutation.
• Event-rule configuration is idempotent.

Inspect and assert:

• Healthy/running state.
• Non-root process UID.
• Restart policy.
• No published ports.
• Membership in the test network.
• Read-only configuration mount.
• Clean runtime logs without warnings or tracebacks.

Include the required pause after convergence for runtime log inspection.

7. Add CI and image publication

Because no .github/workflows/ files currently exist, add workflows that:

• Run application unit tests.
• Build the container image.
• Run pre-commit, yamllint, and ansible-lint.
• Syntax-check playbooks/netbox.yml without Vault or external inventory.
• Run molecule test -s netbox_dns.
• Publish versioned images to GHCR on release tags, including a moving v1 major tag.

The application README and image should remain infrastructure-neutral so the service can later be moved to a dedicated public repository with minimal changes.

github run

[33Fraise33]

/oc build implement the approved plan

[opencode-agent]

Created PR #20

github run