Headless Service vs ClusterIP Service

Detailed Breakdown

ClusterIP Service — The Default

apiVersion: v1
kind: Service
metadata:
  name: web-api
spec:
  selector:
    app: web-api
  ports:
    - port: 80
      targetPort: 8080
  type: ClusterIP

When you create this Service, Kubernetes assigns a virtual IP (e.g., 10.96.142.57) and configures kube-proxy rules to distribute traffic. A DNS lookup for web-api.default.svc.cluster.local returns:

web-api.default.svc.cluster.local.  A  10.96.142.57

The client connects to the virtual IP, and kube-proxy routes the connection to a healthy backend Pod. The client never knows which Pod handled the request.

Headless Service — Direct Pod Access

apiVersion: v1
kind: Service
metadata:
  name: mysql
spec:
  clusterIP: None  # This makes it headless
  selector:
    app: mysql
  ports:
    - port: 3306
      targetPort: 3306

With clusterIP: None, there is no virtual IP. A DNS lookup for mysql.default.svc.cluster.local returns all Pod IPs:

mysql.default.svc.cluster.local.  A  10.244.1.5
mysql.default.svc.cluster.local.  A  10.244.2.8
mysql.default.svc.cluster.local.  A  10.244.3.12

The client receives all three Pod IPs and decides which one to connect to. No kube-proxy rules are created.

StatefulSet DNS Integration

Headless Services are required for StatefulSets to provide per-Pod DNS names:

apiVersion: v1
kind: Service
metadata:
  name: mysql
spec:
  clusterIP: None
  selector:
    app: mysql
  ports:
    - port: 3306
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: mysql
spec:
  serviceName: mysql  # Must match the headless Service name
  replicas: 3
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
        - name: mysql
          image: mysql:8.0
          ports:
            - containerPort: 3306

Each Pod gets a stable DNS entry:

mysql-0.mysql.default.svc.cluster.local → 10.244.1.5
mysql-1.mysql.default.svc.cluster.local → 10.244.2.8
mysql-2.mysql.default.svc.cluster.local → 10.244.3.12

Even if mysql-0 is rescheduled to a different node with a new IP, the DNS name mysql-0.mysql.default.svc.cluster.local is updated to point to the new IP. The name is stable; the IP is not.

DNS Lookup Comparison

You can verify the difference from inside a Pod:

# ClusterIP Service — returns the virtual IP
nslookup web-api.default.svc.cluster.local
# Server:    10.96.0.10
# Name:      web-api.default.svc.cluster.local
# Address:   10.96.142.57

# Headless Service — returns all Pod IPs
nslookup mysql.default.svc.cluster.local
# Server:    10.96.0.10
# Name:      mysql.default.svc.cluster.local
# Address:   10.244.1.5
# Address:   10.244.2.8
# Address:   10.244.3.12

When Headless Services Matter

Database Replication: A MySQL replica needs to know the address of the primary (mysql-0.mysql) to configure replication. A ClusterIP would randomly send the connection to any Pod — including another replica.

Cluster Membership: Etcd, ZooKeeper, and Kafka need each member to know the addresses of all peers. The headless Service DNS returns all member IPs, and the stable per-Pod names let each member find specific peers.

Client-Side Load Balancing: gRPC maintains long-lived connections, so kube-proxy's connection-level load balancing sends all requests on one connection to the same Pod. A headless Service lets the gRPC client discover all Pods and implement round-robin at the request level.

# gRPC client connecting via headless Service
apiVersion: v1
kind: Service
metadata:
  name: grpc-backend
spec:
  clusterIP: None
  selector:
    app: grpc-backend
  ports:
    - port: 50051

The gRPC client resolves grpc-backend.default.svc.cluster.local, gets all Pod IPs, and distributes requests across them using its own load-balancing logic.

Endpoint Slices

Both ClusterIP and headless Services maintain Endpoint Slices that track the IPs of ready Pods:

kubectl get endpointslices -l kubernetes.io/service-name=mysql

For a ClusterIP Service, kube-proxy reads these endpoints to update iptables/IPVS rules. For a headless Service, CoreDNS reads these endpoints to populate DNS records. The endpoint tracking mechanism is the same — only the consumption differs.

Combining Both Service Types

It is common to create both a headless and a ClusterIP Service for the same StatefulSet:

# Headless — for peer discovery and per-Pod DNS
apiVersion: v1
kind: Service
metadata:
  name: mysql-headless
spec:
  clusterIP: None
  selector:
    app: mysql
  ports:
    - port: 3306
---
# ClusterIP — for client access with load balancing
apiVersion: v1
kind: Service
metadata:
  name: mysql
spec:
  selector:
    app: mysql
  ports:
    - port: 3306

Application Pods that need to reach the database use mysql (the ClusterIP Service) for load-balanced access. The database Pods themselves use mysql-headless for peer discovery and replication configuration.

Headless Services Without Selectors

A headless Service without a selector creates no automatic endpoints. You can manually create Endpoints to point to external resources:

apiVersion: v1
kind: Service
metadata:
  name: external-db
spec:
  clusterIP: None
  ports:
    - port: 5432
---
apiVersion: v1
kind: Endpoints
metadata:
  name: external-db
subsets:
  - addresses:
      - ip: 192.168.1.100
    ports:
      - port: 5432

This gives you a stable DNS name within the cluster that points to an external database, useful for migrating workloads into Kubernetes.