Most of the time you want a single stable address, but not always.

In Kubernetes, applications run inside pods, and pods are temporary. They are created, destroyed, and replaced constantly, and every new pod receives a new internal network address. If other applications had to track those changing addresses by hand, life would be very difficult. Kubernetes solves this with a Service, which gives a group of pods one stable name and address that never changes even while the pods behind it come and go.

That arrangement is perfect for ordinary web applications, where any copy of the application can answer any request. However, some software is different. A database cluster has one primary member and several replicas, and a client that wants to write must reach the primary, not just any member. A message broker cluster has members that must find and talk to each other by name. A client that keeps long-lived connections may want to spread its own traffic across every copy of a server. In all these cases, hiding the individual pods behind one address is a disadvantage.

The idea in one sentence

A headless Service does not give you a single virtual address at all. Instead, when a client looks up the Service name, the answer contains the addresses of the individual pods, so the client can connect to them directly.

To appreciate what a headless Service removes, first look at what a regular one provides.

A regular Service of the default type is given a virtual IP address called the cluster IP. This address does not belong to any real machine or pod. It exists only as a rule in the networking layer of each node. A component called kube-proxy, running on every node, programs these rules so that any traffic sent to the virtual address is redirected to one of the healthy pods behind the Service.

sequenceDiagram
    participant C as Client Pod
    participant D as Cluster DNS
    participant V as Virtual IP rules on the node
    participant P1 as Pod A
    participant P2 as Pod B
    C->>D: Look up my-service
    D-->>C: One address, the cluster IP
    C->>V: Connect to the cluster IP
    V->>P1: Forward this connection to a chosen pod
    Note over C,P2: The client never learns which pod answered
        

What this arrangement gives you

The virtual address gives two conveniences. First, it never changes, so clients can remember it. Second, the networking layer spreads new connections across healthy pods, so clients do not need any special logic. These features are excellent for stateless applications, and they are the reason regular Services are the default.

A Service with the cluster IP explicitly set to None.

A headless Service is created like any other Service, with one crucial difference: its cluster IP field is set to the special value None. Because of this, Kubernetes does not allocate a virtual IP address. No rules are programmed on the nodes, and kube-proxy does nothing for this Service. The Service becomes purely a naming and discovery mechanism, and all connection handling is left to the client.

What changes compared to a regular Service

Two flavours of headless Service

A headless Service can be defined with a selector, which is a label query describing which pods belong to it, or without one. With a selector, Kubernetes watches the matching pods and keeps the list of addresses up to date automatically. Without a selector, no list is created automatically, and you may supply addresses manually. We explore both flavours in chapter five.

Everything special about headless Services happens in the DNS answer.

When a client looks up a regular Service name, the cluster DNS replies with one address, the virtual IP. When a client looks up a headless Service name, the DNS replies with several addresses, one for each ready pod behind the Service. The client receives the whole list and chooses how to use it. It might connect to the first address, try each in turn, or open connections to all of them.

sequenceDiagram
    participant C as Client Pod
    participant D as Cluster DNS
    participant P1 as Pod A
    participant P2 as Pod B
    participant P3 as Pod C
    C->>D: Look up my-headless-service
    D-->>C: Address of Pod A, Pod B, Pod C
    C->>P2: Connect directly to a chosen pod
    Note over C,P3: No virtual IP and no proxy in the middle
        

The names you can use

Services get a full name made from the Service name, the namespace, and a cluster suffix. Inside the same namespace, the short Service name is enough. From another namespace, you add the namespace. The full form includes the words svc and the cluster domain, which by default is cluster.local. Headless Services follow exactly the same naming pattern as regular ones, so applications do not need to know which kind they are talking to when they resolve the name; only the answer differs.

The selector decides who fills the list of addresses.

The selector-based flavour

This is by far the more common form. You label the pods of your application, and the Service selects them by those labels. The Service then behaves like a live directory: the moment a pod passes its readiness check, it shows up in the DNS answer, and the moment it fails or is deleted, it disappears. The people running the application do nothing by hand.

The selector-free flavour

Without a selector, the Service is just a name. The list of addresses comes from a separate object that you maintain yourself, and the DNS answer for the headless name is built from that list. This is useful for giving a stable, readable name to something outside the cluster’s control, such as an existing database server, or for testing. It requires more care, because nothing updates the list for you when things change.

The pairing that gives every pod its own permanent name.

A StatefulSet is a Kubernetes object designed for applications that need a stable identity, such as databases. Its pods are named with an ordered number: the first is numbered zero, the next one, and so on. If a pod is deleted, its replacement comes back with the same name and the same storage. But a stable pod name is not enough for other applications to reach it. They also need a stable network name, and this is what the headless Service provides.

A StatefulSet has a field that names the Service governing its network identity. When that Service is headless, each pod gets its own DNS name built from the pod name, the Service name, the namespace, and the cluster suffix. That name always points at the pod with that number, whatever its current address happens to be. If the pod restarts and receives a new address, the DNS name simply starts pointing at the new one.

flowchart TD
    HS[Headless Service
name: db] --> P0[Pod db-0
db-0.db.namespace.svc]
    HS --> P1[Pod db-1
db-1.db.namespace.svc]
    HS --> P2[Pod db-2
db-2.db.namespace.svc]
    SS[StatefulSet
service name field = db] -.creates and manages.-> P0
    SS -.-> P1
    SS -.-> P2
    C[Client] -->|db-0 always means the same member| P0
        

Two names, two purposes

With a headless Service in front of a StatefulSet, there are two kinds of names to use. The Service name itself returns all ready pods and suits clients that just need any member or the full list. The per-pod name reaches one specific member and suits clients that need to reach the primary, or members that need to find their own peers by number.

DNS can tell a client not just where a pod is, but which port to use.

Ordinary address records give only the location of a pod. For headless Services, Kubernetes also publishes another kind of DNS record called an SRV record when the Service defines named ports. An SRV record describes a service in terms of a host name and a port number. A client that understands them can ask, “Where is the replication port of this Service?” and receive both the pod names and the port number in the answer.

Why you should name your ports

Naming ports costs nothing and unlocks SRV discovery. Some client libraries, especially those used in clustered databases and message systems, can use SRV records to find peers and the right ports for each purpose, such as client traffic and internal replication. Even if your applications do not use them today, well-named ports also make configuration files and monitoring far easier to read.

By default only healthy pods appear, and sometimes that is exactly the wrong behaviour.

Kubernetes uses a readiness check to decide whether a pod can serve traffic. Normally, a pod that fails the check is removed from the list behind a Service, and the DNS answer for a headless Service omits it. This is the correct behaviour for ordinary clients, who should not be sent to a pod that cannot answer.

However, clustered software has a chicken-and-egg problem. A database member may only become ready after it has contacted its peers and joined the cluster. But if the peers are not visible in DNS until they are ready, no member can ever find another, and the cluster never forms. To solve this, a headless Service has a setting called publishNotReadyAddresses. When it is turned on, DNS includes pods whether or not they pass the readiness check.

flowchart TD
    A[New member pod starts] --> B{Service publishes not-ready pods?}
    B -->|No| C[Pod is hidden from DNS until ready]
    C --> D[Peers cannot find it]
    D --> E[Pod cannot join the cluster, so it never becomes ready]
    B -->|Yes| F[Pod appears in DNS immediately]
    F --> G[Peers find it and it joins the cluster]
    G --> H[Pod becomes ready]
        

A headless Service gives the client the information it needs to balance traffic itself.

Earlier we saw that a regular Service spreads traffic per connection. For short connections, such as classic web requests that open, transfer, and close, this works beautifully. But many modern protocols keep a single connection open for a very long time and send thousands of requests over it. A popular example is gRPC, which runs on HTTP/2 and multiplexes many requests over one connection.

With a regular Service, a client opens one connection, the networking layer picks one pod, and every request on that connection goes to that pod forever. If you later add more pods, the client keeps using the old connection, and the new pods sit idle. The load is unbalanced even though the Service claims to spread traffic. A headless Service offers a way out: the client receives every pod address and can open a connection to each, then distribute its own requests among them.

flowchart LR
    subgraph Regular Service
        C1[Client
one connection] --> V[Virtual IP]
        V --> A1[Pod A gets all requests]
        V -.idle.-> B1[Pod B]
        V -.idle.-> C2[Pod C]
    end
    subgraph Headless Service
        C3[Client
connections to each pod] --> A2[Pod A]
        C3 --> B2[Pod B]
        C3 --> D2[Pod C]
    end
        

What the client must do

Client-side balancing is not automatic. The client library must look up the headless name, read the full list of addresses, keep a connection to each, and refresh the list regularly to notice new or departed pods. Several popular libraries support this out of the box when configured with a DNS-based name resolver and a round-robin policy. A simple application that just opens the first address it is given will not balance at all.

Choosing the right kind of Service starts with knowing what each one offers.

flowchart TD
    Q1{Do clients need to reach specific pods or all pods?} -->|No, any pod is fine| Q2{Needs access from outside the cluster?}
    Q2 -->|No| CIP[ClusterIP]
    Q2 -->|Yes| LB[LoadBalancer or NodePort]
    Q1 -->|Yes| Q3{Do you want Kubernetes to balance for you?}
    Q3 -->|No| HL[Headless Service]
    Q3 -->|Yes| CIP
        

Headless is not the same as external

A common confusion is to think that a headless Service exposes pods to the outside world. It does not. The addresses it returns are internal pod addresses, reachable from inside the cluster network. To offer access from outside, you still need another mechanism such as an ingress or a load balancer in front of the application, and these usually work with regular Services.

Without a virtual IP there is no port translation, and that matters.

With a regular Service, the Service port and the pod’s target port can differ. A client connects to the Service port, and the networking layer translates it to the pod’s port. With a headless Service, there is no such translation, because there is no virtual address to hang it on. The client connects directly to the pod, so it must use the port that the pod actually listens on.

For this reason, it is good practice to make the Service port match the pod’s port in a headless Service. If the two differ, applications that rely on the Service definition to learn the port may be misled. The same applies to SRV records, which report the port from the Service definition. Keeping them identical avoids confusion.

The directory is only useful if clients keep it up to date.

Every DNS answer carries a lifetime, called the time to live. Clients and libraries are allowed to remember the answer until that time expires. In common cluster DNS setups this lifetime is short, often around half a minute, so the directory is refreshed frequently. But short does not mean zero, and some software caches for much longer than the lifetime suggests.

With a regular Service, stale DNS is rarely a problem, because the answer is the virtual IP, which never changes. With a headless Service, the answer is a list of pod addresses, which do change. A client that remembers an old list may keep trying addresses of pods that no longer exist and may never notice the new ones. This is one of the most common sources of mysterious errors with headless Services.

sequenceDiagram
    participant C as Client
    participant D as Cluster DNS
    participant P1 as Pod A
    participant P2 as Pod B new
    C->>D: Look up service
    D-->>C: Pod A address
    C->>P1: Connect and work
    Note over P1: Pod A is replaced by Pod B with a new address
    C->>P1: Connect using remembered address
    Note over C,P1: Fails because the address is stale
    C->>D: Look up again after cache expires
    D-->>C: Pod B address
    C->>P2: Connect successfully
        

Runtimes and libraries that cache

Situations where removing the virtual IP is the right decision.

The directory changes as pods come and go, and clients must cope.

When a pod restarts

If a container inside a pod crashes and restarts, the pod keeps its address, and nothing changes in DNS. If the whole pod is deleted and recreated, it usually receives a new address. For a StatefulSet pod, the name stays the same, so the per-pod DNS name follows the pod to its new address after a short delay while the record updates.

When you scale up or down

Scaling up adds new pods. Each appears in the DNS answer once it passes its readiness check. Existing clients only notice them after they refresh their DNS answer, which may take some time. Scaling down removes pods, whose records disappear, but clients holding old answers may still try them. Well-behaved clients handle a failed connection by retrying another address.

During rolling updates

In a rolling update, old pods are replaced by new ones in steps. The DNS answer changes several times during the update. If a client caches for longer than the rollout takes, it can end up holding a list where every address belongs to a pod that has been replaced. This is why graceful shutdown and retry logic matter as much here as with any other rollout.

How clusters use DNS to assemble themselves.

Clustered software has to solve the same problem again and again: how does a new member find the existing ones? On a traditional server farm, administrators write member lists into configuration files. On Kubernetes, the headless Service is the natural replacement. The application asks DNS for the list of members and connects to them, and the cluster assembles itself.

sequenceDiagram
    participant N as New member db-2
    participant D as Cluster DNS
    participant M0 as db-0
    participant M1 as db-1
    N->>D: Look up peer service, including not-ready pods
    D-->>N: Addresses of db-0, db-1, and itself
    N->>M0: Ask to join the cluster
    M0-->>N: Send cluster state
    N->>M1: Start replication
    Note over N: Member now passes readiness and serves clients
        

A directory with thousands of entries behaves differently from a short one.

Headless Services do less work in the networking layer, because there are no virtual IP rules to program, and that makes them cheap for the nodes. The cost moves to DNS and to the clients. Every lookup returns the full list of ready pods, so the size of the answer grows with the number of pods. For a handful of pods this is trivial. For hundreds, answers become large and may exceed the sizes that traditional DNS messages were designed for, leading to fallbacks or truncated lists in some clients.

Another cost is churn. When many pods change at once, for example during a large rolling update, the records change many times in quick succession. Clients with different cache lifetimes see different versions of the list at different times, which produces uneven load and occasional connection failures. Large systems mitigate this with careful rollout pacing and clients that tolerate imperfect lists.

Handing out the directory also hands out information.

A headless Service makes pod addresses easy to discover for anyone who can resolve the Service name from inside the cluster. A regular Service hides those addresses behind a virtual IP, which offers a small measure of obscurity. That obscurity was never a real protection, but it is worth knowing that with a headless Service the list of live pods is one DNS query away.

When a headless Service misbehaves, DNS is almost always the first place to look.

Problems with headless Services usually show up as one of three symptoms: the name does not resolve at all, the name resolves to fewer addresses than expected, or the name resolves correctly but connections fail. Each symptom points to a different part of the chain, and a calm, step-by-step check solves most cases in minutes.

Proven arrangements that solve recurring needs.

flowchart TD
    subgraph Cluster members
        M0[db-0]
        M1[db-1]
        M2[db-2]
    end
    PS[Headless peer Service
publishes not-ready pods] --> M0
    PS --> M1
    PS --> M2
    CS[Regular client Service
ready members only] --> M0
    CS --> M1
    CS --> M2
    Mem[Members] -->|discover peers| PS
    App[Applications] -->|send requests| CS
        

Mistakes that lead to lopsided load, lost members, and mysterious errors.

A compact checklist for confident use of headless Services.

How teams use headless Services in everyday operations.

Setting its cluster IP to the value None. Kubernetes then allocates no virtual IP, programs no proxy rules, and answers DNS lookups with the addresses of the individual pods.

Not by itself. DNS may return the addresses in a rotating order, but real balancing depends on the client. Clients that use only the first address will send everything to one pod.

Yes, if you want stable per-pod DNS names. The StatefulSet refers to a governing Service by name, and you must create that Service yourself. Without it, the per-pod names do not exist.

Not in place. The cluster IP field cannot be changed after creation, so you must delete the Service and create a new one with the value set to None.

It makes DNS include pods that have not yet passed their readiness checks. This helps clustered software bootstrap, because members can find each other before any of them is ready.

No. It returns internal pod addresses that are reachable from inside the cluster network. For outside access you need an ingress, a node port, or a load-balanced Service.

The Service name returns the addresses of all ready pods. The per-pod name, made from the pod name followed by the Service name, returns exactly one pod and stays stable across restarts of that StatefulSet member.

The most common causes are a selector that matches no pods, pods that are not ready, a name looked up from the wrong namespace, or a missing link between a StatefulSet and its Service.

They are published for named ports. If you do not name your ports, there are no SRV records for them, so give ports short, meaningful names.

They are probably remembering an earlier DNS answer. Short lifetimes, periodic re-resolution, and retry logic keep clients in step with the current list of pods.

There is no port translation, so clients connect to the pod’s own port. Keeping the Service port equal to the pod port avoids confusion and keeps SRV records accurate.

When any pod can answer any request and short connections are used. A regular Service gives stable addressing and built-in balancing with no special client logic.

A headless Service is a Service without a virtual IP. Instead of standing in front of your pods as a receptionist, it publishes a directory: a DNS answer that lists the addresses of the individual ready pods. This small change makes several things possible that a regular Service cannot do, including stable per-pod names for StatefulSets, peer discovery for clustered software, and client-side balancing for long-lived connections.

The price of that freedom is responsibility. Kubernetes no longer balances traffic, hides changes, or translates ports. Clients must use the full list wisely, cope with caching and churn, retry on failure, and connect to the right port. Security also moves to the pod level, so network policies and encryption become essential. Used where it fits and avoided where it does not, a headless Service is one of the most useful tools in the Kubernetes networking toolbox.