Home › Docs › Hostnames with ExternalDNS

Hostnames with ExternalDNS

Give every LoadBalancer service a real, resolvable name — keycloak.lab.example.dev instead of 172.30.1.7 — with no /etc/hosts editing, no sudo, and the same answer from your Mac, from inside the clusters, and from any script.

Why this works with klimax

klimax routes the kind bridge CIDR from macOS into the VM over pure L3 with no SNAT, so a MetalLB VIP like 172.30.1.7 is directly reachable from your Mac as itself. That is what makes this approach possible: the address a service receives is a real, routable address on your machine, so you can publish it in DNS like any other record.

That is the difference from an /etc/hosts scheme. You are not faking a name-to-address mapping locally; you are publishing a true one. Anything that resolves DNS — your browser, curl, a Go test, a pod in another cluster — gets the same answer, and nothing needs elevated privileges.

What you need

Be clear about the prerequisite, because it is the real barrier: you need a domain you control, hosted in a DNS provider with an API. ExternalDNS writes records programmatically; it cannot invent a zone for you.

If owning a domain is not an option, skip to alternatives. This guide uses Google Cloud DNS; ExternalDNS also supports Route 53, Cloudflare, Azure DNS and many others — only the provider block and the credential differ.

You will also need a running klimax cluster (see Getting started) and gcloud, kubectl and helm on your PATH.

$ export GCP_PROJECT=my-project
$ export DNS_APEX_LITERAL=example-dev        # apex zone resource name
$ export DNS_ZONE_NAME=lab.example.dev       # the delegated sub-zone
$ export DNS_ZONE_LITERAL=lab-example-dev    # its resource name

Step 1 — Delegate a sub-zone for the lab

Do not point ExternalDNS at the zone for your real domain. Give it a delegated sub-zone whose only contents are lab records, so the blast radius of a mistake is that sub-zone and nothing else.

$ gcloud dns --project="${GCP_PROJECT}" managed-zones create "${DNS_ZONE_LITERAL}" \
    --description="klimax lab records" \
    --dns-name="${DNS_ZONE_NAME}." \
    --visibility="public" --dnssec-state="off"

Then delegate to it from the apex zone by copying its nameservers into an NS record:

$ NS_SERVERS=$(gcloud dns --project="${GCP_PROJECT}" record-sets list \
    --zone="${DNS_ZONE_LITERAL}" --name="${DNS_ZONE_NAME}." --type="NS" \
    --format=yaml | yq '.rrdatas | join(",")')

$ gcloud dns --project="${GCP_PROJECT}" record-sets create "${DNS_ZONE_NAME}." \
    --zone="${DNS_APEX_LITERAL}" --type="NS" --ttl="3600" --rrdatas="${NS_SERVERS}"

Verify delegation resolves before going further — this is the most common place to get stuck:

$ dig +short NS "${DNS_ZONE_NAME}"

Step 2 — Create a service account

ExternalDNS needs credentials scoped to DNS administration only:

$ export SA=external-dns-local
$ export CREDS_FILE="$HOME/.klimax/external-dns-credentials.json"

$ gcloud iam service-accounts create "${SA}" \
    --display-name="ExternalDNS for local klimax clusters"

$ gcloud projects add-iam-policy-binding "${GCP_PROJECT}" \
    --role='roles/dns.admin' \
    --member="serviceAccount:${SA}@${GCP_PROJECT}.iam.gserviceaccount.com"

$ gcloud iam service-accounts keys create "${CREDS_FILE}" \
    --iam-account "${SA}@${GCP_PROJECT}.iam.gserviceaccount.com"

roles/dns.admin is project-wide. If you host other zones in the same project, prefer a custom role or a dedicated project for lab DNS.

Step 3 — Install ExternalDNS

$ CTX=dev   # your cluster's kube context

$ kubectl --context "${CTX}" create namespace external-dns
$ kubectl --context "${CTX}" -n external-dns create secret generic external-dns \
    --from-file=credentials.json="${CREDS_FILE}"

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

Write the values file:

# external-dns.values.yaml
provider:
  name: google
extraArgs:
  - "--service-type-filter=LoadBalancer"
  - "--google-project=my-project"
env:
  - name: GOOGLE_APPLICATION_CREDENTIALS
    value: /etc/secrets/service-account/credentials.json
extraVolumeMounts:
  - name: google-service-account
    mountPath: /etc/secrets/service-account/
extraVolumes:
  - name: google-service-account
    secret:
      secretName: external-dns
sources:
  - service
policy: upsert-only
registry: txt
txtOwnerId: "klimax-lab"
domainFilters:
  - "lab.example.dev"
logLevel: info

$ helm --kube-context "${CTX}" upgrade -i external-dns external-dns/external-dns \
    -n external-dns -f external-dns.values.yaml

What the important settings do

Step 4 — Annotate a Service

ExternalDNS publishes a record when a LoadBalancer Service carries the hostname annotation:

apiVersion: v1
kind: Service
metadata:
  name: keycloak
  annotations:
    external-dns.alpha.kubernetes.io/hostname: keycloak.lab.example.dev
spec:
  type: LoadBalancer
  ports:
    - port: 80
      targetPort: 8080
  selector:
    app: keycloak

Within a reconcile cycle — about a minute by default — the name resolves:

$ dig +short keycloak.lab.example.dev
172.30.1.7
$ curl -sS http://keycloak.lab.example.dev/

Keeping the address stable

MetalLB allocates from the cluster's pool in order, so a service can land on a different VIP after a teardown. Pin it if that matters:

metadata:
  annotations:
    external-dns.alpha.kubernetes.io/hostname: keycloak.lab.example.dev
    metallb.io/loadBalancerIPs: 172.30.1.7

klimax allocates 172.30.<num>.1–7 and 172.30.<num>.16–254 per cluster, where <num> is the cluster's assigned number (see klimax cluster list). Pinning from the low range keeps pinned addresses clearly separated from dynamic ones.

Step 5 — Resolve the same names inside the clusters

Host-side resolution now works. Pods, however, resolve through CoreDNS, which will not necessarily return the answer you want for your lab zone.

klimax configures this for you — set the zone in your klimax config:

kind:
  customDnsResolvers:
    - domain: "lab.example.dev"
      # resolvers default to 8.8.8.8 / 8.8.4.4 when omitted

Every cluster created afterwards gets a CoreDNS forward rule for that zone, so keycloak.lab.example.dev resolves identically from a pod and from your Mac. That matters for anything calling services by hostname — mTLS, OIDC issuer URLs, webhook callbacks — where the name must agree on both sides.

Multiple clusters, one zone

Running several clusters against a single zone is the common case:

$ for CTX in dev staging prod; do
    kubectl --context "$CTX" create namespace external-dns
    kubectl --context "$CTX" -n external-dns create secret generic external-dns \
      --from-file=credentials.json="${CREDS_FILE}"
    helm --kube-context "$CTX" upgrade -i external-dns external-dns/external-dns \
      -n external-dns -f external-dns.values.yaml
  done

Namespace the hostnames per cluster so they cannot collide — keycloak.dev.lab.example.dev, keycloak.staging.lab.example.dev — and re-read the upsert-only warning above before changing policy or txtOwnerId. For fleets, the same loop works over klimax fleet describe <name> -o json.

Verifying and troubleshooting

$ kubectl --context "${CTX}" -n external-dns logs deploy/external-dns --tail=50

Teardown

$ helm --kube-context "${CTX}" uninstall external-dns -n external-dns
$ kubectl --context "${CTX}" delete namespace external-dns

Under upsert-only, records survive. Remove them explicitly:

$ gcloud dns --project="${GCP_PROJECT}" record-sets delete \
    keycloak.lab.example.dev. --zone="${DNS_ZONE_LITERAL}" --type=A

Deleting the whole sub-zone is the quickest reset between labs, since nothing else lives there — which is exactly why Step 1 delegates one.

If you cannot own a domain