'\" t
.nh
.TH podman-healthcheck 1
.SH NAME
podman-healthcheck \- Manage healthchecks for containers

.SH SYNOPSIS
\fBpodman healthcheck\fP \fIsubcommand\fP

.SH DESCRIPTION
The \fBpodman healthcheck\fP suite of commands are used to manage container healthchecks.

.PP
Healthchecks are typically sourced from images. Use \fBpodman image inspect\fR to identify a healthcheck in the image's Config section.

.PP
Healthchecks can also be defined when creating a container via \fBpodman run\fR or \fBpodman create\fR using:
- \fB--health-cmd\fR to set the check command (string form runs via CMD-SHELL; array form uses CMD)
- \fB--health-interval\fR, \fB--health-timeout\fR, \fB--health-retries\fR, \fB--health-start-period\fR
- \fB--no-healthcheck\fR to disable an image-defined healthcheck
- Startup healthcheck knobs: \fB--health-startup-cmd\fR, \fB--health-startup-interval\fR, \fB--health-startup-retries\fR, \fB--health-startup-success\fR, \fB--health-startup-timeout\fR

.SS Startup Healthcheck vs Regular Healthcheck
\fBRegular healthcheck\fP runs continuously throughout the container's lifetime to monitor ongoing health. The \fB--health-start-period\fR option provides a grace period during container initialization where failures won't mark the container as unhealthy.

.PP
\fBStartup healthcheck\fP 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 \fB--health-startup-cmd\fR (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 \fB--health-startup-success\fR consecutive successes), it stops and the regular healthcheck takes over
- If it fails too many times (\fB--health-startup-retries\fR), the container can be restarted based on \fB--health-on-failure\fR

.PP
\fBWhen to use each:\fP
- Use \fB--health-start-period\fR for simple cases where you know roughly how long startup takes
- Use startup healthcheck (\fB--health-startup-cmd\fR) when startup time is unpredictable or you need a different check during startup than during normal operation

.PP
To debug or inspect healthchecks:
- Use \fBpodman inspect <container>\fR and view \fB\&.Config.Healthcheck\fR for the effective settings. Other relevant sections are \fB\&.State.Healthcheck\fR, \fBConfig.StartupHealthCheck\fR, \fB\&.Config.HealthcheckOnFailureAction\fR, \fB\&.Config.HealthMaxLogCount\fR, \fB\&.Config.HealthMaxLogSize\fR, and \fB\&.Config.HealthLogDestination\fR
- Use \fBpodman inspect --format '{{.State.Health.Status}} {{.Config.Healthcheck}}' <container>\fR to show current health status and healthcheck config
- Trigger on-demand with \fBpodman healthcheck run <container>\fR and check the exit code (0=success, 1=failure, 125=error)
    - To get more details on why a healthcheck failed, run \fBpodman --log-level debug healthcheck run <container>\fR
- Ensure the health command exists inside the container and is quoted properly (prefer single quotes for shell pipelines)

.PP
To update healthchecks:
- Use \fBpodman update <flag> <container>\fR to update the healthcheck settings of a container while the container is running
- Example: \fBpodman update --health-max-log-count=10 <container>\fR to store up to 10 healthcheck results in the log

.SH SUBCOMMANDS
.TS
allbox;
l l l 
l l l .
\fBCommand\fP	\fBMan Page\fP	\fBDescription\fP
run	podman-healthcheck-run(1)	Run a container healthcheck
.TE

.SH SEE ALSO
\fBpodman(1)\fP, \fBpodman-run(1)\fP, \fBpodman-create(1)\fP, \fBpodman-inspect(1)\fP, \fBpodman-update(1)\fP

.SH HISTORY
Feb 2019, Originally compiled by Brent Baude bbaude@redhat.com
\[la]mailto:bbaude@redhat.com\[ra]