Added healthcheck documentation.

Fixes: #27202

Signed-off-by: Alex Bunea <1alexbunea@gmail.com>

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

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 <bbaude@redhat.com>

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 <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
 
 ## 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 <bbaude@redhat.com>

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**