External DNS - Adguard Home Provider (Webhook)

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.

---

Warning

Please make yourself familiar with the limitations before using this provider!

---

Supported DNS Record Types

The following DNS record types are supported:

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

Adguard Home Filtering Rules

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

Limitations

Rule Ownership

Important

This provider takes ownership of all rules matching above mentioned format!

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.

Subdomain Handling

Important

Adguard will evaluate all subdomains of a specified domain to the exact same DNS response, merging multiple matching rule responses!

For this provider to support all DNS record types, it must leverage Adguard Home filtering rules based on the Adblock-style syntax. The downside is that Adguard will evaluate subdomains of a specified domain to the exact same DNS response(s).

For example, defining a domain test.domain.org to resolve to 10.0.0.1 and querying any subdomain thereof, for example, sub.test.domain.org or other.sub.test.domain.org, will return 10.0.0.1. Additionally, Adguard will merge multiple matching rules. For example, defining the domains test.domain.org = 10.0.0.1 and sub.test.domain.org = 10.0.0.2 and querying for sub.test.domain.org (or any subdomain thereof) will result in the multi-value DNS response of [10.0.0.1, 10.0.0.2].

If you have a central ingress controller, this usually should not matter because the ingress is proxying based on the domain name, path, or else.

However, if you use multiple ingress controllers or expose services directly when using a similar subdomain structure, I recommend not using this provider!

Unfortunately, this behaviour cannot be turned off in Adguard!

---

Configuration

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.

---

Kubernetes Deployment

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 Bitnami Helm charts for ExternalDNS.

helm repo add bitnami https://charts.bitnami.com/bitnami

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

extraArgs:
  webhook-provider-url: http://localhost:8888

sidecars:
  - name: adguard-webhook
    image: ghcr.io/muhlba91/external-dns-provider-adguard:$RELEASE_VERSION
    ports:
      - containerPort: 8888
        name: http
    livenessProbe:
      httpGet:
        path: /healthz
        port: http
      initialDelaySeconds: 10
      timeoutSeconds: 5
    readinessProbe:
      httpGet:
        path: /healthz
        port: http
      initialDelaySeconds: 10
      timeoutSeconds: 5
    env:
      - name: LOG_LEVEL
        value: debug
      - name: ADGUARD_HOME
        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: SERVER_HOST
        value: "0.0.0.0" 
      - name: DRY_RUN
        value: "false"  
EOF

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

---

Contributors

Thanks goes to these wonderful people (emoji key):

Daniel Mühlbachler-Pietrzykowski 🚧 💻 📖

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