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!
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
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.
Important
If an upgrade path between version is listed here, please make sure to follow those paths without skipping a version! Otherwise, the correct behaviour cannot be guaranteed, resulting in possible inconsistencies or errors.
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 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_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: 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
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!