Kubernetes StatefulSet Headless Service Association

Kubernetes StatefulSet Headless Service Association is the specific DNS mechanics enabled when a StatefulSet's serviceName references a headless Service, covering how CoreDNS generates per-Pod DNS records from this association, the distinction between the governing Service's own DNS entry and each individual Pod's subdomain entry, and the publishNotReadyAddresses setting that controls whether not-yet-ready Pods are resolvable at all.

What Makes a Service Headless

clusterIP: None as the Trigger

A Service becomes headless specifically by setting spec.clusterIP: None, instructing Kubernetes not to allocate a virtual cluster IP or perform any load-balancing; DNS queries against the Service name instead resolve directly to the set of matching Pod IPs.

apiVersion: v1
kind: Service
metadata:
  name: headless-service-association-example
spec:
  clusterIP: None
  selector:
    app: db
  ports:
    - port: 5432

Two Distinct DNS Record Types Generated

The Governing Service's Own A Records

Querying the Service name itself returns an A (or AAAA) record for every matching, ready Pod, functioning similarly to a normal Service's DNS but without any single virtual IP, letting a client discover all current members through one lookup.

kubectl exec headless-service-association-example-0 -- nslookup headless-service-association-example

Per-Pod Subdomain Records

Separately, each individual Pod receives its own resolvable DNS name in the form <pod-name>.<service-name>.<namespace>.svc.cluster.local, generated specifically because the Pod belongs to a StatefulSet referencing this Service as its serviceName, letting a client target one specific ordinal directly rather than the whole set.

kubectl exec headless-service-association-example-0 -- nslookup headless-service-association-example-1.headless-service-association-example

publishNotReadyAddresses

Controlling Resolution of Unready Pods

By default, a Pod that has not yet passed its readiness probe is excluded from the governing Service's A records, mirroring normal Service behavior. Setting publishNotReadyAddresses: true on the headless Service overrides this, making even not-yet-ready Pods resolvable, a setting StatefulSets commonly require since peer-discovery during startup often needs to reach a peer before that peer is fully ready to serve application traffic.

spec:
  clusterIP: None
  publishNotReadyAddresses: true
  selector:
    app: db

Why This Matters for Cluster Formation

A distributed database's startup sequence frequently needs to contact peers to negotiate cluster membership before any peer has become fully ready in the application sense; without publishNotReadyAddresses: true, this bootstrapping DNS resolution would fail during exactly the window it is most needed.

Creation Order Independence

The Service and StatefulSet Are Independently Created Objects

Unlike ownership relationships elsewhere in Kubernetes, there is no ownerReferences link between a headless Service and the StatefulSet referencing it; they are independently created and deleted objects, connected only by the serviceName field pointing to a matching selector, meaning the Service must be created (and correctly configured) separately, with no automatic validation ensuring it exists.

kubectl get service headless-service-association-example

Consequence of a Missing or Misconfigured Service

If the referenced Service does not exist, or its selector does not match the StatefulSet's Pods, the StatefulSet's Pods are created and run normally, but per-Pod DNS resolution silently fails, a failure mode invisible from the StatefulSet's own status fields entirely.

Headless Service Association Diagram

Understanding these two distinct DNS record types, and the specific role of publishNotReadyAddresses in supporting cluster bootstrap, is essential for correctly configuring the headless Service that stable network identity depends on entirely, since a subtle misconfiguration here produces symptoms that appear entirely unrelated to DNS at first inspection.