What Is a Headless Service in Kubernetes and When Would You Use One?

What Is a Headless Service?

A headless Service is a Kubernetes Service that explicitly sets clusterIP: None. Unlike a regular ClusterIP Service, it does not allocate a virtual IP address. Instead, when you query its DNS name, you get back the IP addresses of all individual Pods that match the selector.

This bypasses kube-proxy entirely -- there is no load balancing at the Service level. The client receives all Pod IPs and decides how to connect.

Creating a Headless Service

apiVersion: v1
kind: Service
metadata:
  name: cassandra
spec:
  clusterIP: None
  selector:
    app: cassandra
  ports:
    - name: cql
      port: 9042
      targetPort: 9042

The only difference from a regular ClusterIP Service is clusterIP: None.

kubectl get svc cassandra

NAME        TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)    AGE
cassandra   ClusterIP   None         <none>        9042/TCP   10s

How DNS Works for Headless Services

With a regular Service:

nslookup my-service.default.svc.cluster.local
# Returns: 10.96.45.12 (single ClusterIP)

With a headless Service:

nslookup cassandra.default.svc.cluster.local
# Returns:
# 10.244.1.5
# 10.244.2.8
# 10.244.3.12

Each returned IP is a Pod. The client can iterate over these IPs, pick one based on application logic, or connect to all of them.

Headless Services with StatefulSets

The most common use case for headless Services is with StatefulSets. When paired together, each Pod gets a stable, predictable DNS name:

apiVersion: v1
kind: Service
metadata:
  name: cassandra
spec:
  clusterIP: None
  selector:
    app: cassandra
  ports:
    - port: 9042
      targetPort: 9042
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: cassandra
spec:
  serviceName: cassandra      # must match the headless Service name
  replicas: 3
  selector:
    matchLabels:
      app: cassandra
  template:
    metadata:
      labels:
        app: cassandra
    spec:
      containers:
        - name: cassandra
          image: cassandra:4.1
          ports:
            - containerPort: 9042
              name: cql

This creates three Pods with predictable DNS names:

| Pod | DNS Name | |---|---| | cassandra-0 | cassandra-0.cassandra.default.svc.cluster.local | | cassandra-1 | cassandra-1.cassandra.default.svc.cluster.local | | cassandra-2 | cassandra-2.cassandra.default.svc.cluster.local |

Applications that need to connect to a specific replica (e.g., the primary database node) use these stable DNS names.

Regular Service vs. Headless Service

Regular ClusterIP Service:
┌──────────┐     DNS: 10.96.45.12     ┌─────────────┐
│  Client   │ ───────────────────────> │ kube-proxy   │
│           │                          │ (load balance)│
└──────────┘                          └──────┬────────┘
                                             │
                                    ┌────────┼────────┐
                                    ▼        ▼        ▼
                                 Pod-0    Pod-1    Pod-2

Headless Service:
┌──────────┐   DNS: [10.244.1.5,     ┌──────────────┐
│  Client   │        10.244.2.8,      │ Direct to Pod │
│           │        10.244.3.12]     │ (no proxy)    │
└──────────┘                          └──────────────┘
      │
      ├──────────────────────────────> Pod-0 (10.244.1.5)
      ├──────────────────────────────> Pod-1 (10.244.2.8)
      └──────────────────────────────> Pod-2 (10.244.3.12)

Use Cases

1. Distributed Databases

Databases like Cassandra, CockroachDB, and MongoDB require nodes to discover each other for cluster formation. A headless Service lets each database node find all peers via DNS:

# Application-level peer discovery
import socket
peers = socket.getaddrinfo("cassandra.default.svc.cluster.local", 9042)
# Returns all Pod IPs for gossip/cluster joining

2. Leader Election

Some applications need to connect to a specific Pod (the leader). With a headless Service and StatefulSet, the application can always reach the first replica:

# Connect to the primary
host: cassandra-0.cassandra.default.svc.cluster.local

3. Client-Side Load Balancing

gRPC and other protocols that maintain long-lived connections benefit from client-side load balancing. A regular Service would send all requests over a single connection to one Pod. A headless Service exposes all Pods, letting the gRPC client distribute requests:

# gRPC client configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: grpc-client-config
data:
  config.yaml: |
    target: dns:///my-grpc-service.default.svc.cluster.local:50051
    loadBalancingPolicy: round_robin

Headless Services Without a Selector

You can create a headless Service without a selector and manually manage the Endpoints:

apiVersion: v1
kind: Service
metadata:
  name: external-db
spec:
  clusterIP: None
  ports:
    - port: 5432
---
apiVersion: v1
kind: Endpoints
metadata:
  name: external-db     # must match Service name
subsets:
  - addresses:
      - ip: 10.0.0.50
      - ip: 10.0.0.51
    ports:
      - port: 5432

This pattern is useful for pointing to external databases or services that live outside the cluster while still using Kubernetes DNS for discovery.

Verifying a Headless Service

# Check that ClusterIP is None
kubectl get svc cassandra -o jsonpath='{.spec.clusterIP}'
# Output: None

# Verify endpoints are populated
kubectl get endpoints cassandra

# Test DNS resolution from within the cluster
kubectl run dns-test --rm -it --image=busybox:1.36 -- nslookup cassandra.default.svc.cluster.local

Expected nslookup output:

Server:    10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local

Name:      cassandra.default.svc.cluster.local
Address 1: 10.244.1.5 cassandra-0.cassandra.default.svc.cluster.local
Address 2: 10.244.2.8 cassandra-1.cassandra.default.svc.cluster.local
Address 3: 10.244.3.12 cassandra-2.cassandra.default.svc.cluster.local

Summary

Headless Services remove the load-balancing proxy layer and return individual Pod IPs via DNS. They are indispensable for StatefulSets, distributed databases, and any scenario where the client needs to address specific Pods or perform its own load balancing. Combined with StatefulSets, they provide stable, per-Pod DNS names that survive Pod restarts.