dns-traefik-sync

Automatic DNS registration for Traefik-managed containers using Kerberos-authenticated RFC 2136 dynamic updates against a Samba Active Directory DNS server.

Polls the Traefik API, extracts Host() rules from docker-provider routers, and creates/removes A records in Samba AD DNS using GSS-TSIG authentication. No SSH. No passwords. No broad privilege.

How it works

Traefik API (/api/http/routers)
    └── docker provider routers with Host() rules
            └── filtered to target zone
                    └── diff against last known state
                            └── nsupdate -g (GSS-TSIG via Kerberos keytab)
                                    └── Samba AD DNS (vetinari)

On each poll cycle:

Fetches all routers from the Traefik API
Filters to docker provider only, extracts hostnames matching the target zone
Compares against state from the previous cycle
Adds A records for new hostnames, removes A records for gone hostnames
Renews the Kerberos ticket before each cycle

Requirements

Traefik with API enabled
Samba AD DC with a service account in DnsAdmins
Keytab for the service account stored as a Docker secret
Docker Swarm mode (for secrets)

Configuration

All configuration via environment variables:

Variable	Default	Description
TRAEFIK_API	http://<TARGET_IP>:8080	Traefik API base URL
DNS_SERVER	<DNS_SERVER_IP>	Samba AD DNS server IP
DNS_ZONE	<DNS_ZONE>	Zone to manage records in
TARGET_IP	<TARGET_IP>	IP address for created A records
TTL	300	TTL for created records (seconds)
POLL_INTERVAL	60	Poll interval (seconds)
KEYTAB	/run/secrets/dns-updater-keytab	Path to Kerberos keytab
KRB_PRINCIPAL	dns-updater@	Kerberos principal
STATE_FILE	/tmp/dns_state.json	State persistence path

Deployment

See docs/deployment.md for full setup instructions. See docs/operations.md for day-to-day operational guidance.

Security model

Service account scoped to DnsAdmins only
Keytab stored as a Docker secret, never on disk
GSS-TSIG: Kerberos mutual authentication, updates signed and verified by the KDC
No SSH, no HTTP webhooks, no plaintext credentials
Container runs as nobody

Limitations

A records only (no CNAME, no AAAA)
Single target IP (all records point to the same host)
Single zone
On restart, re-syncs from Traefik - safe and idempotent

Changelog

See CHANGELOG.md

2.9 KiB Raw Blame History