Kubernetes Pod DNS Discovery

Kubernetes Pod DNS Discovery refers to the mechanisms by which an individual pod itself becomes addressable and resolvable via DNS, as distinct from Service DNS discovery, which resolves a stable virtual endpoint rather than a specific pod. Pod-level DNS discovery matters specifically for workloads that need to address one particular pod instance directly rather than an arbitrary member of a load-balanced pool.

Conditions Under Which Pods Get DNS Records

No Default Pod-Level DNS Record

An ordinary pod, created without any association to a headless Service, does not receive its own DNS record by default; only Services generate DNS entries under standard cluster DNS behavior, meaning a pod alone is only reachable by its raw IP address unless something explicitly publishes a name for it.

Headless Service as the Publishing Mechanism

Pod-level DNS discovery is enabled by fronting a set of pods with a headless Service (clusterIP: None), which causes cluster DNS to publish an A record per ready pod rather than a single virtual IP, making individual pod addresses discoverable by resolving the Service name.

apiVersion: v1
kind: Service
metadata:
  name: ledger-db
spec:
  clusterIP: None
  selector:
    app: ledger-db
  ports:
    - port: 5432

Stable Per-Pod Hostnames

The hostname and subdomain Fields

A pod can be given a stable, predictable DNS name by setting its hostname and subdomain fields, where subdomain must match the name of a headless Service in the same namespace; the resulting per-pod DNS name combines both with the Service and namespace suffix.

apiVersion: v1
kind: Pod
metadata:
  name: ledger-db-manual-0
  labels:
    app: ledger-db
spec:
  hostname: ledger-db-manual-0
  subdomain: ledger-db
  containers:
    - name: db
      image: codartium/ledger-db:stable

ledger-db-manual-0.ledger-db.prod-payments-ledger.svc.cluster.local

Automatic Assignment for StatefulSets

StatefulSets set hostname and subdomain automatically for every pod they manage, deriving the hostname from the StatefulSet name and the pod's ordinal index, which is why StatefulSet pods are addressable individually and consistently even after being rescheduled, as long as the pod name (and therefore ordinal) is preserved.

ledger-db-0.ledger-db.prod-payments-ledger.svc.cluster.local
ledger-db-1.ledger-db.prod-payments-ledger.svc.cluster.local

Pod's Own DNS Resolver View

The Pod's Own Hostname Inside the Container

Inside the container, the hostname command reflects the value set by the hostname field (or the pod name if unset), which is separate from whether cluster DNS actually publishes a corresponding record externally — a pod can have an internal hostname without necessarily being externally resolvable if it is not attached to a headless Service.

hostname

fullyQualifiedDomainName Exposure

The subdomain and hostname combination can also be surfaced to the container itself through the downward API or environment variables, allowing application code to learn its own fully qualified DNS name at runtime rather than hardcoding assumptions about it.

env:
  - name: POD_FQDN
    value: "$(HOSTNAME).ledger-db.prod-payments-ledger.svc.cluster.local"

setHostnameAsFQDN Behavior

Container-Visible Hostname Format

By default, the in-container hostname is just the short hostname value, not the fully qualified name; setting setHostnameAsFQDN: true on the pod spec changes this so the container's own hostname reports the complete FQDN, which some applications require for correct self-identification, particularly distributed systems that validate peer identity against DNS names.

spec:
  hostname: ledger-db-0
  subdomain: ledger-db
  setHostnameAsFQDN: true

Use Cases Driving Pod-Level Discovery

Peer-to-Peer Clustered Systems

Distributed databases and clustering software that must form quorum among specific, individually addressable members rely on stable per-pod DNS names to configure peer lists at startup, since a load-balanced Service abstraction would be unable to express "connect to member 2 specifically" the way per-pod DNS does.

mongod --replSet rs0 \
  --bind_ip ledger-db-0.ledger-db.prod-payments-ledger.svc.cluster.local

Debugging and Direct Inspection

Operators use per-pod DNS names during troubleshooting to target a specific instance directly — for example, running diagnostic queries against one replica without going through Service-level load balancing that might route the connection to a different, healthy replica instead of the one under investigation.