📖 Read-only preview — lessons, diagrams, and quizzes only. The hands-on labs, live grading, and progress tracking require running the real course locally against a Kubernetes cluster.Run it locally →

Module 4 · Lesson 4.2

Cluster DNS

A ClusterIP solves "the address doesn't change," but you still shouldn't hardcode it — IPs aren't memorable, and they're reassigned if a Service is deleted and recreated. Kubernetes gives every Service a DNS name instead, resolved by a cluster-internal DNS server: CoreDNS.

The name format

Every Service gets a name of the shape <service>.<namespace>.svc.cluster.local. From inside the same namespace, the short form <service> resolves too — Kubernetes appends your pod's own namespace automatically through the search domains it configures. From a different namespace, you need at least <service>.<namespace>, or the fully-qualified name.

The same query, from different places

pod in checkout runs:

nslookup api
↓ CoreDNS ↓
✓ resolved: 10.96.4.21 (api.checkout.svc.cluster.local)
The Service 'api' only ever lives in namespace 'checkout'. What changes is whether the querying pod's namespace + search domain gets you there.

Linux aside: every pod gets a /etc/resolv.conf, the same configuration file your laptop uses to know which DNS server to ask and which domain suffixes to try automatically. Kubernetes writes this file for you, pointing at CoreDNS's own ClusterIP and listing your namespace as a search domain — that's the whole mechanism behind the short-name trick. kubectl exec <pod> -- cat /etc/resolv.conf shows you exactly what was written.

Where this breaks in practice

The single most common real-world DNS bug isn't CoreDNS being down — it's a pod reaching for an unqualified name across a namespace boundary. curl http://api from a pod in checkout only works if a Service named api exists in the checkout namespace. Point that same code at a different namespace without qualifying the name, and you get a clean DNS resolution failure (NXDOMAIN / "could not resolve host") — not a timeout, not a connection refused, a name that simply doesn't exist from where you're asking. That distinction matters: it immediately tells you this is a naming problem, not a networking or application problem.

Diagnosing it

Two commands, in order: kubectl exec <pod> -- nslookup <name> (or wget/curl if nslookup isn't in the image) to see exactly what resolution does, then compare against kubectl get svc -A to see where the Service you actually meant to reach really lives.

The infrastructure analogy

CoreDNS is your cluster's internal DNS server, playing the same role as an internal Route 53 private hosted zone or an on-prem AD-integrated DNS server — service discovery by name instead of by memorized IP, with records that update themselves as Services come and go.

In the lab, you'll hit exactly this cross-namespace DNS failure and fix it by qualifying the name correctly.

🧪 Lab: lab-08-cluster-dns

Preview only

Goal

Hit a real cross-namespace DNS failure, tell it apart from a network problem, and fix it by qualifying the name.

There are two namespaces here: lab-08-cluster-dns (where the real api Service lives) and lab-08-client (an unrelated namespace, standing in for "some other team's app," with a pod that's trying to reach api).

Tasks

  1. Apply the starting manifests: kubectl apply -f manifests/
  2. Confirm api is up: kubectl get pods,svc -n lab-08-cluster-dns
  3. From the client pod, try the request it's configured to make: kubectl exec client -n lab-08-client -- sh -c 'wget -qO- -T 3 $API_URL' — it fails.
  4. Narrow it down with DNS specifically, not the app protocol: kubectl exec client -n lab-08-client -- nslookup api (if nslookup isn't present, wget -T 3 http://api fails the same way — the point is it fails at the name lookup, not a timeout waiting on a connection).
  5. Check what namespace the client pod is actually in vs. where api lives: kubectl get pod client -n lab-08-client -o jsonpath='{.metadata.namespace}' vs. kubectl get svc api -n lab-08-cluster-dns.
  6. Fix it in manifests/client.yaml: qualify API_URL with the right namespace (http://api.lab-08-cluster-dns), then delete and recreate the pod (env vars are immutable on a live pod, same as you saw with command in Module 2): kubectl delete pod client -n lab-08-client && kubectl apply -f manifests/client.yaml
  7. Confirm: kubectl exec client -n lab-08-client -- sh -c 'wget -qO- -T 3 $API_URL' now succeeds.

Check

Run the check once the client pod can successfully reach $API_URL.

This lab runs against a real local Kubernetes cluster with an automated grader — clone the repo and run make start to do it for real.

📝 Quiz

1. What is the fully-qualified DNS name for a Service named 'api' in namespace 'checkout'?

2. A pod in namespace 'checkout' runs `curl http://api`. Which Service does this actually reach?scenario

3. That same `curl http://api` call, run from a pod in a *different* namespace than where the 'api' Service lives, fails. What does the failure look like?scenario

4. What writes a pod's /etc/resolv.conf, and what does it configure?

5. In the traditional-infrastructure analogy, CoreDNS plays the role of:

Progress isn't saved in this preview — run the course locally to track completion and grade labs for real.