diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 8cc18f0f75..bca4f434f3 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -481,6 +481,17 @@ Create a container connected to two networks (called net1 and net2) with a stati $ podman create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr ``` +### Define a healthcheck at run time and verify it + +``` +$ podman create -d --name healthcheck-example -p 8080:80 \ + --health-cmd '["CMD-SHELL","wget -q --spider http://127.0.0.1:80 || exit 1"]' \ + --health-interval 30s --health-timeout 5s --health-retries 3 \ + docker.io/library/nginx:alpine + +$ podman inspect --format '{{.State.Health}}' healthcheck-example +``` + ### Rootless Containers Podman runs as a non-root user on most systems. This feature requires that a new enough version of shadow-utils diff --git a/docs/source/markdown/podman-healthcheck-run.1.md b/docs/source/markdown/podman-healthcheck-run.1.md index 863c8969ec..66673428a7 100644 --- a/docs/source/markdown/podman-healthcheck-run.1.md +++ b/docs/source/markdown/podman-healthcheck-run.1.md @@ -34,7 +34,7 @@ $ podman healthcheck run mywebapp ``` ## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-healthcheck(1)](podman-healthcheck.1.md)** +**[podman(1)](podman.1.md)**, **[podman-healthcheck(1)](podman-healthcheck.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-create(1)](podman-create.1.md)**, **[podman-inspect(1)](podman-inspect.1.md)** ## HISTORY Feb 2019, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-healthcheck.1.md b/docs/source/markdown/podman-healthcheck.1.md index 4caf655011..b3e975fabd 100644 --- a/docs/source/markdown/podman-healthcheck.1.md +++ b/docs/source/markdown/podman-healthcheck.1.md @@ -7,7 +7,40 @@ podman\-healthcheck - Manage healthchecks for containers **podman healthcheck** *subcommand* ## DESCRIPTION -podman healthcheck is a set of subcommands that manage container healthchecks +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` + +### Startup Healthcheck vs Regular Healthcheck + +**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 ` 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}}' ` to show current health status and healthcheck config +- Trigger on-demand with `podman healthcheck run ` 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 ` +- Ensure the health command exists inside the container and is quoted properly (prefer single quotes for shell pipelines) + +To update healthchecks: +- Use `podman update ` to update the healthcheck settings of a container while the container is running +- Example: `podman update --health-max-log-count=10 ` to store up to 10 healthcheck results in the log ## SUBCOMMANDS @@ -16,7 +49,7 @@ podman healthcheck is a set of subcommands that manage container healthchecks | run | [podman-healthcheck-run(1)](podman-healthcheck-run.1.md) | Run a container healthcheck | ## SEE ALSO -**[podman(1)](podman.1.md)** +**[podman(1)](podman.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-create(1)](podman-create.1.md)**, **[podman-inspect(1)](podman-inspect.1.md)**, **[podman-update(1)](podman-update.1.md)** ## HISTORY Feb 2019, Originally compiled by Brent Baude diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 3afd707c8a..ea97263cdb 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -930,6 +930,17 @@ Fri Nov 19 23:10:55 UTC 2021 $ podman run --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr ``` +### Define a healthcheck at run time and verify it + +``` +$ podman create -d --name healthcheck-example -p 8080:80 \ + --health-cmd '["CMD-SHELL","wget -q --spider http://127.0.0.1:80 || exit 1"]' \ + --health-interval 30s --health-timeout 5s --health-retries 3 \ + docker.io/library/nginx:alpine + +$ podman inspect healthcheck-example | jq '.[0].State.Health' +``` + ### Rootless Containers Podman runs as a non-root user on most systems. This feature requires that a new enough version of **shadow-utils**