Skip to main content
Mapagam

Managing Container Health

1. Defining Healthchecks in Dockerfile

Directive Description Example
HEALTHCHECK Defines a command to check the container's health HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 CMD curl -f http://localhost:8080/health || exit 1

Example: Defining a Healthcheck in Dockerfile

FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 CMD curl -f http://localhost:8080/health || exit 1
CMD ["npm", "start"]
Note: The HEALTHCHECK instruction is supported in Dockerfile and can be used to define a command that checks the container's health status.

2. Configuring Health Intervals

Option Values Description
--health-interval 30s Time between health checks (default: 30s)
--health-timeout 3s Maximum time to wait for a health check to complete (default: 3s)
--health-retries 3 Number of consecutive failures to mark container as unhealthy (default: 3)
--health-start-period 0s Period to wait before starting health checks (default: 0s)

Example: Setting custom health check intervals

docker run --name myapp \
  --health-interval=10s \
  --health-timeout=5s \
  --health-retries=3 \
  --health-start-period=30s \
  myapp-image
Note: Health check intervals are defined in seconds, minutes, or hours using suffixes like s, m, h.

3. Setting Health Timeout

Option Values Description
--health-timeout 30s Timeout for each health check command to complete before it is considered failed
--health-start-period 0s Period after container start before health checks are initiated
--health-retries 3 Number of consecutive failures to consider container unhealthy
--health-interval 30s Interval between health checks

Example: Setting Health Check Timeout

docker run --health-cmd "curl -f http://localhost/health || exit 1" \
    --health-timeout 10s \
    --health-start-period 30s \
    --health-retries 3 \
    --health-interval 5s \
    nginx

4. Defining Health Retries

Option Values Description
HEALTHCHECK --retries=N 5 Number of consecutive failures before container is considered unhealthy

Example: Setting Health Check Retries

HEALTHCHECK --interval=30s --timeout=10s --retries=3 CMD curl -f http://localhost/health || exit 1
Note: Default value for --retries is 3.

5. Setting Start Period

Property Value Description
startPeriod 5s Start period for the container to initialize before the healthcheck starts counting. Defaults to 0s.

Example: Using startPeriod in Dockerfile

FROM node:18
WORKDIR /app
COPY . .
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=10s --startPeriod=5s --retries=3 CMD curl -f http://localhost:3000/health || exit 1
CMD ["npm", "start"]

6. Using Custom Health Commands

Command Description Example
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 Defines custom health check configuration HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 CMD curl -f http://localhost/health || exit 1
CMD Runs a command to check container health CMD curl -f http://localhost/health || exit 1
--interval Time between health checks (default 30s) HEALTHCHECK --interval=60s CMD curl -f http://localhost/health || exit 1
--timeout Maximum time to wait for command completion (default 30s) HEALTHCHECK --timeout=5s CMD curl -f http://localhost/health || exit 1
--start-period Grace period before health checks start (default 0s) HEALTHCHECK --start-period=30s CMD curl -f http://localhost/health || exit 1
--retries Number of consecutive failures to mark container as unhealthy (default 3) HEALTHCHECK --retries=5 CMD curl -f http://localhost/health || exit 1

Example: Custom Health Check with HTTP Endpoint

FROM nginx:latest
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost/health || exit 1

Example: Health Check with Script

FROM node:18-alpine
COPY health-check.sh /usr/local/bin/health-check.sh
RUN chmod +x /usr/local/bin/health-check.sh
HEALTHCHECK --interval=30s --timeout=10s CMD /usr/local/bin/health-check.sh
Note: The health check command runs inside the container's environment and must return an exit code of 0 for healthy or non-zero for unhealthy.

7. Viewing Container Health Status

Command Description Example
docker inspect Displays detailed configuration and status information about a container, including health check details. docker inspect --format='{{.State.Health}}' my-container
docker ps Lists running containers with health status in the output. docker ps --format "table {{.Names}}\t{{.Health}}"
docker stats Shows real-time resource usage and health status for containers. docker stats --format "table {{.Name}}\t{{.Health}}"

Example: Inspecting Health Check Details

docker inspect --format='{{.State.Health}}' my-app

Output example:

{
  "Status": "healthy",
  "FailingStreak": 0,
  "Log": [
    {
      "Start": "2025-04-01T10:00:00Z",
      "End": "2025-04-01T10:00:01Z",
      "ExitCode": 0,
      "Output": "OK"
    }
  ]
}
Note: The docker inspect command provides detailed JSON output that includes the health check log and status history.

8. Monitoring Health Events

Example: Health Check Configuration

FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["npm", "start"]
Option Values Description
--interval 30s Time between health checks
--timeout 10s Maximum time to complete a check
--start-period 5s Grace period before checks start
--retries 3 Number of failures before unhealthy
Note: Health checks are only available in Docker 1.12+ and require the container to be run with --healthcheck or via Dockerfile HEALTHCHECK instruction.

Example: Inspecting Health Status

docker inspect --format='{{json .State.Health}}' container_name

Example: Viewing Health Logs

docker events --filter container=container_name --filter event=die

9. Disabling Healthchecks

Option Description Usage
--no-healthcheck Disables any healthcheck configured in the Dockerfile docker run --no-healthcheck my-image
HEALTHCHECK NONE Disables healthcheck in the Dockerfile during build 
FROM ubuntu:20.04
HEALTHCHECK NONE

Example: Disabling Healthcheck in Runtime

docker run --no-healthcheck myapp:latest
Note: Disabling healthchecks can lead to undetected container failures and is generally not recommended in production environments.

10. Implementing Dependency Health Checks

Check Type Configuration Description Notes
CMD CMD ["curl", "-f", "http://localhost:8080/health"] Executes a command to check service health Can be used with any executable or script
HTTP GET HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 Performs an HTTP GET request to a specified endpoint Useful for checking web services or APIs
TCP HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 Checks if a specific port is accessible Good for checking database or network services

Example: HTTP GET Health Check

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

Example: TCP Port Health Check

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD nc -z localhost 5432
Note: The --start-period option delays the first check until after the specified time, which is useful for services that take time to start up.

11. Understanding Health States

State Description Indicator Actions
healthy Container is running and all health checks pass NEW Continue normal operations
unhealthy One or more health checks have failed DEPRECATED Restart or terminate container
starting Container is initializing and health checks are not yet active BETA Wait for health check to complete
none Health checks are not configured for the container EXPERIMENTAL Configure health checks for monitoring

Example: Health Check Configuration

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1
Note: The HEALTHCHECK instruction defines how Docker should check the container's health status.
Warning: If a container's health check fails repeatedly, Docker will restart it based on the --retries setting.

12. Handling Health Failures Gracefully

Option Values Notes
healthcheck HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 CMD curl -f http://localhost:8080/health || exit 1 Defines health check configuration for a container
--interval 30s How often to run the health check (default 30s)
--timeout 3s Maximum time to wait for the health check to complete (default 30s)
--start-period 5s Grace period before health checks begin (default 0s)
--retries 3 Number of consecutive failures to mark container as unhealthy (default 3)

Example: Health Check Configuration in Dockerfile

FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 CMD curl -f http://localhost:8080/health || exit 1
CMD ["npm", "start"]

Example: Health Check in Compose File

version: '3.8'
services:
  app:
    image: myapp
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s
Note: If a container's health check fails, Docker will mark it as unhealthy and restart it if configured to do so.
Warning: Setting --retries too low can cause premature restarts during temporary outages.

Best Practices for Health Checks

  • Use --start-period to allow applications time to initialize before health checks begin.
  • Set --timeout to a value that reflects the expected maximum response time.
  • Ensure health check commands do not impact application performance or resource usage.

Was this article helpful?

Related Cheat Sheets