Mastering Kubernetes Probes: Readiness, Liveness, and Startup Explained

Background

Kubernetes uses many asynchronous mechanisms and decoupled object designs, so when pod counts change or a rolling update occurs, service and ingress configurations may not refresh in time, causing brief outages. To mitigate this, Kubernetes provides three health probes: StartupProbe , LivenessProbe , and ReadinessProbe .

Pod States

Pending : Pod creation request cannot be scheduled because no node satisfies the requirements.

Running : All containers are created and at least one is running, starting, or restarting.

Succeeded : All containers have terminated successfully.

Failed : All containers have terminated, but at least one exited with failure.

Unknown : The apiserver cannot communicate with the node’s kubelet to obtain status.

Pod Restart Policies

Always : Restart the container whenever it exits.

OnFailure : Restart only if the container exits with a non‑zero status.

Never : Do not restart the container regardless of exit status.

Probe Overview

Kubernetes offers three probe types:

ReadinessProbe

LivenessProbe

StartupProbe (added in v1.16)

Purpose of Probes

Probes monitor container health and control traffic routing. ReadinessProbe removes a pod’s IP from Service endpoints when it fails, preventing traffic to an unhealthy pod. LivenessProbe kills an unhealthy container, triggering the pod’s restart policy. StartupProbe handles cases where the application needs a long initialization period before the other probes become reliable.

Probe Types and Detection Methods

Both Liveness and Readiness probes support three detection methods:

exec : Run a command inside the container; success is indicated by exit code 0.

httpGet : Perform an HTTP GET request; a status code between 200 and 399 is considered healthy.

tcpSocket : Attempt a TCP connection; success means the socket opens.

Probe results can be Success , Failure , or Unknown .

Common Probe Fields

initialDelaySeconds : Seconds to wait after container start before probing begins.

periodSeconds : Interval between probe attempts.

timeoutSeconds : Seconds to wait for a probe response before considering it failed.

successThreshold : Minimum consecutive successes required (must be 1 for Liveness).

failureThreshold : Consecutive failures required before the pod is marked unhealthy (default 3 for Readiness).

Tip: ReadinessProbe failures do not restart the pod; only StartupProbe and LivenessProbe can trigger a restart.

StartupProbe Behavior

If all three probes are defined, StartupProbe runs first and disables the other two until it succeeds. After a successful StartupProbe, Liveness and Readiness probes become active for the remainder of the container’s life.

Practical Usage Examples

LivenessProbe Examples

Exec‑based LivenessProbe

apiVersion: v1
kind: Pod
metadata:
  name: liveness-exec
  labels:
    app: liveness
spec:
  containers:
  - name: liveness
    image: busybox
    args:
    - /bin/sh
    - -c
    - "touch /tmp/healthy; sleep 30; rm -rf /tmp/healthy; sleep 600"
    livenessProbe:
      initialDelaySeconds: 10
      periodSeconds: 5
      exec:
        command:
        - cat
        - /tmp/healthy

HTTP‑based LivenessProbe

apiVersion: v1
kind: Pod
metadata:
  name: liveness-http
  labels:
    test: liveness
spec:
  containers:
  - name: liveness
    image: test.com/test-http-prober:v0.0.1
    livenessProbe:
      failureThreshold: 5
      initialDelaySeconds: 20
      periodSeconds: 10
      timeoutSeconds: 5
      successThreshold: 2
      httpGet:
        scheme: HTTP
        port: 8081
        path: /ping

TCP‑based LivenessProbe

apiVersion: v1
kind: Pod
metadata:
  name: liveness-tcp
  labels:
    app: liveness
spec:
  containers:
  - name: liveness
    image: nginx
    livenessProbe:
      initialDelaySeconds: 15
      periodSeconds: 20
      tcpSocket:
        port: 80

ReadinessProbe Examples

apiVersion: v1
kind: Pod
metadata:
  name: readiness-exec
  labels:
    app: readiness-exec
spec:
  containers:
  - name: readiness-exec
    image: busybox
    args:
    - /bin/sh
    - -c
    - "touch /tmp/healthy; sleep 30; rm -rf /tmp/healthy; sleep 600"
    livenessProbe:
      initialDelaySeconds: 10
      periodSeconds: 5
      exec:
        command:
        - cat
        - /tmp/healthy
---
apiVersion: v1
kind: Pod
metadata:
  name: readiness-http
  labels:
    app: readiness-http
spec:
  containers:
  - name: readiness-http
    image: test.com/test-http-prober:v0.0.1
    ports:
    - name: server
      containerPort: 8080
    - name: management
      containerPort: 8081
    readinessProbe:
      initialDelaySeconds: 20
      periodSeconds: 5
      timeoutSeconds: 10
      httpGet:
        scheme: HTTP
        port: 8081
        path: /ping

StartupProbe Example

apiVersion: v1
kind: Pod
metadata:
  name: startup
  labels:
    app: startup
spec:
  containers:
  - name: startup
    image: nginx
    startupProbe:
      failureThreshold: 3
      initialDelaySeconds: 5
      timeoutSeconds: 10
      periodSeconds: 5
      httpGet:
        path: /test
        port: 80

Additional Notes

The terminationGracePeriodSeconds parameter is important for graceful shutdowns but cannot be used with ReadinessProbe; the apiserver will reject such configurations.

Conclusion

Understanding and correctly configuring Startup, Liveness, and Readiness probes enables you to maximize pod availability, safety, and resilience. No single solution fits all scenarios, so each workload requires a tailored probe strategy.