Kubernetes Health Probes

A running container is not always a working container. A web server can freeze, a database connection can break, or an application can need a minute to warm up. Health probes let Kubernetes check the real condition of an application and react without human help.

The Doctor Visit Analogy

Picture a nurse who visits patients every few minutes. One question asks whether the patient is alive. Another asks whether the patient is ready to receive visitors. A third question applies only to a patient who just woke from surgery: is the patient fully awake yet? Kubernetes asks these same three questions through three probe types.

The Three Probe Types

Probe	Question	Action on failure
Liveness	Is the container still healthy?	Kubelet restarts the container
Readiness	Can the container serve traffic now?	Pod leaves the service endpoints until it recovers
Startup	Has the application finished starting?	Kubelet restarts the container if startup never completes

Liveness Probe

This probe detects deadlocks and frozen processes. A failed check triggers a container restart, which often clears the problem.

Readiness Probe

This probe protects users. A pod that fails readiness stays running but receives no traffic. Use it during warm-up, during heavy load, or when a dependency such as a database goes offline.

Startup Probe

Slow applications need extra time to boot. A startup probe holds back the liveness and readiness probes until the application starts. This prevents a liveness probe from killing a container that still loads data.

Diagram: Kubelet Checking a Pod

 ┌─────────┐   every 10 sec    ┌──────────────────────┐
 │ Kubelet │ ────────────────▶ │ Container            │
 │ (node)  │ ◀──────────────── │ GET /healthz         │
 └─────────┘   200 OK / fail   └──────────────────────┘
      │
      ├── Liveness fails   ──▶ restart container
      ├── Readiness fails  ──▶ remove from Service
      └── Startup passes   ──▶ begin other probes

Probe Methods

• httpGet sends an HTTP request. Status codes from 200 to 399 count as success.
• tcpSocket opens a TCP connection to a port. An open port counts as success.
• exec runs a command inside the container. Exit code 0 counts as success.
• grpc calls the gRPC health checking service for applications that speak gRPC.

Writing a Complete Example

apiVersion: v1
kind: Pod
metadata:
  name: orders-pod
spec:
  containers:
  - name: orders
    image: myrepo/orders:1.0
    ports:
    - containerPort: 8080
    startupProbe:
      httpGet:
        path: /healthz
        port: 8080
      failureThreshold: 30
      periodSeconds: 5
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
      periodSeconds: 10
      failureThreshold: 3
    readinessProbe:
      httpGet:
        path: /ready
        port: 8080
      periodSeconds: 5
      failureThreshold: 2

The startup probe allows up to 150 seconds (30 attempts at 5 second gaps) for the application to boot. Liveness and readiness checks begin only after startup succeeds.

Probe Settings

Setting	Meaning	Default
initialDelaySeconds	Wait before the first check	0
periodSeconds	Gap between checks	10
timeoutSeconds	Time allowed for one reply	1
successThreshold	Passes needed to count as healthy	1
failureThreshold	Failures allowed before action	3

Diagram: Pod Lifecycle with Probes

 Container starts
       │
       ▼
 Startup probe running ── fails too long ──▶ Restart
       │ passes
       ▼
 ┌─────────────────────────────────────────┐
 │ Liveness probe  : keeps checking health │
 │ Readiness probe : controls traffic flow │
 └─────────────────────────────────────────┘
       │
       ▼
 Ready ──▶ pod receives Service traffic

Design Tips

• Create a dedicated /healthz endpoint that checks only the application itself.
• Keep liveness checks light. A liveness probe that tests an external database can restart every pod when the database slows down.
• Let readiness checks include dependencies, since removing a pod from traffic carries no restart cost.
• Set realistic timeouts. A one second timeout on a slow endpoint produces false alarms.
• Test probes in a staging cluster before production.

Common Mistakes

• Skipping readiness probes sends users to pods that still load. Rolling updates replace healthy pods with unready ones.
• Setting initialDelaySeconds too low restarts a slow application in an endless loop. Add a startup probe to cover the boot period.
• Using the same endpoint and thresholds for liveness and readiness hides the difference between "restart me" and "pause traffic".

Inspecting Probe Results

kubectl describe pod orders-pod
kubectl get pod orders-pod -w
kubectl get endpoints orders-service

The Events section of describe shows messages such as "Readiness probe failed" or "Liveness probe failed", along with the status code returned.

Key Points

• Liveness restarts broken containers.
• Readiness controls whether a pod receives traffic.
• Startup protects slow applications during boot.
• Rolling updates rely on readiness to move traffic safely.