Kubernetes container probes: Liveness, readiness and startup

When a pod starts, Kubernetes begins sending traffic to it immediately once the container process is running. This creates two problems. First, the application might not be ready yet. It could still be loading configuration or waiting for a database connection. Second, the application might be running but deadlocked. The process is alive but not responding. Container probes solve both problems.

The three probe types

Liveness probe

A liveness probe checks whether the container is alive. If it fails beyond the failure threshold, Kubernetes kills the container and restarts it. Use liveness probes to detect deadlocks or unresponsive states where the process is running but the application is not functioning correctly.

Readiness probe

A readiness probe checks whether the container is ready to receive traffic. If it fails, Kubernetes removes the pod from the Service endpoints so no traffic is sent to it. The container is not restarted. When the probe passes again, the pod is added back to the endpoints. Use readiness probes for applications that have a slow startup or that periodically become temporarily unavailable.

Startup probe

A startup probe is for applications that take a long time to start. It disables the liveness probe until it succeeds. Without a startup probe, you would need a large initialDelaySeconds on the liveness probe to accommodate a slow startup, and that same delay would then apply to every subsequent liveness check during normal operation. With a startup probe, the liveness probe only activates once the application has finished starting.

The three probe mechanisms

Timing parameters

Liveness probe examples

httpGet liveness probe

Checks that nginx responds with a 2xx or 3xx status on port 80. If the path does not exist or the server is unresponsive, the probe fails.

1apiVersion: v1
2kind: Pod
3metadata:
4  name: nginx
5spec:
6  containers:
7  - name: nginx
8    image: nginx
9    livenessProbe:
10      httpGet:
11        path: /
12        port: 80
13      initialDelaySeconds: 5
14      periodSeconds: 10
15      failureThreshold: 3

1kubectl apply -f liveness.yaml
2kubectl get pods

Describe the pod to see probe results:

1kubectl describe pod nginx

Look for the Liveness section in the container description and the Events section at the bottom. If the probe is passing, no liveness-related events appear. If it fails, you will see:

1Warning  Unhealthy  kubelet  Liveness probe failed: ...

tcpSocket liveness probe

Checks that a port is accepting TCP connections. Useful for non-HTTP services:

1livenessProbe:
2  tcpSocket:
3    port: 80
4  initialDelaySeconds: 5
5  periodSeconds: 10
6  failureThreshold: 3

If you specify a port that is not open, the probe fails and Kubernetes restarts the container after failureThreshold failures.

exec liveness probe

Runs a command inside the container. Exit code 0 means healthy, anything else means unhealthy:

1livenessProbe:
2  exec:
3    command:
4    - cat
5    - /usr/share/nginx/html/index.html
6  initialDelaySeconds: 5
7  periodSeconds: 10
8  failureThreshold: 3

To demonstrate a failure, exec into the pod and remove the file:

1kubectl exec -it nginx -- sh

1rm /usr/share/nginx/html/index.html
2exit

Describe the pod:

1kubectl describe pod nginx

After three failures (by default every 10 seconds), you will see in the Events section:

1Warning  Unhealthy  kubelet  Liveness probe failed: cat: /usr/share/nginx/html/index.html: No such file or directory
2Normal   Killing    kubelet  Container nginx failed liveness probe, will be restarted

The container is killed and restarted. After the restart the file is restored from the image and the probe passes again.

Readiness probe example

A readiness probe uses the same mechanisms as liveness but controls Service endpoint membership rather than container restarts:

1apiVersion: v1
2kind: Pod
3metadata:
4  name: nginx
5spec:
6  containers:
7  - name: nginx
8    image: nginx
9    readinessProbe:
10      httpGet:
11        path: /
12        port: 80
13      initialDelaySeconds: 5
14      periodSeconds: 5
15      failureThreshold: 3
16    livenessProbe:
17      httpGet:
18        path: /
19        port: 80
20      initialDelaySeconds: 15
21      periodSeconds: 10
22      failureThreshold: 3

Note the different initialDelaySeconds values. The readiness probe starts checking sooner (after 5 seconds) to determine when to add the pod to the Service. The liveness probe waits longer (15 seconds) to give the application time to fully start before Kubernetes considers restarting it.

Startup probe example

Use a startup probe for slow-starting applications. The liveness probe is disabled until the startup probe succeeds:

1apiVersion: v1
2kind: Pod
3metadata:
4  name: slow-app
5spec:
6  containers:
7  - name: app
8    image: my-slow-starting-app
9    startupProbe:
10      httpGet:
11        path: /health
12        port: 8080
13      failureThreshold: 30
14      periodSeconds: 10
15    livenessProbe:
16      httpGet:
17        path: /health
18        port: 8080
19      periodSeconds: 10
20      failureThreshold: 3

With this configuration, the application has up to 300 seconds (30 failures x 10 seconds) to complete startup. Once the startup probe succeeds, the liveness probe takes over with a tighter failure threshold of 3.