The Adguard Home Provider Webhook for External DNS provides support for Adguard Home filtering rules.

The provider is hugely based on https://github.com/ionos-cloud/external-dns-ionos-webhook.

The following DNS record types are supported:

• A
• AAAA
• CNAME
• TXT
• SRV
• NS
• PTR
• MX

The provider manages Adguard Home filtering rules following the Adblock-style syntax, which allows this provider to - theoretically - support all kinds of DNS record types.

Each record will be added in the format |DNS.NAME^dnsrewrite=NOERROR;RECORD_TYPE;TARGET. Examples are:

|my.domain.com^dnsrewrite=NOERROR;A;1.2.3.4
|my.domain.com^dnsrewrite=NOERROR;AAAA;1111:2222::3

Adguard does not support inline comments for filtering rules, making it impossible to filter out only rules set by External DNS. If you require manually set rules, it is adviced to define them as DNSEndpoint objects and enable the crd source in External DNS.

However, rules not matching above format, for example, |domain.to.block, will not be modified.

v8 introduces the HEALTHZ_ADDRESS (default: 0.0.0.0) and HEALTHZ_PORT (default: 8080) environment variable to introduce compatibility with the official Helm chart.

Attention: if you are using a customized Helm chart, make sure to adjust the probes accordingly.

v6 introduces the ADGUARD_SET_IMPORTANT_FLAG environment variable to set the important flag for AdGuard rules. This is enabled by default.

To keep the previous behaviour of v5, set ADGUARD_SET_IMPORTANT_FLAG to false.

In v5 removes the automated migration from the old rules syntax (v3) to the new syntax introduced in v4.

Attention: if you skip the upgrade to v4, old rules will be dangling and will cause issues.

In v3 the rule format was ||DNS.NAME^dnsrewrite=NOERROR;RECORD_TYPE;TARGET.

In v4 this was changed to |DNS.NAME^dnsrewrite=NOERROR;RECORD_TYPE;TARGET to solve issues with handling subdomains.

v4 also introduces an automated migration from the old syntax to the new one. To achieve this the provider reads the old syntax when updating rules but ignores them when providing the existing rules to ExternalDNS. In fact, ExternalDNS tries to create those rules and the provider will re-write those in AdGuard using the new syntax.

Please make sure v4 runs for some time in your cluster to ensure the migration of all old rules.

See cmd/webhook/init/configuration/configuration.go for all available configuration options of the webhook sidecar, and internal/adguard/configuration.go for all available configuration options of the Adguard provider.

The Adguard webhook is provided as an OCI image in ghcr.io/muhlba91/external-dns-provider-adguard.

The following example shows the deployment as a sidecar container in the ExternalDNS pod using the ExternalDNS included Helm chart.

helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/

# create the adguard configuration
kubectl create secret generic adguard-configuration --from-literal=url='<ADGUARD_URL>' --from-literal=user='<ADGUARD_USER>' --from-literal=password='<ADGUARD_PASSWORD>'

# create the helm values file
cat <<EOF > external-dns-adguard-values.yaml
provider: 
  name: webhook
  webhook:
    image:
      repository: ghcr.io/muhlba91/external-dns-provider-adguard
      tag: latest
    service:
      port: 8888
    livenessProbe: 
      httpGet:
        path: /healthz
        port: 8080
      initialDelaySeconds: 10
      timeoutSeconds: 5
    readinessProbe: 
      httpGet:
        path: /healthz
        port: 8080
      initialDelaySeconds: 10
      timeoutSeconds: 5
    env:
      - name: ADGUARD_URL
        valueFrom:
          secretKeyRef:
            name: adguard-configuration
            key: url
      - name: ADGUARD_USER
        valueFrom:
          secretKeyRef:
            name: adguard-configuration
            key: user
      - name: ADGUARD_PASSWORD
        valueFrom:
          secretKeyRef:
            name: adguard-configuration
            key: password
      - name: LOG_LEVEL
        value: debug
      - name: DRY_RUN
        value: "false"
EOF

# install external-dns with helm
helm install external-dns-adguard external-dns/external-dns -f external-dns-adguard-values.yaml

Thanks goes to these wonderful people (emoji key):

Daniel Mühlbachler-Pietrzykowski 🚧 💻 📖

heyzling 📖

Gabe Cook 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!