coredns-netbox/GEMINI.md

CoreDNS NetBox Sync

This project automates the generation of DNS zone files for CoreDNS (or BIND) by synchronizing data from NetBox. It fetches IPAM data (active IPs with DNS names) and DNS plugin entries to maintain up-to-date Forward and Reverse zones.

Project Overview

• Core Logic: A Python script (sync.py) runs in a continuous loop, fetching data from the NetBox API.
• Output: Generates standard DNS zone files compatible with CoreDNS and BIND.
• Resilience: If the NetBox API is unreachable, the script preserves existing zone files to prevent DNS outages (NXDOMAIN).
• Environment: designed to run as a Docker container, sharing the generated zone files via a volume with the CoreDNS container.

Key Files

• sync.py: The main application logic. Handles API authentication, data fetching, data formatting, and file writing.
• Dockerfile: Defines the minimal Python 3.11 Alpine-based image for running the script.
• .env.example: Template for required environment variables.
• README.md: Official project documentation (German).

Configuration

Configuration is handled entirely via environment variables.

Variable	Required	Default	Description
NETBOX_URL	Yes	-	Full URL to NetBox (e.g., http://netbox.local).
NETBOX_TOKEN	Yes	-	API Token (Read-only sufficient).
ZONE_NAME	No	klenzel.net	The DNS zone to manage.
REVERSE_ZONE_NAME	No	172.in-addr.arpa	The reverse lookup zone.
REFRESH_INTERVAL	No	600	Sync interval in seconds.
OUTPUT_FILE_FWD	No	/zones/db.klenzel.net	Path for the forward zone file.
OUTPUT_FILE_REV	No	/zones/db.reverse.arpa	Path for the reverse zone file.
FALLBACK_NS_HOSTNAME	No	fks-01-cl-cdns	Fallback NS hostname if none in NetBox.
FALLBACK_NS_IP	No	172.25.16.152	Fallback NS IP for glue record.

Development & Usage

Building the Image

docker build -t local/dns-sync .

Running Locally (for testing)

1. Create a .env file with your NetBox credentials.
2. Run the container:

docker run -d \
  --name dns-sync-test \
  --env-file .env \
  -v $(pwd)/zones:/zones \
  local/dns-sync

(Ensure the ./zones directory exists locally before running)

Logic Details

• IPAM Fetch: Queries /api/ipam/ip-addresses/?status=active&dns_name__n=&limit=0.
• Plugin Fetch: Queries /api/plugins/netbox-dns/records/?zone__name={ZONE_NAME}&limit=0.
• Nameserver Logic:
  • If NetBox has NS records for the zone, the first one is used as the Primary SOA.
  • If no NS records exist, it falls back to FALLBACK_NS_HOSTNAME and creates a Glue Record (A record) for it to ensure the zone is valid.