Being alive and being ready to help are two very different states, and Kubernetes cannot guess the difference on its own.

When Kubernetes starts a container, it can easily see whether the program has begun running. It can also see whether the program has crashed. What it cannot see, without your help, is what the program is doing inside. Is it still reading a large file? Is it waiting for a database to answer? Is it in the middle of a long clean-up? To the outside, all of these look the same: a healthy, running process.

Without further information, Kubernetes assumes that a container is ready as soon as it starts. That is a safe guess for a tiny program that starts in a blink. It is a poor guess for the typical real application, which needs seconds or even minutes before it can serve its first visitor properly.

Common reasons a running pod is not ready

A readiness probe is a repeated health question that decides whether a pod may receive traffic.

A probe is a small test that Kubernetes runs against your container on a schedule. The word comes from a doctor’s probe: a tool used to check on something inside a body without opening it up. A readiness probe is the kind of probe whose only job is to answer one question: should this pod be receiving requests from visitors right now?

You describe the test in the pod’s description. You say what to check, such as “ask this web address” or “try this network port”. You also say how often, how long to wait for an answer, and how many failures to tolerate. Kubernetes then runs the test over and over, for as long as the container lives, and acts on the results.

What it is, why it exists, where it is used

What it is: a repeated check, defined per container, that marks a pod as ready or not ready for traffic.

Why it exists: so that visitors reach only the pods that can serve them well, and so that updates and restarts do not cause errors.

Where it is used: in nearly every production web service, API, and worker that receives traffic. It is one of the most important settings in a reliable Kubernetes system.

A few basic words are enough to follow the rest of this guide.

Kubernetes is a system that runs your containers across many machines and keeps them healthy. You say what you want, and Kubernetes makes it true and keeps it true. Here are the parts that matter for probes.

How a Service finds its pods

A Service does not memorize pod addresses. It uses a list, maintained automatically, called the endpoints of the Service. Each entry in the list is a pod that matches the Service and is currently able to receive traffic. When a pod becomes unready, its entry is marked as not ready, and the Service stops sending it visitors. This list is the bridge between a readiness probe and real traffic, and you will see it again and again in this guide.

Three kinds of probes

Kubernetes offers three probes. They look alike but have very different jobs. The readiness probe decides whether a pod receives traffic. The liveness probe decides whether a container should be restarted. The startup probe gives slow-starting applications extra time before the other two begin. The next chapters treat each in turn, with the readiness probe as the star.

A readiness answer starts inside one container and ends up changing where visitors are sent across the whole cluster.

The diagram below shows the path. The kubelet on the node asks the container the health question. It reports the answer to the API server, the cluster’s front door. Other parts of Kubernetes notice the change and update the list of ready pods. Finally, the components that route traffic read that list and adjust.

flowchart LR
    subgraph Node["Worker Node"]
        Kubelet["kubelet prober"] -->|asks the health question| App["Container"]
        Kubelet -->|reports Ready or not| API
    end
    API["API Server"] --> Slice["EndpointSlice controller"]
    Slice --> Proxy["kube-proxy and load balancers"]
    Proxy -->|sends traffic only to ready pods| App
    Client["Users"] --> Proxy
    

Meet the components

Three probes, three different questions, three different consequences.

flowchart TD
    Start["Container starts"] --> SP{"Startup probe configured"}
    SP -->|Yes| SW["Wait for the startup probe to pass"]
    SP -->|No| RUN["Liveness and readiness begin"]
    SW -->|Passes| RUN
    SW -->|Fails for too long| KILL["Container is restarted"]
    RUN --> LV["Liveness failing means restart"]
    RUN --> RD["Readiness failing means no traffic"]
    

Why keeping them separate matters

Mixing up these probes causes some of the nastiest incidents in Kubernetes. If a liveness probe is used for something that is really a readiness matter, such as a slow database, Kubernetes restarts healthy pods again and again, which makes the slowdown worse. If a readiness probe is used where a liveness probe is needed, a truly frozen program sits idle forever, never restarted. Each probe must ask the right question.

Kubernetes can ask your container the health question in four different styles. Pick the one that fits your program.

HTTP: the most common choice

Most web applications offer a tiny address dedicated to health, often named something like “ready” or “health”. Kubernetes sends a request to it. If the application replies with a success code, the probe passes. If it replies with an error code, or does not reply in time, the probe fails. This style is popular because it lets the application itself decide what “ready” means.

TCP: only checks that a door is open

A TCP probe simply tries to connect to a port. If something is listening, it passes. This is a weak test, because a program may accept connections long before it can do real work. It is fine for simple servers, but be aware that it only proves the door is open, not that the shop is ready.

Command: for programs without a web address

Some programs have a small tool that reports their status. Kubernetes can run that tool inside the container and read its exit number, where zero means success. This style costs more, since a new process starts at every check. Use it when HTTP or TCP cannot express readiness.

gRPC: a native option

Services built on the gRPC framework follow a standard health-checking convention. Kubernetes can call it directly, with no extra adapter program needed. It is available in current versions of Kubernetes.

Five numbers control how patient or nervous a probe is. Getting them right is half the art.

flowchart TD
    S["Container starts"] --> D["Wait for the initial delay"]
    D --> P["Probe runs every period"]
    P --> Q{"Probe passes"}
    Q -->|Yes so count a success| SU{"Reached the success threshold"}
    SU -->|Yes| R["Pod is marked Ready"]
    SU -->|No| P
    Q -->|No so count a failure| F{"Reached the failure threshold"}
    F -->|Yes| N["Pod is marked Not Ready"]
    F -->|No| P
    

Doing the arithmetic

To find how quickly a pod is removed from traffic after it breaks, multiply the period by the failure threshold. With the defaults, that is ten seconds times three, which is about thirty seconds. Add up to a few more seconds for the report to travel through the cluster. During those seconds, the broken pod still receives traffic. If thirty seconds of errors is too much, shorten the period or lower the threshold, at the price of more sensitivity to random blips.

Between one failed check and a change in traffic, a short chain of events unfolds.

sequenceDiagram
    participant K as kubelet
    participant C as Container
    participant A as API Server
    participant E as EndpointSlice controller
    participant P as kube-proxy
    K->>C: Readiness check
    C-->>K: Fails with an error
    K->>K: Count failures until the threshold
    K->>A: Report pod not Ready
    A->>E: Pod status changed
    E->>A: Mark the endpoint not ready
    A->>P: Updated endpoint list
    P->>P: Stop sending traffic to this pod
    K->>C: Readiness check again
    C-->>K: Succeeds
    K->>A: Report pod Ready
    A->>E: Pod status changed
    E->>A: Mark the endpoint ready
    A->>P: Updated endpoint list
    P->>P: Resume sending traffic
    

Readiness affects far more than visitors. It also steers software updates and startup order.

An unready pod still exists

A pod that fails its readiness probe is not deleted, not restarted, and not moved. It simply sits outside the traffic. Its logs remain available, and you can still look inside it. This is very useful for debugging, since the broken pod stays around for investigation while healthy pods serve users.

Direct access still works

Readiness controls traffic that goes through Services and the components built on them. It does not build a wall around the pod. Anyone who knows the pod’s own address can still call it directly. Readiness is a routing signal, not a security fence.

A pod moves between a few clear states during its life, and the probe is the switch.

stateDiagram-v2
    [*] --> NotReady: Pod starts
    NotReady --> Ready: Probe passes enough times
    Ready --> NotReady: Probe fails enough times
    Ready --> Terminating: Pod is deleted
    NotReady --> Terminating: Pod is deleted
    Terminating --> [*]
    

Readiness is what makes a software release smooth instead of scary.

When you release a new version of an application, Kubernetes does not switch everything at once. A Deployment replaces the old pods gradually. It starts a new pod, waits for it to be ready, and only then removes an old one. This gentle handover is called a rolling update, and readiness is the signal that makes it safe.

flowchart LR
    A["Old pods serve all traffic"] --> B["A new pod starts"]
    B --> C{"New pod passes readiness"}
    C -->|Yes| D["Traffic shifts and one old pod is removed"]
    D --> E["Repeat until every pod is new"]
    C -->|No for a long time| F["Rollout stalls and old pods keep serving"]
    

The settings that shape a rollout

What a stuck rollout looks like

If a new version has a bug that stops it from ever becoming ready, the rollout stops. The new pods stay unready. The old pods keep serving users, so nobody notices an outage, but the release never finishes. After the progress deadline, the Deployment reports that it has failed to make progress. This is the system working exactly as designed: a broken release is quarantined by readiness before it can hurt anyone.

The hardest part of a readiness probe is not the settings. It is deciding what the application should check.

Your application decides what to answer when the probe arrives. There are two schools of thought, and a good engineer understands both.

The cascade danger

Imagine twenty copies of a web service, all depending on one database. If the readiness probe asks the database, then a brief database slowdown makes all twenty copies unready together. The Service now has nobody to send visitors to. Users see errors, even though the web service itself is perfectly healthy and would have shown a friendly message or served cached pages. The deep check turned a partial problem into a total one.

A useful rule is this: check what is local to the pod, and be cautious about checking what is shared by all pods. If a shared dependency is down, no pod can fix it by leaving the traffic. Removing them all only makes matters worse. Instead, let the application handle the failure gracefully, with clear errors, cached data, or retries.

What belongs in a good readiness check

Readiness matters at the end of a pod’s life as much as at the start.

When a pod is deleted, for example during an update or when the cluster shrinks, Kubernetes does two things at nearly the same moment. It tells the traffic layer to stop sending visitors, and it tells the container to shut down. Those two messages travel by different routes and take different amounts of time. The result can be a small race: the container may start shutting down while some visitors are still being sent to it.

The steps of a graceful goodbye

How to make it smooth

• Handle the polite stop signal in your application so it finishes current requests before exiting.
• Make the readiness answer flip to “not ready” as soon as shutdown begins.
• Add a short pre-stop pause to cover the delay before all traffic components notice.
• Set the grace period long enough for your slowest normal request to finish.
• Keep long-lived connections in mind, such as chat or streaming, and close them cleanly.

Some applications take minutes to start. The startup probe gives them time without weakening the other probes.

Big applications, such as those that load large models, build big indexes, or run many start-up checks, may need a long time before they can answer even the simplest question. If you set a very long initial delay on the readiness and liveness probes to accommodate them, you lose sharpness later: a failing pod would also be detected slowly once the application is running normally.

The startup probe solves this. While the startup probe has not yet passed, the other two probes are held back. It can be given a generous budget, such as checking every ten seconds up to thirty times, giving the application five minutes to finish starting. As soon as it passes once, it steps aside for good, and the readiness and liveness probes take over with their normal, tighter timing.

Sometimes a pod should not be considered ready until something outside the pod agrees.

A readiness probe is the pod’s own opinion of itself. But in some situations another system must confirm that the pod is ready. For example, a cloud load balancer may need to register the pod and confirm that it can reach it before any traffic should be routed there. Kubernetes supports this through readiness gates.

A readiness gate is an extra named condition listed in the pod’s description. The pod is ready only when all its containers are ready and every gate condition has been set to true by whoever owns it. An outside controller sets the condition when its work is finished. Until then, the pod remains not ready, even if the container passes every probe.

A probe is cheap once and expensive when repeated forever across thousands of pods.

The load a probe adds

Each check is one small request to the application. Every pod is checked by its own node’s kubelet, so the load does not concentrate in one place. For normal applications, this is invisible. But if the check is heavy, such as running a database query, and the period is short, the checks themselves become a meaningful share of the application’s work.

Where trouble shows up

Readiness is a tool for staying available, but a careless setup can do the opposite.

How readiness helps availability

• Unhealthy or warming-up pods are kept away from users.
• Releases stop by themselves when a new version is broken.
• Brief trouble in one pod is absorbed by its siblings.
• Pods recover without a disruptive restart.

How readiness can hurt availability

Working together with other protections

Readiness alone does not make a system highly available. It works best alongside spare capacity, spreading pods across machines and zones, disruption budgets that limit how many pods maintenance may remove at once, and sensible autoscaling. Think of readiness as the traffic warden, and the others as the road, the lanes, and the signals.

A health endpoint is a small door into your application. Keep it small and quiet.

Readiness problems are invisible to users until they become outages. Watch for them early.

Alerts worth setting up

• The number of ready pods for an application falls below a safe minimum.
• A pod flips between ready and not ready several times in a short period, which signals flapping.
• A Deployment has had unavailable copies for longer than a normal release.
• A rollout has passed its progress deadline.
• Probe failures rise sharply across many pods together, which suggests a shared cause.

Readiness probes are among the most valuable settings in Kubernetes, and among the most misused.

The main trade-offs

Sensitivity versus stability. A twitchy probe catches problems fast and removes healthy pods by mistake. A patient probe is calm and lets broken pods linger. You choose the point that matches your tolerance for errors and for false alarms.

Depth versus safety. A deep check finds more problems, and it can make every pod fail together. A shallow check is safe, and it misses real issues. Most teams settle on a mostly shallow check with a few carefully chosen local tests.

Speed of rollout versus caution. Requiring pods to stay ready for a while before proceeding makes releases slower and safer. Skipping this makes them faster and riskier.

Some habits produce calm, boring deployments. Others produce surprises.

Patterns that work

Anti-patterns to avoid

A handful of habits prevents most readiness problems.

Best practices

Common mistakes

The same ideas appear in systems of every size and industry.

Match the symptom to its likely cause, then apply the fix.

Let us set up a readiness probe for a small web application, describing each step in words rather than code.

Suppose you have a small web service that needs about twenty seconds after starting to load its data. You run three copies behind a Service. Here is how a careful engineer adds readiness.

What this walkthrough teaches

The order matters: first make the application able to answer honestly, then tell Kubernetes how often to ask, then test both good and bad cases on purpose. A probe that has never been seen failing has never been proved to work.

Quick answers to the questions beginners ask most often.