dnsweaver

dnsweaver can be deployed in several environments depending on your complexity and availability requirements. Choose the method that best fits your infrastructure:

• Docker Compose: The simplest deployment for single-host environments. Recommended for getting started and development.
• Docker Swarm: A production deployment for multi-node Docker clusters requiring high availability.
• Kubernetes: Deploy via Helm or Kustomize. This mode watches Ingress, IngressRoute, HTTPRoute, and Service resources.
• Split-Horizon DNS: A specialized configuration to manage internal and external DNS records using the same container labels.

dnsweaver automates DNS record management by connecting Sources to Providers.

• Sources: Where hostnames are discovered (e.g., Traefik labels, Kubernetes Ingress, Proxmox VMs, or Incus containers).
• Engine: The core logic that watches for events from sources, matches hostnames to domain patterns, and reconciles the desired state against the live DNS records.
• Providers: Where the records are actually written (e.g., Technitium, Cloudflare, Pi-hole).

By using multiple providers simultaneously, you can implement Split-Horizon DNS, where the same container labels trigger both internal (e.g., Technitium) and external (e.g., Cloudflare) DNS updates.

dnsweaver follows a specific hierarchy to determine if an existing record should be 'adopted' (claimed) by the system. The precedence order is:

1. Named Record: dnsweaver.records.<name>.adopt (most specific)
2. Workload: dnsweaver.adopt (applies to hostnames found on the workload)
3. Provider Instance: DNSWEAVER_{NAME}_ADOPT_EXISTING
4. Global: DNSWEAVER_ADOPT_EXISTING (least specific)

Security Note: Workload configuration is not trusted by default. An adopt=true label or annotation is ignored unless the matching provider has DNSWEAVER_{NAME}_ADOPT_EXISTING_ALLOW_OVERRIDES=true. However, an adopt=false value is always honored to ensure dnsweaver's authority is restricted as requested.

You can choose how dnsweaver detects changes in your Traefik configuration files using the DNSWEAVER_SOURCE_TRAEFIK_WATCH_METHOD variable.

• auto (Default): Uses inotify if available on the system, otherwise falls back to poll.
• inotify: Uses Linux filesystem events for near-instant detection of changes.
• poll: Periodically scans files at the interval defined by DNSWEAVER_SOURCE_TRAEFIK_POLL_INTERVAL. This is the most compatible method across different platforms.

# Example using polling
- DNSWEAVER_SOURCE_TRAEFIK_WATCH_METHOD=poll
- DNSWEAVER_SOURCE_TRAEFIK_POLL_INTERVAL=30s

dnsweaver automates DNS record management by following a three-step lifecycle:

1. Watch: It monitors various sources (Docker/Swarm, Kubernetes, Proxmox VE, or Incus) for events.
2. Match: It extracts hostnames from these sources and matches them against configured provider domain patterns.
3. Reconcile: It compares the desired state (from the sources) against the live state in the DNS providers, performing create, update, or delete operations to ensure they match.

This process enables split-horizon DNS, where a single source (like a container label) can trigger updates to both internal (e.g., Technitium, Pi-hole) and external (e.g., Cloudflare, OVH) DNS providers simultaneously.

The Incus source determines the DNS hostname for each instance using the following order of precedence:

1. user.dnsweaver.hostname config key: Set directly on the Incus instance (e.g., incus config set web user.dnsweaver.hostname=app.example.net).
2. dnsweaver.hostname label: The incus-compose form of the override.
3. Instance name contains a dot: The name is used directly as an FQDN (e.g., db.home.example.com).
4. Configured domain suffix: Appended to the instance name (e.g., web + home.example.com $\rightarrow$ web.home.example.com).

Warning: If none of these apply, the instance is skipped. It is strongly recommended to set DNSWEAVER_INCUS_DOMAIN_SUFFIX to ensure all instances are registered.

Because Pi-hole does not support TXT records, dnsweaver cannot use standard ownership markers (_dnsweaver.*). Instead, it uses target-based ownership inference in managed mode.

If a record's RECORD_TYPE and TARGET match the provider instance's configured values, dnsweaver infers ownership. When the source workload disappears, dnsweaver will clean up these records. Records with different targets are preserved and not managed by this instance.

The DNSWEAVER_PLATFORM variable determines which workload sources are active. Use DNSWEAVER_INSTANCE_ID for unique identification in multi-instance setups.

• docker (default): Watches Docker containers/services.
• kubernetes: Watches Kubernetes Ingress, IngressRoute, HTTPRoute, and Service resources.
• both: Watches both Docker and Kubernetes workloads.
• none (or standalone): Disables container-runtime clients. Use this when running as a bare binary on a host/VM. You must configure at least one non-container source (e.g., Proxmox, Incus, or a file-discovery source) or startup will fail.