Updated8 hours ago

LanguageGo

Setup difficultyModerate

Stars: 207
Port: 8080 (health, readiness, and metrics listener)

Docker

maxamill/dnsweaver

Install with Docker Compose

What is dnsweaver?

dnsweaver is a DNS automation tool built for self-hosted labs. It monitors container labels, Kubernetes objects, Proxmox virtual machines, and Incus instances to automatically create and delete DNS records across many providers. The software handles split-horizon setups so one label set produces both private and public records. It ships as a standalone Go binary with multi-architecture Docker images, a Helm chart, and Kustomize manifests. All settings use environment variables and integrate with Docker secrets or Kubernetes Secrets.

Should you self-host dnsweaver?

dnsweaver scores 50/100 on selfhost.directory (how scoring works) and ranks #25 of 41 in DNS. It has 207 GitHub stars.

It shipped 17 stable releases in the past year. The latest, v3.2.2, came out on 26 October 2026. New versions land roughly every 5 days.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is MIT-licensed and written mostly in Go.

Its closest alternative on selfhost.directory is Pi-hole (87/100, 61 522 stars). It scores higher overall, so compare the two before you pick. See dnsweaver vs Pi-hole side by side.

Features

Docker socket proxy support
Dry Run Mode
Dynamic target resolution
Existing record adoption
Hardened TLS configuration
Incus auto-DNS
Multi-instance with separate ownership namespacesDoes not provide leader election or active-active HA
Multi-provider DNS management
Prometheus metrics and health endpoints
Proxmox VE auto-DNS
Secrets Management
Seven source integrations
Single static Go binary
Split-Horizon DNS
Standalone mode (no Docker/Kubernetes)

How to install dnsweaver

Install dnsweaver with Docker Compose

Docker Compose

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

Example with Technitium provider and Docker secrets

Install dnsweaver with Kubernetes

kubectl apply -k https://github.com/maxfield-allison/dnsweaver/deploy/kustomize/base

Kustomize base deployment with RBAC

Install dnsweaver with Linux

Linux host with supported DNS provider and/or Proxmox/Incus

DNSWEAVER_PLATFORM=none DNSWEAVER_SOURCES=proxmox DNSWEAVER_PROXMOX_URL=https://pve.example.com:8006/ DNSWEAVER_PROXMOX_TOKEN_ID=user@pve!dnsweaver DNSWEAVER_PROXMOX_TOKEN_SECRET_FILE=/etc/dnsweaver/pve-token DNSWEAVER_INSTANCES=technitium DNSWEAVER_TECHNITIUM_TYPE=technitium DNSWEAVER_TECHNITIUM_URL=http://127.0.0.1:5380 DNSWEAVER_TECHNITIUM_TOKEN_FILE=/etc/dnsweaver/technitium-token DNSWEAVER_TECHNITIUM_ZONE=example.com

Run as bare binary on host, VM, or LXC with no container runtime

Install dnsweaver with Helm

helm install dnsweaver oci://ghcr.io/maxfield-allison/charts/dnsweaver
--namespace dnsweaver --create-namespace
--set config.instances="internal-dns"
--set config.providers.internal-dns.type=technitium
--set config.providers.internal-dns.url=http://dns.internal:5380
--set config.providers.internal-dns.zone=home.example.com
--set config.providers.internal-dns.recordType=A
--set config.providers.internal-dns.target=192.0.2.100
--set config.providers.internal-dns.domains="*.home.example.com"

Official Helm chart from ghcr.io/maxfield-allison/charts/dnsweaver

FAQ

Can dnsweaver do load balancing / round-robin?

dnsweaver creates single records per hostname. For load balancing, use your reverse proxy (Traefik, Nginx), DNS provider's native round-robin if supported, or multiple A records with a custom provider implementation.

Will you add support for [DNS Provider X]?

Check existing issues on GitHub. If not requested, open a feature request. The webhook provider can be used as a workaround for unsupported providers.

Can I preview changes without applying them?

Yes, use dry-run mode with DNSWEAVER_DRY_RUN=true. Changes are logged but not applied to DNS providers.

What happens if a DNS provider is unavailable?

dnsweaver logs the error, continues processing other providers, and retries on the next reconciliation cycle. Records in unavailable providers won't be updated until connectivity is restored.

How often does dnsweaver check for changes?

Docker and Kubernetes events are processed in real-time via event streams and watch APIs. Periodic reconciliation runs every 60 seconds by default to catch any missed events. File sources use a configurable poll interval.

How do I set up dual-stack DNS (A + AAAA)?

Configure two provider instances with the same domain patterns but different record types and targets (A for IPv4, AAAA for IPv6). Both instances can point to the same DNS server.

Why aren't my container labels being detected?

Common causes: Swarm mode requires labels on the service (not deploy labels), label format issues with Traefik Host rule syntax, or hostname not matching DOMAINS patterns. Enable debug logging with DNSWEAVER_LOG_LEVEL=debug.

Can dnsweaver manage existing DNS records?

By default, dnsweaver only manages records it creates (tracked via ownership TXT records). To adopt existing records, set DNSWEAVER_ADOPT_EXISTING=true. Test with DRY_RUN=true first.

Can I run dnsweaver without Docker or Kubernetes?

Yes. Set DNSWEAVER_PLATFORM=none (alias standalone) to run dnsweaver as a bare binary on a host, VM, or LXC with no container runtime. You must configure at least one non-container source such as Proxmox VE, Incus, or a file-discovery source.

Can I run dnsweaver on both Docker and Kubernetes at the same time?

Yes. Set DNSWEAVER_PLATFORM=both to watch Docker events and Kubernetes resources simultaneously. This is useful for mixed environments or gradual migrations between platforms.

How does dnsweaver work in Kubernetes?

dnsweaver watches Kubernetes resources (Ingress, IngressRoute, HTTPRoute, Service) for hostname information and creates DNS records automatically. It uses a ServiceAccount with RBAC permissions and deploys as a single-replica Deployment via Helm or Kustomize.

Do I need to run dnsweaver on every Docker host?

No. dnsweaver connects to the Docker socket (or socket proxy) and watches events cluster-wide in Swarm mode. Run a single instance on a manager node.

What's the difference between dnsweaver and external-dns?

external-dns is primarily designed for Kubernetes and cloud DNS providers. dnsweaver reads from seven sources (Traefik, Caddy, nginx-proxy, native labels, Kubernetes, Proxmox VE, Incus) and writes to twelve providers with a focus on self-hosted DNS providers and split-horizon DNS.