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

• 🔀 Multi-Provider Support — Route different domains to different DNS providers
• 🌐 Split-Horizon DNS — Internal and external records from the same container labels
• 🐳 Docker & Swarm — Works with standalone Docker and Docker Swarm clusters
• ☸️ Kubernetes Native — Watches Ingress, IngressRoute, HTTPRoute, and Service resources via Helm or Kustomize
• 🏗️ 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

# Docker Hub
docker pull maxamill/dnsweaver:latest

# GitHub Container Registry
docker pull ghcr.io/maxfield-allison/dnsweaver:latest

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=192.0.2.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

flowchart LR
    A["Docker Events"] --> B["dnsweaver<br/>(matching)"]
    D["Kubernetes Resources"] --> B
    B --> C["DNS Providers<br/>(A/CNAME/SRV)"]

1. A container starts with a Traefik label (or a Kubernetes Ingress/HTTPRoute is created):

   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 → 192.0.2.100
   • CNAME: myapp.example.com → proxy.example.com

4. When the container stops (or the Kubernetes resource is deleted), the DNS record is automatically cleaned up

Deploy dnsweaver to watch Kubernetes resources for DNS management:

# 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:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  annotations:
    dnsweaver.dev/record-type: "A"
    dnsweaver.dev/target: "192.0.2.100"
spec:
  rules:
    - host: app.example.com

See the Kubernetes deployment guide for full configuration.

Manage internal and external DNS from the same container labels:

environment:
  - DNSWEAVER_INSTANCES=internal,external

  # Internal: Technitium → private IP
  - DNSWEAVER_INTERNAL_TYPE=technitium
  - DNSWEAVER_INTERNAL_RECORD_TYPE=A
  - DNSWEAVER_INTERNAL_TARGET=192.0.2.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 → 192.0.2.100
• External DNS → CNAME record → tunnel.example.com

Contributions are welcome! See CONTRIBUTING for guidelines.

MIT License