Mastering Kubernetes Pod Health Checks: Liveness and Readiness Probes Explained

Pod Health Check Introduction

By default, kubelet uses container runtime status for health, which cannot detect application-level failures such as deadlocks, leading to service loss. Introducing health checks with LivenessProbe (live detection) and ReadinessProbe (ready detection) ensures containers remain healthy.

LivenessProbe (Live Detection)

LivenessProbe checks whether the application inside a container is healthy via HTTP, exec commands, or TCP. If the probe fails, kubelet restarts the pod according to the restartPolicy.

ReadinessProbe (Ready Detection)

ReadinessProbe determines whether a container can accept traffic. Only pods in Ready state are added to a Service's endpoints. This prevents premature request handling before the container finishes initialization.

Health Check Implementation Methods

Both probes support three actions:

ExecAction – run a command inside the container; success if exit code is 0.

HTTPGetAction – send an HTTP request to the container IP/port/path; success for status codes 200‑399.

TCPSocketAction – attempt a TCP connection to the container IP/port; success if the connection is established.

Each action can return Success, Failure, or Unknown.

LivenessProbe Example (ExecAction)

livenessProbe for ExecAction Example

Create a pod that runs Nginx, sleeps 60 seconds, then removes /run/nginx.pid. The exec probe checks for the existence of this file.

cat ngx-health.yaml
apiVersion: v1
kind: Pod
metadata:
  name: ngx-health
spec:
  containers:
  - name: ngx-liveness
    image: nginx:latest
    command:
    - /bin/sh
    - -c
    - /usr/sbin/nginx; sleep 60; rm -rf /run/nginx.pid
    livenessProbe:
      exec:
        command: ["/bin/sh", "-c", "test -e /run/nginx.pid"]
  restartPolicy: Always

Apply and observe events; the pod restarts when the exec probe fails.

livenessProbe for HTTPGetAction Example

Use HTTP GET to request /index.html on port 80. If the response code is 200‑399, the container is considered healthy.

cat ngx-health.yaml
apiVersion: v1
kind: Pod
metadata:
  name: ngx-health
spec:
  containers:
  - name: ngx-liveness
    image: nginx:latest
    command:
    - /bin/sh
    - -c
    - /usr/sbin/nginx; sleep 60; rm -rf /run/nginx.pid
    livenessProbe:
      httpGet:
        path: /index.html
        port: 80
        scheme: HTTP
  restartPolicy: Always

livenessProbe for TCPSocketAction Example

Check TCP connectivity on port 80.

apiVersion: v1
kind: Pod
metadata:
  name: ngx-health
spec:
  containers:
  - name: ngx-liveness
    image: nginx:latest
    command:
    - /bin/sh
    - -c
    - /usr/sbin/nginx; sleep 60; rm -rf /run/nginx.pid
    livenessProbe:
      tcpSocket:
        port: 80
  restartPolicy: Always

Health Check Parameters

initialDelaySeconds

– time after container start before the first check. periodSeconds – interval between checks (default 10s, min 1s). successThreshold – consecutive successes required (must be 1). timeoutSeconds – probe timeout (default 1s, min 1s). failureThreshold – consecutive failures before marking unhealthy (default 1).

Health Check Practice

Example deployment combines both readiness and liveness probes with detailed configuration:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-health-deploy
  namespace: nginx-health-ns
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx-health
  template:
    metadata:
      labels:
        app: nginx-health
    spec:
      restartPolicy: Always
      containers:
      - name: nginx-health-containers
        image: nginx:1.17.1
        command:
        - /bin/sh
        - -c
        - /usr/sbin/nginx; sleep 60; rm -rf /run/nginx.pid
        readinessProbe:
          initialDelaySeconds: 5
          periodSeconds: 10
          successThreshold: 1
          timeoutSeconds: 3
          failureThreshold: 1
          httpGet:
            path: /index.html
            port: 80
            scheme: HTTP
        livenessProbe:
          initialDelaySeconds: 15
          periodSeconds: 3
          successThreshold: 1
          timeoutSeconds: 1
          failureThreshold: 2
          tcpSocket:
            port: 80
        resources:
          requests:
            memory: "64Mi"
            cpu: "250m"
          limits:
            memory: "128Mi"
            cpu: "500m"
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-health-svc
  namespace: nginx-health-ns
spec:
  clusterIP: 10.106.189.88
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: nginx-health
  sessionAffinity: ClientIP
  type: ClusterIP

After applying the manifests, the pods transition from ContainerCreating to Running, with readiness and liveness probes ensuring they only receive traffic when fully initialized.

Observing pod events and logs (e.g., kubectl logs -f pod/ngx-health) shows periodic probe results and restart actions when probes fail.