This project provides a lightweight, automatic DNS service for Docker containers using CoreDNS and a Python event listener.
It dynamically maps container hostnames and IP addresses into CoreDNS, supports reverse DNS (PTR) lookups automatically, and allows you to specify for what interfaces you want to create DNS records.
✅ Automatic DNS Record Management
- Every container attached to a matched network (see
NETWORK_PREFIXbelow) gets a fully-qualified domain name (FQDN) automatically added to/etc/coredns/hosts. - CoreDNS automatically provides forward (A) and reverse (PTR) resolution.
- A matched container that's currently stopped still resolves to its statically assigned address, if it has one. Docker clears the runtime IP when a container stops but keeps the configured one, so an on-demand container resolves correctly before anything starts it. Only an attachment with no static address configured falls back to the
FALLBACK_IPplaceholder. - Containers with no matched network get no entry at all — they don't resolve, rather than resolving to a placeholder.
✅ Event-Based Updates
- The DNS host file updates within about a second of a Docker event (start, stop, destroy, etc.).
- No need for polling — it’s lightweight and real-time.
- A burst of events (a host booting, a compose stack coming up) is one rewrite, not one per event.
- If the event stream drops, the updater re-subscribes and rewrites the file in full. If the updater itself dies, the container exits so a restart policy brings it back, rather than CoreDNS serving a file that no longer follows Docker.
✅ Multi-Network Support
- Supports one or more Docker network prefixes.
- Example:
NETWORK_PREFIX=macvlan,dmzwill include all containers in any network that starts withmacvlanordmz.
✅ Custom Domain
- Easily define your internal domain via the
DOMAINenvironment variable. - Example:
DOMAIN=docker.local. - If no variable is entered the default value 'docker.local' will be used.
✅ Reverse DNS Support
- CoreDNS automatically provides reverse (PTR) lookups for all listed IPs.
✅ No DNS forwarding
- CoreDNS will not forward requests to upstream. Use this only for automated Docker container resolving.
docker-coredns/
├── Dockerfile # Builds the CoreDNS + Python container
├── Corefile # CoreDNS configuration
├── scripts/update_hosts.py # Watches Docker events and updates hosts file
├── entrypoint.sh # Runs the updater and CoreDNS; ends the container when either exits
├── smoke_test.py # Address-selection logic against a fake Docker client
├── smoke_test_live.py # The built image serving real DNS against a real Docker daemon
└── docker-compose.yml # Example compose setup
Environment variables:
| Variable | Default | Description | Example |
|---|---|---|---|
DOMAIN |
docker.local |
DNS suffix for containers | docker.local |
NETWORK_PREFIX |
macvlan |
Comma-separated list of Docker network name prefixes to include | macvlan, bridge |
FALLBACK_IP |
0.0.0.0 |
Placeholder IP for a matched container with no address at all — neither running nor statically assigned. A stopped container with a static IP uses that instead. | 0.0.0.0 |
DEBOUNCE_SECONDS |
1 |
How long to wait after a Docker event before rewriting the hosts file, so that a burst of events costs one rewrite. Each rewrite lists and inspects every container. | 1 |
- On startup, the Python script scans all Docker containers (running and stopped).
- For each container connected to a network matching one of the configured
NETWORK_PREFIXvalues (e.g.macvlan*,bridge*), it writes an entry to/etc/coredns/hosts. Containers with no matching network are skipped entirely — no entry, no resolution. - CoreDNS reads this file using the
hostsplugin and automatically serves both:
- Forward lookup:
container.docker.local → 192.168.10.100 - Reverse lookup:
192.168.10.100 → container.docker.local
- The script subscribes to Docker events (container
start,die,destroy; networkconnect,disconnect) and rewrites the hosts file whenever containers change,DEBOUNCE_SECONDSafter the first event of a burst. Other events, such as healthcheckexec_*events, are ignored. CoreDNS itself reloads that file every 2 seconds (seeCorefile), so a change is served within a few seconds, not synchronously. - The file is written to a temporary name and renamed into place, so a reload never reads a half-written file.
entrypoint.shruns the script and CoreDNS side by side and ends the container if either one exits. Use a restart policy (restart: alwaysin the example) so they come back together.
Forward lookup:
dig @192.168.10.10 container.docker.localReverse lookup:
dig -x 192.168.10.100 @192.168.10.10Two smoke tests, both stdlib-only:
smoke_test.pyrunsupdate_hosts.pyagainst a fake Docker client: runtime address, the static-address fallback for stopped containers,FALLBACK_IP, the network prefix filter and the hosts-file line format; that the file is replaced by rename rather than rewritten in place; and that irrelevant events request nothing, a burst of 80 events is one rewrite, and a failed rewrite is retried.smoke_test_live.py IMAGEruns the built image against a real Docker daemon on a throwaway network and queries it over DNS: A and PTR records for a container that existed at startup, a record for one started later (the event listener), and a stopped container still resolving to its static address. It then checks that the updater's output reaches the container log, thatdocker stopexits 0 promptly, and that killing the updater ends the container. It createscdsmoke-*containers and network, uses the subnet172.31.254.0/24, and removes them afterwards.
docker build -t docker-coredns:dev .
docker run --rm -v "$PWD/smoke_test.py:/smoke_test.py:ro" docker-coredns:dev python3 /smoke_test.py
python3 smoke_test_live.py docker-coredns:devBoth workflows run them: pr-validate.yml on pull requests, and build.yml before pushing the
image, so a change that breaks the records at runtime never reaches :latest. Building alone proves
nothing here, and coredns/coredns:latest is a floating tag that can change with no pull request.