--- title: "How to Manage DNS Records in Kubernetes with ExternalDNS" description: "Deploy ExternalDNS with Helm to create DNS records automatically for Kubernetes Services and Ingresses in Cloudflare or PowerDNS, with safe ownership settings." category: "Kubernetes Ecosystem" language: en source: https://cubepath.com/docs/kubernetes-ecosystem/external-dns-kubernetes-service-discovery updated: 2026-09-25 --- # How to Manage DNS Records in Kubernetes with ExternalDNS ExternalDNS watches Kubernetes Services and Ingresses and keeps matching records in an external DNS provider, so a new `LoadBalancer` Service or Ingress host gets its A record without anyone touching the DNS panel. In this tutorial you will install ExternalDNS with Helm, connect it to Cloudflare with a scoped API token, publish a record for a demo Service, and learn the ownership and policy settings that keep it from touching records it does not own. A PowerDNS configuration is included at the end for self-hosted DNS. ## Prerequisites To follow this guide you need: - A Kubernetes cluster where `LoadBalancer` Services receive an external IP (for example through MetalLB or a cloud load balancer), or an Ingress controller that publishes its address in the Ingress status. - `kubectl` with admin access and Helm 3 on your workstation. - A domain whose DNS zone is hosted in Cloudflare. This guide uses **`example.com`**; replace it with your own domain. - `dig` on your workstation to verify records (package `dnsutils` on Ubuntu). ## Step 1 - Creating a Cloudflare API token ExternalDNS needs permission to read zones and edit DNS records. Use an API token restricted to the zones it manages instead of your global API key. In the Cloudflare dashboard, go to **My Profile > API Tokens > Create Token**, start from the **Edit zone DNS** template and set: - Permissions: **Zone / Zone / Read** and **Zone / DNS / Edit**. - Zone Resources: **Include / Specific zone / example.com**. Copy the token, then store it in a Kubernetes Secret in a dedicated namespace. Replace `your_cloudflare_api_token` with the value you copied: ```bash kubectl create namespace external-dns kubectl create secret generic cloudflare-api-token -n external-dns \ --from-literal=api-token=your_cloudflare_api_token ``` ## Step 2 - Installing ExternalDNS with Helm Add the chart repository maintained by the Kubernetes SIG: ```bash helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/ helm repo update ``` Create a values file: ```bash nano external-dns-values.yaml ``` ```yaml provider: name: cloudflare env: - name: CF_API_TOKEN valueFrom: secretKeyRef: name: cloudflare-api-token key: api-token sources: - service - ingress domainFilters: - example.com txtOwnerId: k8s-prod policy: upsert-only interval: 1m logLevel: info ``` The settings that matter most: | Setting | Purpose | |---------|---------| | `sources` | Which Kubernetes objects ExternalDNS reads hostnames from. | | `domainFilters` | Only zones and names under these domains are managed. Everything else is ignored. | | `txtOwnerId` | ExternalDNS writes a TXT record next to every record it creates, containing this ID. It only updates or deletes records that carry its own ID. Use a unique value per cluster. | | `policy` | `upsert-only` creates and updates but never deletes. `sync` also deletes records when the Service or Ingress goes away. | | `interval` | How often a full reconciliation runs. Cloudflare rate limits API calls, so do not set this too low. | Start with `upsert-only` while you confirm the behavior, then switch to `sync` in Step 5. Install the chart: ```bash helm install external-dns external-dns/external-dns \ --namespace external-dns \ --values external-dns-values.yaml ``` Check that the pod is running and that it can talk to Cloudflare: ```bash kubectl get pods -n external-dns kubectl logs -n external-dns deploy/external-dns --tail=20 ``` ```output NAME READY STATUS RESTARTS AGE external-dns-6d8c5f7b9c-p4w2k 1/1 Running 0 30s ``` In the logs you should see the configuration being printed and then `All records are already up to date`. An authentication error at this point means the token or its zone scope is wrong. ## Step 3 - Publishing a record for a Service ExternalDNS publishes a Service of type `LoadBalancer` when it carries the `external-dns.alpha.kubernetes.io/hostname` annotation. Create a demo web server: ```bash kubectl create deployment web --image=nginx ``` Create a Service manifest for it: ```bash nano web-service.yaml ``` ```yaml apiVersion: v1 kind: Service metadata: name: web annotations: external-dns.alpha.kubernetes.io/hostname: web.example.com external-dns.alpha.kubernetes.io/ttl: "300" spec: type: LoadBalancer selector: app: web ports: - port: 80 targetPort: 80 ``` The `hostname` annotation accepts a comma-separated list if you want several names for the same Service. Apply it and wait for an external IP: ```bash kubectl apply -f web-service.yaml kubectl get service web ``` ```output NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE web LoadBalancer 10.96.41.120 203.0.113.25 80:31544/TCP 20s ``` Within one `interval`, ExternalDNS creates the record. The logs show the change: ```bash kubectl logs -n external-dns deploy/external-dns --tail=5 ``` ```output level=info msg="Changing record." action=CREATE record=web.example.com ttl=300 type=A zone=... level=info msg="Changing record." action=CREATE record=a-web.example.com type=TXT zone=... ``` Verify it resolves: ```bash dig +short web.example.com ``` ```output 203.0.113.25 ``` By default, Cloudflare records are created as DNS only (not proxied). To proxy one record through Cloudflare, add the annotation `external-dns.alpha.kubernetes.io/cloudflare-proxied: "true"` to that Service or Ingress. ## Step 4 - Publishing records from an Ingress For Ingress resources you do not need a hostname annotation: ExternalDNS reads the hosts from `spec.rules[].host` and points them at the address in the Ingress status. A minimal example, assuming an Ingress class named `nginx`: ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: web spec: ingressClassName: nginx rules: - host: app.example.com http: paths: - path: / pathType: Prefix backend: service: name: web port: number: 80 ``` Once `kubectl get ingress web` shows an address in the `ADDRESS` column, ExternalDNS creates `app.example.com`. If the column stays empty, the Ingress controller is not publishing its status and ExternalDNS has nothing to point the record at. ## Step 5 - Enabling sync and limiting what is managed With `upsert-only`, deleting the Service leaves a stale DNS record behind. Once you are confident the `domainFilters` and `txtOwnerId` are correct, switch to `sync` so records are removed together with their Service or Ingress. Edit `external-dns-values.yaml`: ```yaml policy: sync ``` Before applying it to a zone with existing records, preview what ExternalDNS would do by adding a dry run temporarily: ```yaml extraArgs: - --dry-run ``` ```bash helm upgrade external-dns external-dns/external-dns \ --namespace external-dns \ --values external-dns-values.yaml kubectl logs -n external-dns deploy/external-dns --tail=30 ``` In dry run mode the logs list the planned changes without calling the API. If no unexpected `DELETE` appears, remove the `extraArgs` block and run the same `helm upgrade` again. Because ExternalDNS only deletes records whose TXT record carries its own `txtOwnerId`, records you created by hand in the zone are left alone even with `sync`. If you only want to publish some Services, use an annotation filter so ExternalDNS ignores everything without an explicit opt-in: ```yaml extraArgs: - --annotation-filter=external-dns.alpha.kubernetes.io/enabled in (true) ``` Then add `external-dns.alpha.kubernetes.io/enabled: "true"` to the Services and Ingresses that should get records. Test the full lifecycle by deleting the demo Service: ```bash kubectl delete service web ``` After one interval, `dig +short web.example.com` returns nothing. ## Using PowerDNS instead of Cloudflare If you run your own authoritative DNS with PowerDNS, enable its HTTP API (`api=yes`, `api-key=...` and `webserver=yes` in `pdns.conf`) and make it reachable from the cluster. Store the API key in a Secret: ```bash kubectl create secret generic pdns-api-key -n external-dns \ --from-literal=api-key=your_pdns_api_key ``` Use these values instead of the Cloudflare block. ExternalDNS reads any command-line flag from an environment variable named `EXTERNAL_DNS_`, which keeps the key out of the pod arguments: ```yaml provider: name: pdns env: - name: EXTERNAL_DNS_PDNS_API_KEY valueFrom: secretKeyRef: name: pdns-api-key key: api-key extraArgs: - --pdns-server=http://pdns.example.internal:8081 sources: - service - ingress domainFilters: - example.com txtOwnerId: k8s-prod policy: upsert-only ``` Replace `pdns.example.internal:8081` with the address of your PowerDNS API. The zone must already exist in PowerDNS; ExternalDNS manages records, not zones. ## Troubleshooting **No record is created.** Check the logs with `kubectl logs -n external-dns deploy/external-dns`. The usual causes are a hostname outside `domainFilters`, a Service of type `ClusterIP` (it has no external address to publish), or a LoadBalancer Service still waiting for its external IP. **`403` or authentication errors from Cloudflare.** The token lacks `Zone Read` or `DNS Edit`, or is not scoped to the zone you are using. **A record exists but ExternalDNS will not update it.** The record was created by hand or by another cluster with a different `txtOwnerId`, so ExternalDNS treats it as foreign. Delete it manually and let ExternalDNS recreate it. **Two clusters overwrite each other's records.** Each ExternalDNS instance writing to the same zone needs its own `txtOwnerId`. ## Conclusion ExternalDNS now keeps your Cloudflare (or PowerDNS) zone in step with the Services and Ingresses in your cluster, and the TXT ownership records stop it from touching anything it did not create. As next steps, pair it with cert-manager so the same hostnames also get TLS certificates, move to `policy: sync` once you trust the configuration, and run one instance per zone or provider if you manage both public and internal DNS.