How Headless Services Enable Direct Pod Access in Kubernetes

Overview

Headless Services are a special type of Service whose spec.clusterIP is set to None, meaning no ClusterIP is allocated. They are also called "headless services" and provide service discovery via DNS without load‑balancing. Each Pod gets its own DNS A record, making them suitable for stateful workloads such as databases deployed with a StatefulSet.

Service and Service Discovery

Service Overview

Services expose a group of Pods and use label selectors to match Pods. The Service IP (ClusterIP) is a virtual address reachable only inside the cluster. External access can be achieved with NodePort or LoadBalancer types.

Note: besides NodePort and LoadBalancer, services can also be exposed via hostPort, hostNetwork, or Ingress.

Service Access Mechanism

A Service creates routing rules on each node that forward traffic arriving at the ClusterIP to the corresponding Pod IP and port.

kube-proxy watches the API server and updates node routing tables accordingly.

Service Types

Three main types: ClusterIP, NodePort, LoadBalancer.

(1) ClusterIP – internal virtual IP only.

(2) NodePort – maps a port on each node to the Service, accessible as nodeIP:nodePort.

(3) LoadBalancer – builds on NodePort and provisions an external load‑balancer IP (commonly used in public clouds).

Headless Service

After the Service overview, we focus on Headless Services.

Observing a Headless Service

Example: an existing headless Service named openldap defined as:

apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/instance: cb-openldap
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: openldap-ha
  name: openldap
spec:
  clusterIP: None  # makes the service headless
  ports:
  - name: ldap
    port: 389
    protocol: TCP
    targetPort: 389
  selector:
    app.kubernetes.io/instance: cb-openldap
    app.kubernetes.io/name: openldap-ha
  sessionAffinity: None
  type: ClusterIP

Running kubectl get svc openldap shows ClusterIP: None. kubectl describe svc openldap lists two ready Pods (10.233.0.214:389, 10.233.9.73:389).

# kubectl get svc openldap
NAME       TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
openldap   ClusterIP   None         <none>        389/TCP   185d

# kubectl describe svc openldap
Name:              openldap
Namespace:         default
Labels:            app.kubernetes.io/instance=cb-openldap
                   app.kubernetes.io/managed-by=Helm
                   app.kubernetes.io/name=openldap-ha
Annotations:       meta.helm.sh/release-name: cb-openldap
                   meta.helm.sh/release-namespace: default
Selector:          app.kubernetes.io/instance=cb-openldap,app.kubernetes.io/name=openldap-ha
Type:              ClusterIP
IP Family Policy:  SingleStack
IP Families:       IPv4
IP:                None
Ports:             ldap  389/TCP
TargetPort:        389/TCP
Endpoints:         10.233.0.214:389,10.233.9.73:389
Session Affinity: None

DNS‑Based Pod Discovery

For a normal Service, DNS returns the single ClusterIP. For a Headless Service, DNS returns the IP address of each backing Pod, providing multiple A records.

DNS Discovery Example

Using a busybox Pod with nslookup:

# kubectl exec -it busybox-848d7987f9-wbqq8 /bin/sh
/ # cat /etc/resolv.conf
search default.svc.cluster.local svc.cluster.local cluster.local
nameserver 169.254.25.10
options ndots:5

Querying the Service name returns the Pod IPs, confirming DNS‑based discovery.

Similarly, a headless Kafka Zookeeper Service returns the IPs of all three Pods.

# kubectl get svc -n=xxx-middleware | grep kafka-zookeeper-headless
kafka-zookeeper-headless   ClusterIP   None   <none>   2181/TCP,3888/TCP,2888/TCP   646d

# kubectl describe svc -n=xxx-middleware kafka-zookeeper-headless
Name:              kafka-zookeeper-headless
Namespace:         xxx-middleware
Labels:            app=zookeeper
Annotations:       meta.helm.sh/release-name: kafka
Type:              ClusterIP
IP:                None
Ports:             client  2181/TCP
Endpoints:         10.233.66.179:2181,10.233.66.181:2181,10.233.69.223:2181
...

Discovering All Pods, Including Unready Ones

By default only ready Pods become endpoints. Adding the annotation

service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"

forces the Service to include all Pods matching the selector, regardless of readiness.

kind: Service
metadata:
  annotations:
    service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"

Example with a Redis HA Service shows the annotation and the resulting endpoints.

# kubectl describe svc -n=xxx-system redis-ha-announce-0
Annotations:       service.alpha.kubernetes.io/tolerate-unready-endpoints: true
Endpoints:         10.233.0.213:6379

Conclusion

Headless Services provide a ClusterIP‑less way to discover Pods via DNS, useful for internal communication in stateful applications. They rely on DNS round‑robin rather than kube‑proxy load‑balancing, and can be combined with a regular Service to expose the same Pods externally if needed.