Updated on 2025-07-29 GMT+08:00

Readiness Probes

Once a pod is created, it can be immediately selected by a Service, which forwards requests to the pod. However, it takes time to start a pod. If the pod is not ready for some reason (for example, loading the configuration or data or executing a preheating program), it cannot process requests, resulting in request failures.

To solve this problem, Kubernetes provides readiness probes. A readiness probe can be configured for each container in a pod. A pod is only considered ready when the readiness probes configured for all containers are successful. The pod is then added to the endpoint list of the Service and starts to receive traffic.

A readiness probe periodically detects a container and determines whether it is ready based on responses. Similar to Liveness Probes, there are three kinds of readiness probes.

  • Exec: A probe of this kind executes a command in the target container and determines whether the container is ready based on the exit status code. If 0 is returned, the container is considered ready. If a non-zero value is returned, the container is not ready.
  • HTTP GET: A probe of this kind uses an HTTP GET request. When a probe of this kind is used, kubelet periodically sends an HTTP GET request to the container port (<pod-IP>:<container-port>). If the returned status code is 2xx or 3xx, the probe is successful, and the container is considered ready and can receive traffic. If any other codes are returned, the container is considered not ready, and the Service does not forward traffic to the container.
  • TCP socket: A probe of this kind attempts to establish a TCP connection with the target container. If the connection is successful, the container is considered ready.

How Readiness Probes Work

Readiness probes can be implemented using endpoints. Like in the following figure, when a pod is not ready, its IP address and port (in the format <IP-address>:<port>) is not in the endpoint list. When the pod is ready, its IP address and port is added to the endpoint list.

Figure 1 How readiness probes work

Exec

An exec probe is the same as an HTTP GET probe. As shown below, the exec probe runs the ls /ready command. If the /ready file exists, 0 is returned, indicating that the pod is ready. If the file does not exist, a non-zero status code is returned.

The following uses a Deployment as example. Assume that the nginx image used does not contain the /ready file. Check whether the pods for the Deployment are ready. The following is an example YAML file:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:alpine
        name: container-0
        resources:
          limits:
            cpu: 100m
            memory: 200Mi
          requests:
            cpu: 100m
            memory: 200Mi
        readinessProbe:      # Readiness probe
          exec:              # Defines the ls /ready command.
            command:
            - ls
            - /ready
      imagePullSecrets:
      - name: default-secret

Save the above Deployment definition in the deploy-ready.yaml file, delete the existing Deployment, and use the deploy-ready.yaml file to recreate the Deployment.

# kubectl delete deploy nginx
deployment.apps "nginx" deleted

# kubectl create -f deploy-ready.yaml
deployment.apps/nginx created

As shown below, because the nginx image does not contain the /ready file, the value in the READY column is 0/1, indicating that the pods are not in the ready state.

# kubectl get po
NAME                     READY     STATUS    RESTARTS   AGE
nginx-7955fd7786-686hp   0/1       Running   0          7s
nginx-7955fd7786-9tgwq   0/1       Running   0          7s
nginx-7955fd7786-bqsbj   0/1       Running   0          7s

Create a Service.

apiVersion: v1
kind: Service
metadata:
  name: nginx        
spec:
  selector:          
    app: nginx
  ports:
  - name: service0
    targetPort: 80   
    port: 8080       
    protocol: TCP    
  type: ClusterIP

Check the Service. No values are returned for Endpoints, indicating that there are no endpoints.

$ kubectl describe svc nginx
Name:              nginx
......
Endpoints:         
......

If the /ready file is created in a container to make the readiness probe work, the container will be in the ready state. If you check the pod and endpoints now, you will find that the pod is already ready, and an endpoint is added.

# kubectl exec nginx-7955fd7786-686hp -- touch /ready

# kubectl get po -o wide
NAME                     READY     STATUS    RESTARTS   AGE       IP
nginx-7955fd7786-686hp   1/1       Running   0          10m       192.168.93.169 
nginx-7955fd7786-9tgwq   0/1       Running   0          10m       192.168.166.130
nginx-7955fd7786-bqsbj   0/1       Running   0          10m       192.168.252.160

# kubectl get endpoints
NAME       ENDPOINTS           AGE
nginx      192.168.93.169:80   14d

HTTP GET

A readiness probe is configured in the same way as a liveness probe. It is defined by the containers field in the pod description template. As shown below, the workload has three pods, and each pod contains only one container. After the probe for the container in each pod is successful, the pods will be in the ready state.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:alpine
        name: container-0
        resources:
          limits:
            cpu: 100m
            memory: 200Mi
          requests:
            cpu: 100m
            memory: 200Mi
        readinessProbe:           # Readiness probe
          httpGet:                # Defines an HTTP GET request.
            path: /read
            port: 80
      imagePullSecrets:
      - name: default-secret

TCP Socket

Another kind of readiness probe uses a TCP socket. The following example shows how to define a readiness probe of this kind.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:alpine
        name: container-0
        resources:
          limits:
            cpu: 100m
            memory: 200Mi
          requests:
            cpu: 100m
            memory: 200Mi
        readinessProbe:             # Readiness probe
          tcpSocket:                # Defines a TCP socket.
            port: 80
      imagePullSecrets:
      - name: default-secret

Advanced Settings of Readiness Probes

Similar to a liveness probe, a readiness probe also has the same advanced configuration items, as shown in the output of the describe command of the nginx pod:

Readiness: exec [ls /var/ready] delay=0s timeout=1s period=10s #success=1 #failure=3

The parameters for advanced settings of the readiness probe are detailed as follows:

  • delay=0s indicates that the probe starts immediately after the container is started.
  • timeout=1s indicates that the container must respond to the probe within 1s. If the container fails to respond to the probe, the probe is considered failed.
  • period=10s indicates that the probe is performed every 10s.
  • #success=1 indicates that the probe is considered successful as long as it succeeds once.
  • #failure=3 indicates that the probe is considered failed after three consecutive times.

These are the default configurations when the probe is created. You can modify them as needed.

        readinessProbe:      # Readiness probe
          exec:              # Defines the ls /readiness/ready command.
            command:
            - ls
            - /readiness/ready
          initialDelaySeconds: 10    # The readiness probe is initiated 10s after a container starts.
          timeoutSeconds: 2          # The container must respond within 2s, or the probe is considered failed.
          periodSeconds: 30          # The probe is performed every 30s.
          successThreshold: 1        # The probe is considered successful as long as it succeeds once.
          failureThreshold: 3        # The probe is considered failed after three consecutive failures.