Kubernetes Container Health Probe Flow

Kubernetes Container Health Probe Flow is the operational sequence the kubelet follows when executing startup, liveness, and readiness probes against a container, from initial delay through periodic checking, threshold accumulation, and the resulting state change each probe type triggers. This flow runs independently for every container that declares probes, on a schedule entirely local to the kubelet on the node hosting that container.

Probe Mechanisms

The Three Check Types

A probe performs one of three kinds of check against the container:

• httpGet: issues an HTTP GET request to a specified path and port, treating any response in the 200–399 range as success.
• tcpSocket: attempts to open a TCP connection to a specified port, treating a successful connection as success.
• exec: runs a command inside the container's namespace, treating a zero exit code as success.

containers:
  - name: app
    livenessProbe:
      exec:
        command: ["cat", "/tmp/healthy"]
      periodSeconds: 10

Timing Parameters

initialDelaySeconds and periodSeconds

initialDelaySeconds delays the very first probe execution after the container starts, giving the process a minimum grace period before any check is attempted. periodSeconds sets the interval between subsequent checks once probing begins.

timeoutSeconds

timeoutSeconds bounds how long the kubelet waits for a single probe attempt to respond before counting it as a failure, independent of the check interval.

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
  timeoutSeconds: 2

Threshold Accumulation

failureThreshold and successThreshold

A single failed probe does not immediately change container state; the kubelet requires failureThreshold consecutive failures before acting, and correspondingly successThreshold consecutive successes before flipping a probe back to passing, which prevents transient blips from causing unnecessary state churn.

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  failureThreshold: 3
  successThreshold: 1

Startup Probe Gating

Suppressing Other Probes During Initialization

When a startupProbe is defined, the kubelet runs only that probe first, on its own schedule, and does not begin evaluating liveness or readiness probes until the startup probe reports success. This lets slow-starting applications receive a longer effective grace period without weakening the liveness probe's sensitivity once the application is actually running.

startupProbe:
  httpGet:
    path: /startupz
    port: 8080
  failureThreshold: 30
  periodSeconds: 2

Divergent Outcomes Per Probe Type

Liveness Failure Path

When a liveness probe accumulates failureThreshold consecutive failures, the kubelet kills the container and routes it through the restart mechanism governed by restartPolicy, incrementing restartCount.

Readiness Failure Path

When a readiness probe accumulates failureThreshold consecutive failures, the kubelet sets the container's ready field to false and updates the Pod's ContainersReady and Ready conditions accordingly, without killing or restarting the container.

status:
  containerStatuses:
    - name: app
      ready: false
      state:
        running: {}

Probe Flow Diagram

This divergence at the threshold point is the key design detail of probe flow: identical failure detection mechanics feed into two entirely different remediation actions depending on which probe type observed the failure.