Skip to content

External-DNS

Watches Kubernetes Ingress and Service resources and reconciles their hostnames into Cloudflare DNS records for the tomoda.life zone, so the Ingress spec is the one place to declare in-cluster DNS.

Installed by k8s/envs/platform/external-dns/application.yaml, configured by k8s/envs/platform/external-dns/values.yaml.

Chart and source

Field Value
Helm chart external-dns
Repository https://kubernetes-sigs.github.io/external-dns/
Version 1.21.1
Destination namespace external-dns (created by Argo CD)
Argo CD Application external-dns

The Application is multi-source: the chart is pulled from the upstream Helm repo, the values.yaml is sourced from this repo via $values/k8s/envs/platform/external-dns/values.yaml.

What it syncs

From values.yaml:

provider: cloudflare
sources:
  - ingress
  - service
domainFilters:
  - tomoda.life
interval: 1m
policy: sync
registry: txt
txtOwnerId: k8s-dev
  • Provider: Cloudflare, the only authoritative DNS for tomoda.life. Zone-level records (mail, redirects, Workers) are Terraform-managed in infrastructure/cloudflare/dns.tf.
  • Sources: Ingress + Service. Every Ingress host and every LoadBalancer Service's annotated hostname becomes a DNS record. In practice this is dominated by Ingresses (since the cluster has exactly one LoadBalancer Service, the Traefik one).
  • Domain filter. Only tomoda.life and its subdomains are touched. Records outside this zone are ignored, even if they appear in cluster manifests.
  • Policy: sync. External-DNS creates and deletes records to match cluster state. If an Ingress is removed, its DNS record is removed.
  • Registry: txt with txtOwnerId: k8s-dev. Every managed record gets a sibling TXT record marking ownership. External-DNS refuses to delete records it doesn't own, so it never touches the Terraform-managed records.

Cloudflare credentials

CF_API_TOKEN comes from the external-dns-cloudflare-secret Secret, an ExternalSecret (k8s/envs/platform/manifests/external-secrets-config.yaml) over GSM tomoda-cloudflare-api-token (a token with Zone:DNS:Edit on tomoda.life). To rotate, add a new GSM version; ESO refreshes the Secret within the hour, then restart the External-DNS pod.

Proxied vs DNS-only

Records are DNS-only unless the Ingress sets external-dns.alpha.kubernetes.io/cloudflare-proxied: "true". The tomoda app Ingress sets it in both envs; admin UIs stay DNS-only.

Verifying

# Watch what External-DNS is doing
kubectl logs -n external-dns deploy/external-dns -f

# Confirm a record exists
dig +short argo-app.tomoda.life

A successful reconciliation log line names the record, the type, and the owner TXT it wrote. If a record is missing, common causes are: hostname not under tomoda.life, Ingress not yet picked up by Traefik (no LoadBalancer status address yet), or the Cloudflare token lacking permissions.

Operational notes

  • One-minute interval. New Ingresses get DNS within ~60 seconds. Lowering interval risks Cloudflare API rate limits.
  • Adding a new public hostname requires nothing beyond declaring it on an Ingress under tomoda.life. No manual DNS work.
  • Moving a hostname out of the cluster means deleting the Ingress (External-DNS removes the record) and then setting whatever new record you want in Cloudflare directly. Avoid leaving Ingresses behind purely as "DNS holders".