Introduction

Kubernetes readiness probes are defined on containers inside Pods, not on a StatefulSet object as a whole. If what you really want is “only consider this StatefulSet ready when the whole clustered application is ready,” the solution is to express that condition through per-Pod readiness logic or through separate status checks outside the probe system.

What Readiness Actually Applies To

A readiness probe answers one narrow question: should this Pod receive traffic right now? Services use that signal to decide whether to include the Pod in their endpoints.

A StatefulSet does not have its own readinessProbe field because it is a controller, not a traffic-serving workload instance. What it does have is status such as readyReplicas, and by default it rolls Pods in OrderedReady order. That means Pod 1 will not be updated until Pod 0 becomes ready, and so on.

So the practical model is:

• readiness is per Pod
• StatefulSet rollout ordering uses Pod readiness
• whole-set health must be derived from Pod readiness or external checks

How to Represent Cluster Readiness

For many stateful apps, simple process-up checks are too weak. A database replica might have a running process but still be replaying logs, joining quorum, or waiting for leader election. In those cases, your readiness probe should check the local instance's real application state.

For example, a container might expose an HTTP endpoint that reports ready only when the node has joined the cluster and completed recovery:

1readinessProbe:
2  httpGet:
3    path: /ready
4    port: 8080
5  initialDelaySeconds: 10
6  periodSeconds: 5
7  failureThreshold: 6

Or you can use an exec probe that checks a local command:

1readinessProbe:
2  exec:
3    command:
4      - sh
5      - -c
6      - |
7        pg_isready -h 127.0.0.1 -p 5432 &&
8        test -f /var/lib/postgresql/data/bootstrap-complete
9  initialDelaySeconds: 15
10  periodSeconds: 5

The key is that the probe runs inside each Pod, but it can still reflect higher-level cluster conditions if your application exposes them.

When You Need Whole-StatefulSet Readiness

Sometimes the real requirement is not service endpoint control. It is orchestration logic such as “wait until all replicas are ready before starting another job.” That is not solved by a StatefulSet-level readiness probe because such a feature does not exist.

Instead, query StatefulSet status directly:

kubectl rollout status statefulset/my-db
kubectl get statefulset my-db -o jsonpath='{.status.readyReplicas}'
kubectl get statefulset my-db -o jsonpath='{.status.replicas}'

If those values match, the controller considers all expected Pods ready. This pattern is useful in deployment scripts, init workflows, or higher-level automation.

Example StatefulSet Snippet

Here is a minimal StatefulSet showing a Pod-level readiness probe that the controller can use during ordered rollout:

1apiVersion: apps/v1
2kind: StatefulSet
3metadata:
4  name: my-db
5spec:
6  serviceName: my-db
7  replicas: 3
8  selector:
9    matchLabels:
10      app: my-db
11  template:
12    metadata:
13      labels:
14        app: my-db
15    spec:
16      containers:
17        - name: db
18          image: postgres:16
19          readinessProbe:
20            exec:
21              command:
22                - sh
23                - -c
24                - pg_isready -h 127.0.0.1 -p 5432

This does not make the StatefulSet itself probe-aware. It simply gives each Pod a readiness signal that the StatefulSet controller can honor during sequencing.

Common Pitfalls

The most common mistake is trying to find a readinessProbe field directly under the StatefulSet spec. Kubernetes does not support that because readiness belongs to containers.

Another mistake is using a shallow readiness check such as “TCP port is open” for clustered software that is still replaying data or waiting for leader synchronization. A probe that is too optimistic can route traffic too early.

It is also easy to confuse Service routing readiness with whole-cluster orchestration readiness. Services care about individual endpoints. Deployment scripts may need to watch StatefulSet status separately.

Summary

• Readiness probes exist at the container level, not at the StatefulSet level.
• StatefulSets use Pod readiness to control ordered rollout behavior.
• If you need cluster-aware readiness, expose that state through each Pod's probe.
• If you need all replicas ready before another step, query StatefulSet status directly.
• Use application-aware probes instead of simple process-up checks for stateful systems.