Chapter 26 of 47 · Services and discovery

Headless Services: talking to one specific Pod

A normal Service hides its Pods behind one virtual IP and picks a Pod for you. Usually that is exactly what you want. But a database primary, a Kafka broker, or a peer in a cluster must be reached by name, individually. A headless Service gives every Pod its own DNS name instead.

When "any Pod" is not good enough

What headless means

One line: clusterIP: None. The Service gets no virtual IP, kube-proxy does nothing for it, and nothing load-balances. It only does one job: DNS.

What DNS returns

$ nslookup db
Name:     db.default.svc.cluster.local
Address:  10.96.5.9            ← one virtual IP

$ nslookup db-headless
Name:     db-headless.default.svc.cluster.local
Address:  10.244.1.21          ← db-0
Address:  10.244.2.14          ← db-1
Address:  10.244.3.8           ← db-2

$ nslookup db-0.db-headless
Name:     db-0.db-headless.default.svc.cluster.local
Address:  10.244.1.21          ← exactly this Pod

Headless + StatefulSet = stable names

A Deployment's Pods get random names (db-7d9f8-x2kqp) that change on every replacement, so per-Pod DNS would be useless. A StatefulSet (chapter 38 goes deeper) is a controller like a Deployment, but for stateful apps: its Pods are numbered, and a replacement Pod gets the same name (and, in chapter 31, the same disk). Step through:

The YAML

apiVersion: v1
kind: Service
metadata:
  name: db-headless
spec:
  clusterIP: None
  selector:
    app: db
  ports:
    - port: 5432
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: db
spec:
  serviceName: db-headless
  replicas: 3
  selector:
    matchLabels:
      app: db
  template:
    metadata:
      labels:
        app: db
    spec:
      containers:
        - name: postgres
          image: postgres:16
          ports:
            - containerPort: 5432
  # volumeClaimTemplates: ...   (chapter 31)

Often you add a second, normal Service for the same Pods: a ClusterIP db-read that spreads read queries over all replicas, while writes use db-0.db-headless.

Using it from Node

// writes: always the primary
const primary = new Pool({ host: 'db-0.db-headless', port: 5432 });

// reads: any replica (a normal ClusterIP Service in front of all of them)
const replicas = new Pool({ host: 'db-read', port: 5432 });

// or: get every Pod address yourself
const { resolve4 } = require('node:dns/promises');
const ips = await resolve4('db-headless.default.svc.cluster.local');   // ['10.244.1.21', ...]

ClusterIP vs headless

Good to know

• Only ready Pods appear in DNS. Peers that must find each other before they are ready (cluster bootstrapping) need publishNotReadyAddresses: true.
• DNS caching: clients that resolve once at startup keep stale IPs. Prefer per-Pod names, and reconnect on errors.
• You usually do not write this yourself: database Helm charts and operators create the headless Service and StatefulSet for you. Knowing the pattern lets you read and debug them.

Quick check