podman-healthcheck - Manage healthchecks for containers
podman healthcheck subcommand
The podman healthcheck suite of commands are used to manage container healthchecks.
Healthchecks are typically sourced from images. Use
podman image inspect to identify a healthcheck in the
image's Config section.
Healthchecks can also be defined when creating a container via
podman run or podman create using: -
--health-cmd to set the check command (string form runs via
CMD-SHELL; array form uses CMD) - --health-interval,
--health-timeout, --health-retries,
--health-start-period - --no-healthcheck to
disable an image-defined healthcheck - Startup healthcheck knobs:
--health-startup-cmd,
--health-startup-interval,
--health-startup-retries,
--health-startup-success,
--health-startup-timeout
Regular healthcheck runs continuously throughout the
container's lifetime to monitor ongoing health. The
--health-start-period option provides a grace period during
container initialization where failures won't mark the container as
unhealthy.
Startup healthcheck is a separate healthcheck that
runs during container startup and transitions to the regular healthcheck
once the container has successfully started. It's designed for
containers with extended or unpredictable startup times: - Define it
with --health-startup-cmd (requires a regular healthcheck
to also be set) - The startup healthcheck cannot be sourced from an
image; it can only be set manually - Once the startup healthcheck
succeeds (based on --health-startup-success consecutive
successes), it stops and the regular healthcheck takes over - If it
fails too many times (--health-startup-retries), the
container can be restarted based on --health-on-failure
When to use each: - Use
--health-start-period for simple cases where you know
roughly how long startup takes - Use startup healthcheck
(--health-startup-cmd) when startup time is unpredictable
or you need a different check during startup than during normal
operation
To debug or inspect healthchecks: - Use
podman inspect <container> and view
.Config.Healthcheck for the effective settings. Other
relevant sections are .State.Healthcheck,
Config.StartupHealthCheck,
.Config.HealthcheckOnFailureAction,
.Config.HealthMaxLogCount,
.Config.HealthMaxLogSize, and
.Config.HealthLogDestination - Use
podman inspect --format '{{.State.Health.Status}} {{.Config.Healthcheck}}' <container>
to show current health status and healthcheck config - Trigger on-demand
with podman healthcheck run <container> and check the
exit code (0=success, 1=failure, 125=error) - To get more details on why
a healthcheck failed, run
podman --log-level debug healthcheck run <container>
- Ensure the health command exists inside the container and is quoted
properly (prefer single quotes for shell pipelines)
To update healthchecks: - Use
podman update <flag> <container> to update the
healthcheck settings of a container while the container is running -
Example:
podman update --health-max-log-count=10 <container>
to store up to 10 healthcheck results in the log
| Command | Man Page | Description |
|---|---|---|
| run | podman-healthcheck-run(1) | Run a container healthcheck |
podman(1), podman-run(1), podman-create(1), podman-inspect(1), podman-update(1)
Feb 2019, Originally compiled by Brent Baude bbaude@redhat.com