Skip to content
Projects

maxfield-allison/dnsweaver has 224 GitHub stars and 24 forks. GitHot measured 0 stars in 24 hours and +4 in 7 days. Last checked 2026-11-16 23:59 UTC. Last push 2026-11-14.

How these counts are measured

What you can do

  • 🔀 Multi-Provider Support — Route domains to matching providers, with optional workload instance selection in the unreleased source
  • 🌐 Split-Horizon DNS — Internal and external records from the same container labels
  • 🧩 Seven Sources — Traefik, Caddy, nginx-proxy, native labels, Kubernetes, Proxmox VE, and Incus, in one binary. See Supported Sources
  • 🏗️ Separate ownership namespaces — Use distinct instance IDs and non-conflicting record scopes for multiple dnsweaver processes; this does not provide leader election or active-active HA

Measured star growth

in 24h
0
in 7 days
+4
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Automatic DNS records for containers, VMs & clusters. Seven sources (Traefik, Caddy, nginx-proxy, native labels, Kubernetes, Proxmox VE, Incus) and twelve DNS providers including Technitium, Pi-hole and AdGuard Home. Split-horizon out of the box. external-dns for the homelab.

Self-hosted

README.md

Original

dnsweaver — Automatic DNS records for containers, VMs and clusters

dnsweaver

CI Release Docker Pulls License Go Version

Automatic DNS records for containers, VMs & clusters.

dnsweaver reads hostnames from seven sources and writes records to twelve DNS providers. A container starts with a Traefik label or a Proxmox VM boots, and the record appears; when they go away, so does it. Internal and external records come from the same labels, so split-horizon costs nothing extra.

📚 Full Documentation

Why dnsweaver?

Think of dnsweaver as external-dns for the homelab. Where most tools solve a slice of the problem, dnsweaver covers the parts self-hosters actually run into:

  • It does Proxmox. Auto-create A records for VMs and LXCs from the PVE API. Almost no other DNS automation tool offers it.
  • It speaks self-hosted DNS. First-class Technitium, Pi-hole, AdGuard Home, and dnsmasq support. Not an afterthought, and not alpha.
  • It's multi-source. Traefik, Caddy, nginx-proxy, native labels, Kubernetes, Proxmox VE, and Incus in one binary. Run one or all of them at once. external-dns is Kubernetes-only.
  • It does split-horizon out of the box. Internal and external records from the same labels. Route private hostnames to Technitium and public ones to Cloudflare simultaneously.
  • It's a single static Go binary. Multi-arch (amd64/arm64), with no separate application runtime or sidecar required.

If you manage a homelab with Traefik, Proxmox, and a self-hosted resolver and you're still creating DNS records by hand, dnsweaver is built for you.

Features

  • 🔀 Multi-Provider Support — Route domains to matching providers, with optional workload instance selection in the unreleased source
  • 🌐 Split-Horizon DNS — Internal and external records from the same container labels
  • 🧩 Seven Sources — Traefik, Caddy, nginx-proxy, native labels, Kubernetes, Proxmox VE, and Incus, in one binary. See Supported Sources
  • 🏗️ Separate ownership namespaces — Use distinct instance IDs and non-conflicting record scopes for multiple dnsweaver processes; this does not provide leader election or active-active HA
  • 🔒 Socket Proxy Compatible — Connect via TCP to a Docker socket proxy for improved security
  • 🛡️ Hardened TLS — Unified per-instance TLS controls (custom CA, mTLS client certs, SNI override, configurable min version; TLS 1.2 floor by default) for every HTTP-based provider and the Proxmox and Incus sources
  • 📊 Observable — Prometheus metrics, health endpoints, structured logging
  • 🔑 Secrets Support — Docker secrets and Kubernetes Secrets via _FILE suffix variables

Supported Sources

Sources are where hostnames come from. Enable any combination with DNSWEAVER_SOURCES.

Source Reads Runs over
traefik traefik.http.routers.*.rule labels, plus Traefik dynamic config files Docker, Swarm, Incus
caddy caddy / caddy_<n> labels from caddy-docker-proxy Docker, Swarm, Incus
nginx-proxy VIRTUAL_HOST labels from jwilder/nginx-proxy Docker, Swarm, Incus
dnsweaver Native dnsweaver.* labels for explicit record configuration Docker, Swarm, Incus
kubernetes Ingress, IngressRoute, HTTPRoute, and Service resources Kubernetes
proxmox PVE API: QEMU VMs via guest agent, and LXC containers Proxmox VE
incus Incus API: system containers and VMs, local socket or remote HTTPS Incus

Supported Providers

Providers are where records get written. Run several at once to split internal and external DNS.

Provider Record Types Notes
Technitium A, AAAA, CNAME, SRV, TXT Full-featured self-hosted DNS
Cloudflare A, AAAA, CNAME, SRV, TXT With optional proxy support
OVHcloud A, AAAA, CNAME, SRV, TXT Public DNS for OVH-hosted domains
RFC 2136 A, AAAA, CNAME, SRV, TXT HMAC-TSIG-compatible BIND, PowerDNS, Knot, Technitium; Windows secure updates are not supported
PowerDNS A, AAAA, CNAME, SRV, TXT Native Authoritative HTTP API
Pi-hole A, CNAME API or file mode
AdGuard Home A, AAAA, CNAME DNS rewrite management
OPNsense A, AAAA Unbound or Dnsmasq host overrides via REST API
pfSense A, AAAA Unbound or Dnsmasq host overrides via REST API (community pfSense-pkg-RESTAPI)
UniFi Network A, AAAA, CNAME, SRV, TXT DNS policies via the official Integration API (Network 10.6+, served by a UniFi gateway)
dnsmasq A, CNAME File-based configuration
Webhook Any Custom integrations

Quick Start

Before upgrading

In v3.0.0, health, readiness and metrics listen on loopback by default. Remote scrapers and probes need an explicit network listener and access restrictions. See the management-listener migration guide. The bundled container and Kubernetes probes use local checks.

The same changes reject invalid TLS settings and unreadable credential files instead of falling back. Remote dnsmasq updates require an SFTP server with the OpenSSH POSIX rename extension; see the provider requirements. Check the release notes for your image tag before applying these settings.

Installation

# Docker Hub
docker pull maxamill/dnsweaver:latest

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

Basic Example

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

How It Works

flowchart LR
    subgraph sources["7 sources"]
        direction TB
        A["traefik · caddy · nginx-proxy · dnsweaver<br/>labels on Docker, Swarm, Incus"]
        D["kubernetes<br/>Ingress · IngressRoute · HTTPRoute · Service"]
        P["proxmox · incus<br/>API: VMs · LXC · system containers"]
    end

    subgraph engine["dnsweaver"]
        direction TB
        W["Watch<br/>events"] --> M["Match hostname<br/>to domain patterns"] --> R["Reconcile<br/>desired vs. live"]
    end

    subgraph providers["12 providers · split-horizon"]
        direction TB
        INT["Internal instance<br/>e.g. technitium · pi-hole · adguard"]
        EXT["External instance<br/>e.g. cloudflare · ovhcloud"]
    end

    A --> W
    D --> W
    P --> W
    R -->|create / update / delete| INT
    R -->|create / update / delete| EXT
  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

Documentation

Topic Description
Getting Started Installation and first configuration
Configuration Environment variables reference
Providers Provider-specific setup guides
Sources All seven sources, what each reads, and the capability matrix
Kubernetes Kubernetes deployment with Helm/Kustomize
Proxmox VE Auto-DNS for VMs and LXC containers
Incus Auto-DNS for system containers and VMs
Split-Horizon DNS Internal + external records
Docker Swarm Swarm deployment guide
Observability Metrics, logging, and health checks
FAQ Common questions and troubleshooting

TLS Configuration

Every HTTP-based provider (Technitium, AdGuard Home, Cloudflare, OVHcloud, PowerDNS, Pi-hole, OPNsense, pfSense, Webhook) and the Proxmox and Incus sources share a single TLS configuration surface:

Env key (per instance) Purpose
DNSWEAVER_<NAME>_TLS_CA_FILE Trust a private CA bundle (PEM)
DNSWEAVER_<NAME>_TLS_CERT_FILE / _TLS_KEY_FILE Present a client certificate (mTLS)
DNSWEAVER_<NAME>_TLS_SERVER_NAME Override SNI / hostname verification
DNSWEAVER_<NAME>_TLS_SKIP_VERIFY Disable verification (development only)
DNSWEAVER_<NAME>_TLS_MIN_VERSION 1.2 (default) or 1.3

The Proxmox and Incus sources use the same keys under DNSWEAVER_PROXMOX_TLS_* and DNSWEAVER_INCUS_TLS_* (Incus adds DNSWEAVER_INCUS_TLS_PIN_SHA for certificate pinning). The legacy *_INSECURE_SKIP_VERIFY and DNSWEAVER_PROXMOX_VERIFY_TLS variables are still accepted but emit a deprecation warning at startup — migrate to the unified TLS_SKIP_VERIFY keys. See the Environment Reference and SECURITY.md for full details and recipes.

Mounting certs? The container drops privileges to uid/gid 1000, so cert/key files must be readable by that user — a root:root 0600 key yields permission denied. See TLS Certificate File Permissions.

Kubernetes Quick Start

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.

Split-Horizon DNS Example

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

Contributing

Contributions are welcome! See CONTRIBUTING for guidelines.

Support

dnsweaver is free and MIT-licensed. If it saves you time, you can support ProbablyFine through GitHub Sponsors. Sponsorship helps cover code-signing and other development costs. It doesn't buy priority support, roadmap influence, or promised features.

Star History

If dnsweaver saves you time, a ⭐ helps others find it.

License

MIT License