Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 37 ยท Projects and Workloads

Pods, Containers and Health Probes

Understand the Pod lifecycle, multi-container Pods, init containers, and configure liveness, readiness and startup probes so OpenShift restarts and routes correctly.

A Pod is the smallest thing OpenShift runs. It holds one or more containers that share a network address and storage volumes. You rarely create bare Pods; Deployments and Jobs create them for you. But you will read Pod status constantly, so it pays to understand how a Pod lives and how the platform decides whether it is healthy.

Pod lifecycle

A Pod moves through phases: Pending (accepted, not all containers running yet), Running, Succeeded or Failed (for Pods that finish), and Unknown. Inside, each container has its own state: Waiting (with a reason such as ImagePullBackOff), Running or Terminated (with an exit code).

When a Pod must stop, OpenShift sends SIGTERM to the container's main process, waits for the termination grace period (30 seconds by default), then sends SIGKILL. Your app should catch SIGTERM, finish in-flight requests and exit. A preStop hook can add a short delay, which helps the router stop sending new requests before the process exits.

Multi-container Pods

Containers in one Pod share localhost and volumes, and are scheduled together. Use this only when the parts are tightly coupled:

  • a sidecar (log shipper, proxy),
  • an init container, which runs to completion before the main containers start (wait for a dependency, fetch config, run a migration).
YAML
spec:
  initContainers:
    - name: wait-for-db
      image: registry.access.redhat.com/ubi9/ubi-minimal
      command: ["sh", "-c", "until getent hosts db; do sleep 2; done"]
  containers:
    - name: web
      image: quay.io/example/web:1.0

Separate processes that scale independently (web and database) belong in separate Deployments, not one Pod.

Why probes exist

A running process is not the same as a working app. A web server may be deadlocked, still loading data, or temporarily overloaded. Probes let the platform ask the app directly. There are three kinds.

Probe Question If it fails
Startup Has the app finished starting? Container is restarted; liveness and readiness wait for it
Readiness Can it serve traffic right now? Pod is removed from Service endpoints (no restart)
Liveness Is it still alive, not stuck? Container is restarted

Each probe can use an HTTP GET (success on 200-399), a TCP socket connect, an exec command (exit code 0) or gRPC.

YAML
containers:
  - name: web
    image: quay.io/example/web:1.0
    startupProbe:
      httpGet: { path: /healthz, port: 8080 }
      failureThreshold: 30
      periodSeconds: 2
    readinessProbe:
      httpGet: { path: /ready, port: 8080 }
      periodSeconds: 5
      failureThreshold: 2
    livenessProbe:
      httpGet: { path: /healthz, port: 8080 }
      initialDelaySeconds: 10
      periodSeconds: 10
      failureThreshold: 3

Useful fields: initialDelaySeconds, periodSeconds, timeoutSeconds, successThreshold and failureThreshold. The example gives the app up to 30 x 2 = 60 seconds to start before the liveness probe applies.

stateDiagram-v2
  [*] --> Starting
  Starting --> Started: startup probe passes
  Started --> Ready: readiness passes
  Ready --> NotReady: readiness fails
  NotReady --> Ready: readiness passes again
  Started --> Restarted: liveness fails
  Ready --> Restarted: liveness fails
  Restarted --> Starting

Figure: readiness controls traffic; liveness controls restarts.

Rules of thumb

  • Readiness should check what this Pod needs to serve, such as "my cache is warm and my database connection works". Be careful: if every Pod depends on a shared database in the readiness check and the database blips, all Pods become unready at once.
  • Liveness should be simple. A liveness check that calls the database can restart healthy Pods during a database outage and make things worse. Check only that the process can respond.
  • Use a startup probe for slow starters instead of a huge initialDelaySeconds.
  • Add a short readiness period so bad Pods leave rotation quickly.

Inspecting Pods

Terminal
oc get pod web-6d5f-aaaa -o wide
oc describe pod web-6d5f-aaaa
oc logs web-6d5f-aaaa
oc logs web-6d5f-aaaa --previous
oc logs web-6d5f-aaaa -c sidecar
oc rsh web-6d5f-aaaa
oc exec web-6d5f-aaaa -- env
oc debug deployment/web
oc port-forward web-6d5f-aaaa 8080:8080

oc rsh opens a shell in the container; oc debug starts a copy of the Pod with a shell (useful when the real one crashes at start); oc port-forward tunnels a local port to the Pod. The Events at the bottom of oc describe pod show probe failures as Readiness probe failed: ... or Liveness probe failed: ....

Stand-in: simulate probes

The stand-in below simulates a Pod over time. It shows how a failing readiness check removes the Pod from traffic while a failing liveness check restarts it. It is a model with fixed numbers, not a kubelet.

Python Stand-in: readiness and liveness over time

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: shutdown with a grace period

Python Stand-in: graceful shutdown

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common mistakes

  • Using the same endpoint for liveness and a heavy readiness check.
  • Setting timeoutSeconds smaller than the app's normal response time under load.
  • Ignoring SIGTERM, so every rollout waits the full grace period.
  • Running shells as PID 1 that do not forward signals; use exec in start scripts.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens when a readiness probe fails?

    Failing readiness stops traffic to the Pod. Only a failing liveness (or startup) probe restarts the container.
  2. 2. Why use a startup probe?

    A startup probe pauses liveness and readiness until the app has started, avoiding restarts of slow starters.
  3. 3. What is an init container?

    Init containers run in order and must succeed before the app containers begin.
  4. 4. Which command shows the logs of the previous crashed container?

    --previous prints the logs of the prior container instance, which is how you read a crash.

Summary

  • A Pod shares network and volumes among its containers; init containers run first.
  • OpenShift stops Pods with SIGTERM, a grace period, then SIGKILL.
  • Readiness controls traffic, liveness controls restarts, startup protects slow starts.
  • Keep liveness checks simple and readiness checks honest about what the Pod needs.
  • Use oc logs, describe, rsh, debug and port-forward to inspect Pods.

Next: ConfigMaps and Secrets