Add Health Probes
Teach Kubernetes when a container is ready, when it should restart, and when startup needs extra time.
A running process is not necessarily ready to serve traffic. Kubernetes probes turn application-specific health signals into controller decisions.
Download this chapter's files
Use your browser to download either ivia-chapter-07.tar.gz or ivia-chapter-07.zip. The archive is self-contained; you do not need this tutorial repository.
Open a terminal after the browser download:
cd ~/Downloads
tar -xzf ivia-chapter-07.tar.gz
cd ivia-chapter-07
All remaining relative paths in this chapter start from that extracted directory.
The challenge
Challenge: observe healthy probes, deliberately point them at a missing path, diagnose the evidence, and restore the release.
Prerequisites
- A running Minikube cluster and the extracted static source.
- Helm and kubectl.
- Two terminal windows.
Learning goals
- Distinguish readiness, liveness, and startup probes
- Read rendered probe configuration
- Diagnose failures from conditions and events
- Choose conservative probe timings
Prepare the standalone exercise
minikube image build -t simple-static:local static-app
kubectl label node minikube ivia.ch/nodetype=app --overwrite
kubectl create namespace tutorial \
--dry-run=client -o yaml \
| kubectl apply -f -
Three different questions
- Readiness: may this Pod receive Service traffic now? Failure removes it from endpoints without restarting it.
- Liveness: is this process stuck beyond recovery? Repeated failure restarts the container.
- Startup: has a slow application finished starting? It suppresses the other probes until startup succeeds.
Inspect the snapshot and rendered probes:
sed -n '1,200p' static-app/values.yaml
helm template simple-app \
oci://harbor.ivia.ch/ivia-generic-helm-chart/ivia-generic-helm-chart \
--version 4.8.0 -n tutorial \
-f static-app/values.yaml \
| grep -A10 -E 'readinessProbe:|livenessProbe:'
Deploy healthy probes
helm upgrade --install simple-app \
oci://harbor.ivia.ch/ivia-generic-helm-chart/ivia-generic-helm-chart \
--version 4.8.0 -n tutorial --atomic --timeout 5m \
-f static-app/values.yaml
kubectl rollout status deployment/simple-app-frontend -n tutorial --timeout=120s
kubectl get pods -n tutorial
Introduce one controlled failure
mkdir -p work
cp static-app/values.yaml work/broken-probe.yaml
python - <<'PYEDIT'
from pathlib import Path
path = Path('work/broken-probe.yaml')
path.write_text(path.read_text().replace('health: /healthz', 'health: /missing'))
PYEDIT
helm upgrade simple-app \
oci://harbor.ivia.ch/ivia-generic-helm-chart/ivia-generic-helm-chart \
--version 4.8.0 -n tutorial -f work/broken-probe.yaml
Observe briefly and gather evidence:
kubectl get pods -n tutorial -w
# Press Ctrl+C after readiness is 0/1 or restarts appear.
kubectl describe pod -l deploymentName=simple-app -n tutorial
kubectl get events -n tutorial --sort-by=.lastTimestamp
Restore immediately:
helm upgrade simple-app \
oci://harbor.ivia.ch/ivia-generic-helm-chart/ivia-generic-helm-chart \
--version 4.8.0 -n tutorial --atomic --timeout 5m \
-f static-app/values.yaml
kubectl rollout status deployment/simple-app-frontend -n tutorial --timeout=120s
Expected validation
Initially the Pod is 1/1 Running. With /missing, events include an HTTP probe failure with status 404; readiness becomes false and liveness may increase RESTARTS. Restoration returns the newest Pod to 1/1 Running.
Troubleshooting and common pitfalls
- Remote dependency in liveness: avoid it; a temporary dependency outage can create a restart storm.
- Probe port mismatch: use the container port, not a port-forward host port.
- Startup takes longer than delays: add a startup probe instead of making liveness overly patient.
- Atomic rollback hides failure: the deliberate upgrade omits
--atomic; the restoration includes it. - Several matching Pods: describe each Pod by name to separate old and new revisions.
- Release left broken: always perform the restoration before continuing.
Probe failures are Kubernetes explaining what it sees. You now know how to turn that explanation into action.