https://github.com/maxfield-allison/dnsweaver
Automatic DNS management for Docker containers with multi-provider support
https://github.com/maxfield-allison/dnsweaver
automation container-orchestration containers devops dns dns-automation dns-management docker docker-labels docker-swarm dynamic-dns go golang homelab infrastructure-as-code microservices self-hosted service-discovery technitium traefik
Last synced: 19 days ago
JSON representation
Automatic DNS management for Docker containers with multi-provider support
- Host: GitHub
- URL: https://github.com/maxfield-allison/dnsweaver
- Owner: maxfield-allison
- License: mit
- Created: 2026-01-07T17:16:44.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-09T03:41:42.000Z (21 days ago)
- Last Synced: 2026-03-09T09:05:19.603Z (21 days ago)
- Topics: automation, container-orchestration, containers, devops, dns, dns-automation, dns-management, docker, docker-labels, docker-swarm, dynamic-dns, go, golang, homelab, infrastructure-as-code, microservices, self-hosted, service-discovery, technitium, traefik
- Language: Go
- Homepage: https://github.com/maxfield-allison/dnsweaver
- Size: 785 KB
- Stars: 16
- Watchers: 0
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# dnsweaver
[](https://github.com/maxfield-allison/dnsweaver/releases)
[](https://hub.docker.com/r/maxamill/dnsweaver)
[](LICENSE)
[](go.mod)
**Automatic DNS record management for Docker and Kubernetes workloads with multi-provider support.**
dnsweaver watches Docker events and Kubernetes resources to automatically create and delete DNS records. Unlike single-provider tools, dnsweaver supports **split-horizon DNS**, **multiple DNS providers** simultaneously, and works across both **Docker** and **Kubernetes** platforms.
📚 **[Full Documentation](https://maxfield-allison.github.io/dnsweaver/)**
## Features
- 🔀 **Multi-Provider Support** — Route different domains to different DNS providers
- 🌐 **Split-Horizon DNS** — Internal and external records from the same container labels
- 🐳 **Docker & Swarm Native** — Works with standalone Docker and Docker Swarm clusters
- ☸️ **Kubernetes Support** — Watches Ingress, IngressRoute, HTTPRoute, and Service resources
- 🏗️ **Multi-Instance Safe** — Run multiple dnsweaver instances on the same DNS zone without conflicts
- 🔒 **Socket Proxy Compatible** — Connect via TCP to a Docker socket proxy for improved security
- 🏷️ **Traefik Integration** — Parses `traefik.http.routers.*.rule` labels to extract hostnames
- 📊 **Observable** — Prometheus metrics, health endpoints, structured logging
- 🔑 **Secrets Support** — Docker secrets and Kubernetes Secrets via `_FILE` suffix variables
## Supported Providers
| Provider | Record Types | Notes |
|----------|--------------|-------|
| [Technitium](https://maxfield-allison.github.io/dnsweaver/providers/technitium/) | A, AAAA, CNAME, SRV, TXT | Full-featured self-hosted DNS |
| [Cloudflare](https://maxfield-allison.github.io/dnsweaver/providers/cloudflare/) | A, AAAA, CNAME, TXT | With optional proxy support |
| [RFC 2136](https://maxfield-allison.github.io/dnsweaver/providers/rfc2136/) | A, AAAA, CNAME, SRV, TXT | BIND, Windows DNS, PowerDNS, Knot |
| [Pi-hole](https://maxfield-allison.github.io/dnsweaver/providers/pihole/) | A, AAAA, CNAME | API or file mode |
| [dnsmasq](https://maxfield-allison.github.io/dnsweaver/providers/dnsmasq/) | A, AAAA, CNAME | File-based configuration |
| [Webhook](https://maxfield-allison.github.io/dnsweaver/providers/webhook/) | Any | Custom integrations |
## Quick Start
### Installation
```bash
# Docker Hub
docker pull maxamill/dnsweaver:latest
# GitHub Container Registry
docker pull ghcr.io/maxfield-allison/dnsweaver:latest
```
### Basic Example
```yaml
services:
dnsweaver:
image: maxamill/dnsweaver:latest
restart: unless-stopped
environment:
- DNSWEAVER_INSTANCES=internal-dns
- DNSWEAVER_INTERNAL_DNS_TYPE=technitium
- DNSWEAVER_INTERNAL_DNS_URL=http://dns.internal:5380
- DNSWEAVER_INTERNAL_DNS_TOKEN_FILE=/run/secrets/technitium_token
- DNSWEAVER_INTERNAL_DNS_ZONE=home.example.com
- DNSWEAVER_INTERNAL_DNS_RECORD_TYPE=A
- DNSWEAVER_INTERNAL_DNS_TARGET=10.0.0.100
- DNSWEAVER_INTERNAL_DNS_DOMAINS=*.home.example.com
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
secrets:
- technitium_token
secrets:
technitium_token:
external: true
```
### How It Works
```mermaid
flowchart LR
A["Docker Events
(start/stop)"] --> B["dnsweaver
(matching)"]
B --> C["DNS Providers
(A/CNAME/SRV)"]
```
1. A container starts with a Traefik label:
```yaml
labels:
- "traefik.http.routers.myapp.rule=Host(`myapp.home.example.com`)"
```
2. dnsweaver extracts the hostname and matches it against configured provider domain patterns
3. The matching provider creates the DNS record:
- **A record**: `myapp.home.example.com → 10.0.0.100`
- **CNAME**: `myapp.example.com → proxy.example.com`
4. When the container stops, the DNS record is automatically cleaned up
## Documentation
| Topic | Description |
|-------|-------------|
| [Getting Started](https://maxfield-allison.github.io/dnsweaver/getting-started/) | Installation and first configuration |
| [Configuration](https://maxfield-allison.github.io/dnsweaver/configuration/environment/) | Environment variables reference |
| [Providers](https://maxfield-allison.github.io/dnsweaver/providers/) | Provider-specific setup guides |
| [Kubernetes](https://maxfield-allison.github.io/dnsweaver/deployment/kubernetes/) | Kubernetes deployment with Helm/Kustomize |
| [Split-Horizon DNS](https://maxfield-allison.github.io/dnsweaver/deployment/split-horizon/) | Internal + external records |
| [Docker Swarm](https://maxfield-allison.github.io/dnsweaver/deployment/swarm/) | Swarm deployment guide |
| [Observability](https://maxfield-allison.github.io/dnsweaver/observability/) | Metrics, logging, and health checks |
| [FAQ](https://maxfield-allison.github.io/dnsweaver/faq/) | Common questions and troubleshooting |
## Kubernetes Quick Start
Deploy dnsweaver to watch Kubernetes resources for DNS management:
```bash
# Using Kustomize
kubectl apply -k https://github.com/maxfield-allison/dnsweaver/deploy/kustomize/base
# Using Helm
helm install dnsweaver deploy/helm/dnsweaver/ \
--namespace dnsweaver --create-namespace
```
dnsweaver automatically detects hostnames from Ingress, IngressRoute (Traefik), HTTPRoute (Gateway API), and Service resources. Use `dnsweaver.dev/*` annotations for per-resource overrides:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: my-app
annotations:
dnsweaver.dev/record-type: "A"
dnsweaver.dev/target: "10.0.0.100"
spec:
rules:
- host: app.example.com
```
See the [Kubernetes deployment guide](https://maxfield-allison.github.io/dnsweaver/deployment/kubernetes/) for full configuration.
## Split-Horizon DNS Example
Manage internal and external DNS from the same container labels:
```yaml
environment:
- DNSWEAVER_INSTANCES=internal,external
# Internal: Technitium → private IP
- DNSWEAVER_INTERNAL_TYPE=technitium
- DNSWEAVER_INTERNAL_RECORD_TYPE=A
- DNSWEAVER_INTERNAL_TARGET=10.0.0.100
- DNSWEAVER_INTERNAL_DOMAINS=*.example.com
# External: Cloudflare → tunnel CNAME
- DNSWEAVER_EXTERNAL_TYPE=cloudflare
- DNSWEAVER_EXTERNAL_RECORD_TYPE=CNAME
- DNSWEAVER_EXTERNAL_TARGET=tunnel.example.com
- DNSWEAVER_EXTERNAL_DOMAINS=*.example.com
```
With this configuration, when `app.example.com` starts:
- Internal DNS → `A` record → `10.0.0.100`
- External DNS → `CNAME` record → `tunnel.example.com`
## Contributing
Contributions are welcome! See [CONTRIBUTING](https://maxfield-allison.github.io/dnsweaver/contributing/) for guidelines.
## License
[MIT License](LICENSE)