DevOps Dictionary

Kubernetes Readiness Probe is a health check that tells Kubernetes whether a container is ready to receive traffic. If the readiness probe fails, Kubernetes keeps the pod running but removes it from Service endpoints, so new requests are not routed to it.

What a Kubernetes readiness probe does

A readiness probe protects users and systems from sending traffic to a pod before the application can handle it. This is useful when a container process starts before the app is fully initialized.

For example, a web API container may start in 3 seconds, but the application might need another 20 seconds to:

• Load configuration
• Connect to a database
• Run startup checks
• Warm an in-memory cache
• Register internal routes or plugins

During that time, the pod exists, but it should not receive production traffic. The readiness probe gives Kubernetes a clear signal for that decision.

How it works

The kubelet runs the readiness probe on each node where the pod is scheduled. It checks the container on a regular interval using one of several probe types:

• HTTP GET: Kubernetes sends an HTTP request to a path such as /ready or /healthz.
• TCP socket: Kubernetes checks whether a TCP port is open.
• Exec: Kubernetes runs a command inside the container and checks the exit code.
• gRPC: Kubernetes calls a gRPC health checking endpoint.

If the probe succeeds, the container is marked ready. If it fails enough times, the pod is marked not ready. For pods behind a Kubernetes Service, Kubernetes updates EndpointSlices so traffic stops going to that pod.

The container is not restarted when a readiness probe fails. The pod stays alive and can become ready again after the application recovers.

Common readiness probe settings

• initialDelaySeconds: How long Kubernetes waits after the container starts before running the first probe.
• periodSeconds: How often Kubernetes runs the probe.
• timeoutSeconds: How long Kubernetes waits for a probe response.
• successThreshold: How many successful checks are needed before the container is marked ready.
• failureThreshold: How many failed checks are needed before the container is marked not ready.

A common starting point for HTTP services is a readiness endpoint checked every 5 or 10 seconds with a short timeout, such as 1 or 2 seconds. You should tune these values based on real startup time and normal response latency.

Simple example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: example/api:1.0.0
          ports:
            - containerPort: 8080
          readinessProbe:
            httpGet:
              path: /ready
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
            timeoutSeconds: 2
            failureThreshold: 3

In this example, Kubernetes sends requests to /ready on port 8080. If the endpoint fails 3 times in a row, the pod is removed from Service traffic until the probe succeeds again.

Common use cases

• Safe rolling deployments: Kubernetes waits for new pods to become ready before shifting traffic to them.
• Startup protection: A pod can finish initialization before it receives requests.
• Temporary dependency issues: An app can stop receiving traffic while it cannot serve requests correctly.
• Graceful maintenance: A pod can mark itself not ready before shutdown or draining.
• Workload-specific checks: Systems such as web APIs, workers with HTTP control ports, and platforms like Airflow on EKS can expose readiness checks for their own runtime state. See this guide to deploy Apache Airflow on AWS EKS for a real Kubernetes workload context.

Readiness probe vs liveness probe

Readiness and liveness probes solve different problems.

• Readiness probe: Decides whether the pod should receive traffic.
• Liveness probe: Decides whether Kubernetes should restart the container.

If your application is temporarily unable to serve requests but can recover by itself, use a readiness probe. If the application is stuck and needs a restart, use a liveness probe.

A common mistake is using the same endpoint for both. For example, if your liveness probe fails every time the database is unavailable, Kubernetes may restart healthy application containers during a database outage. In many systems, database availability belongs in readiness, not liveness.

Readiness probe vs startup probe

A startup probe checks whether a slow-starting application has finished booting. While the startup probe is still failing, Kubernetes does not run liveness and readiness probes for that container.

Use a startup probe when your application may take a long time to start, such as a JVM service loading large dependencies. Use a readiness probe to decide whether the app should receive traffic after startup.

Good readiness probe design

A useful readiness probe should answer one question: can this container serve traffic right now?

Good checks often include:

• The application process is running
• The HTTP server or gRPC server is accepting requests
• Required local state is loaded
• Critical downstream dependencies are reachable, when failure means the app cannot serve requests

Avoid making the probe too expensive. If every pod runs a readiness check every 5 seconds, and that check performs multiple database queries, the probe itself can add load to your system.

For most web services, a lightweight internal endpoint such as /ready is better than probing a full user-facing request path.

Operational considerations

• Rolling updates depend on readiness: Bad readiness checks can stall deployments or route traffic too early.
• Readiness affects Services: A not-ready pod is removed from Service endpoints, but direct pod traffic can still reach it.
• Probe timing matters: Aggressive timeouts can mark healthy pods as not ready during short CPU or network spikes.
• External dependencies require care: If every pod marks itself not ready during a shared dependency outage, the Service may have no ready endpoints.
• Cluster upgrades can expose weak probes: During node drains and pod rescheduling, readiness behavior becomes more visible. These practical Kubernetes upgrade tips for startups cover related rollout and availability concerns.

Managing readiness probes as code

Readiness probes are usually defined in Kubernetes manifests, Helm charts, Kustomize overlays, or Terraform-managed Kubernetes resources. If you manage workloads through Terraform, this guide on how to deploy Kubernetes resources using Terraform shows the broader workflow.

Teams that provision cloud infrastructure through Kubernetes APIs may also define workloads and related cloud resources together. For example, Crossplane can manage AWS resources through Kubernetes-style objects, as shown in this guide to deploy AWS resources using Crossplane on Kubernetes.

Practical example

Suppose you run a payment API with 6 replicas behind a Kubernetes Service. A new version starts successfully, but it needs 30 seconds to load routing rules and connect to its fraud-check provider.

Without a readiness probe, Kubernetes may send traffic to the new pods as soon as the containers start. Users could see failed payments or 500 responses.

With a readiness probe, each pod returns failure from /ready until the app can process requests. Kubernetes keeps those pods out of the Service endpoints. Once each pod returns success, Kubernetes starts routing traffic to it.

Key takeaway

A Kubernetes readiness probe is the traffic gate for a pod. It helps Kubernetes route requests only to containers that are prepared to serve them, which makes deployments safer and reduces avoidable errors during startup, rollout, and temporary application issues.