Pod DNS Records

A ReplicaSet runs three replicas of your database. Each Pod gets a random name like db-xk7p2 and an IP that changes after every restart. If another application needs to talk to a specific replica rather than any replica, it has no reliable name to use. Services solve the load-balancing case, but when you need to address a specific instance by name, a different mechanism is required.

Kubernetes has two answers: a generic Pod DNS record format and, for StatefulSets, a stable hostname scheme that makes each Pod permanently addressable by name.

The Pod DNS record format

Every Pod in Kubernetes has a DNS record, but it is built from its IP address rather than its generated name. The format replaces each dot in the IP with a hyphen:

<pod-ip-with-hyphens>.<namespace>.pod.cluster.local

A Pod with IP 10.244.1.15 in the default namespace has the record 10-244-1-15.default.pod.cluster.local.

Start by looking at current Pod IPs in the simulated cluster:

kubectl get pods -o wide

The IP column shows the address assigned to each Pod. From that IP you can form the DNS record manually. Why does Kubernetes use the IP in the name? Because Pod IPs are allocated by the network layer at scheduling time. Encoding the IP in the record lets CoreDNS generate it without maintaining a separate registry of Pod names.

Stable hostnames with subdomain and hostname

You can give a regular Pod a predictable DNS record by setting two fields in its spec: hostname and subdomain. When both are set and a headless Service with that subdomain name exists in the same namespace, CoreDNS registers a stable A record:

<hostname>.<subdomain>.<namespace>.svc.cluster.local

Why does Kubernetes require a headless Service as the zone anchor? CoreDNS only creates these records when a headless Service with the matching name exists. Without it, the hostname and subdomain fields in the Pod spec are stored in etcd but produce no DNS entry. The Service acts as the permission mechanism for the DNS zone.

# illustrative only
apiVersion: v1
kind: Pod
metadata:
  name: primary
spec:
  hostname: primary
  subdomain: db-internal
  containers:
    - name: db
      image: postgres:15

StatefulSets and stable DNS

StatefulSets are the most common use case for stable Pod DNS. A StatefulSet assigns each Pod an ordinal index and keeps that index stable across restarts: db-0, db-1, db-2. Combined with a headless Service, each Pod gets a permanent DNS name:

<pod-name>.<headless-service>.<namespace>.svc.cluster.local

Even if db-1 restarts and gets a new IP, its DNS name db-1.db.default.svc.cluster.local continues to resolve to the new IP. The name is stable because it is derived from the ordinal index, not the IP address.

Inspect pods in the simulated cluster to see the naming pattern:

kubectl get pods -o wide

Each StatefulSet Pod follows the <statefulset-name>-<ordinal> pattern. The combination with a headless Service is what makes each one addressable by a stable name.

DNS policy

Every Pod has a dnsPolicy field that controls how DNS is configured inside the container.

ClusterFirst is the default. DNS queries go to CoreDNS first. If CoreDNS cannot resolve the name (because it is an external domain), it forwards the query to the upstream DNS server of the node. This is the standard behavior for every workload that needs both in-cluster and external DNS.

Default tells the Pod to inherit the DNS configuration of the node, bypassing CoreDNS entirely. A Pod with this policy cannot resolve Service names using short names.

None disables all automatic DNS configuration. You must supply a dnsConfig block in the Pod spec with explicit nameserver and search domain entries.

kubectl get pods -o wide

Pod DNS records follow the IP-hyphen format and are rarely addressed directly. Stable naming for Pods comes from the hostname and subdomain combination for standalone Pods, or from the StatefulSet ordinal combined with a headless Service for stateful workloads. The dnsPolicy field controls whether a Pod participates in cluster DNS at all.