Health Checks

In one sentence: A health check runs a user-defined probe on a timer inside the container and folds the results into a second, orthogonal state — starting, healthy, unhealthy — because "the process is running" says nothing about "the service works."

Running ≠ working

A deadlocked web server is Running forever and serving nothing. The image (or run config) therefore declares a probe — "GET /health returns 200" — plus four knobs: interval (how often), timeout (how long a probe may hang), retries (consecutive failures before declaring unhealthy — one blip shouldn't flip state), and start-period (a warm-up window where failures don't count, so slow-booting apps aren't condemned at birth). Health is a separate little state machine layered on Running:

stateDiagram-v2
  [*] --> Starting: container starts (start-period)
  Starting --> Healthy: first probe passes
  Starting --> Starting: failures ignored (warm-up)
  Healthy --> Healthy: probe passes
  Healthy --> Unhealthy: N consecutive failures
  Unhealthy --> Healthy: probe passes again
  note right of Unhealthy
    engine emits an event —
    consumers decide what to do
    (restart, de-route, alert)
  end note
    

The probe loop

Mechanically each probe is a tiny exec (Lesson 22): run the command in the container's namespaces, exit 0 = pass. The engine only reports health transitions as events — acting on them (restarting, pulling from a load balancer, gating dependent startups in Lesson 35) belongs to consumers. Separating detection from reaction keeps the engine simple and the policy pluggable:

sequenceDiagram
  participant E as Engine (timer)
  participant C as Container
  participant O as Event consumers
  loop every interval
    E->>C: exec probe: GET /health
    C-->>E: exit 0 — pass
  end
  note over C: app deadlocks (process still Running)
  E->>C: probe → timeout (counts as failure 1)
  E->>C: probe → failure 2
  E->>C: probe → failure 3 = retries
  E->>O: event: c-42 Healthy → Unhealthy
  O->>O: policy: restart it / de-route traffic