podman healthcheck runs a container health probe, and the --health-cmd flags define one so CI can wait until a service is ready.
Tests that race a slow-starting service flake. A health check plus a wait loop on the health status makes the pipeline deterministic.
What it does
A health check is a command Podman runs inside a container on an interval; its exit status sets the container health to starting, healthy, or unhealthy. podman healthcheck run triggers it on demand, and podman inspect reads the resulting status.
Common usage
Terminal
podman run -d --name db \
--health-cmd 'pg_isready -U postgres' \
--health-interval 5s --health-retries 5 --health-start-period 10s \
docker.io/library/postgres:16
# wait until healthy
until [ "$(podman inspect -f '{{.State.Health.Status}}' db)" = healthy ]; do sleep 2; done
podman healthcheck run db
Options
Flag/Command
What it does
--health-cmd <cmd>
Command that probes container health
--health-interval <dur>
Time between checks
--health-retries <n>
Failures before marking unhealthy
--health-start-period <dur>
Grace period before failures count
healthcheck run <ctr>
Run the check once on demand
{{.State.Health.Status}}
Inspect field with the current status
In CI
Define a health check on service containers and poll {{.State.Health.Status}} in a bounded until loop before running tests, so a slow database does not cause flaky failures. Cap the loop with a timeout so a never-healthy container fails the job instead of hanging.
Common errors in CI
"Error: container ... has no defined healthcheck" from podman healthcheck run means the image and run command set no --health-cmd; add one. A status stuck at "starting" means the start period has not elapsed or the probe never succeeds; check the command with podman exec. An unbounded wait loop hangs the job when the container is "unhealthy"; add a max iteration count.
Frequently asked questions
podman healthcheck: Wait For a Service in CI?
Tests that race a slow-starting service flake. A health check plus a wait loop on the health status makes the pipeline deterministic.
What it does?
A health check is a command Podman runs inside a container on an interval; its exit status sets the container health to starting, healthy, or unhealthy. podman healthcheck run triggers it on demand, and podman inspect reads the resulting status.
In CI?
Define a health check on service containers and poll {{.State.Health.Status}} in a bounded until loop before running tests, so a slow database does not cause flaky failures. Cap the loop with a timeout so a never-healthy container fails the job instead of hanging.
Common errors in CI?
"Error: container ... has no defined healthcheck" from podman healthcheck run means the image and run command set no --health-cmd; add one. A status stuck at "starting" means the start period has not elapsed or the probe never succeeds; check the command with podman exec.
