Container health checks in Docker - Step-by-Step Execution

Process Flow - Container health checks

Start Container

↓

Run Health Check Command

↓

Check Command Exit Code

↓

Mark Healthy

↓

Repeat Health Check Periodically

↓

Container Status Updated

The container runs a health check command repeatedly. If the command succeeds, the container is healthy; if it fails, it is unhealthy.

Execution Sample

Docker

HEALTHCHECK --interval=5s --timeout=2s \
  CMD curl -f http://localhost/ || exit 1

This Dockerfile instruction sets a health check that tries to curl the container's localhost every 5 seconds and fails if curl returns an error.

Process Table

Check Number	Health Check Command	Exit Code	Health Status	Action
1	curl -f http://localhost/	0	Healthy	Container marked healthy
2	curl -f http://localhost/	0	Healthy	Container remains healthy
3	curl -f http://localhost/	1	Unhealthy	Container marked unhealthy
4	curl -f http://localhost/	1	Unhealthy	Container remains unhealthy
5	curl -f http://localhost/	0	Healthy	Container marked healthy

💡 Health checks continue periodically; this trace shows status changes over 5 checks.

Status Tracker

Variable	Start	After 1	After 2	After 3	After 4	After 5
Exit Code	N/A	0	0	1	1	0
Health Status	Starting	Healthy	Healthy	Unhealthy	Unhealthy	Healthy

Key Moments - 2 Insights

Why does the container become unhealthy at check 3 even though it was healthy before?

Because the health check command returned exit code 1 at check 3, indicating failure, so the container status changed to unhealthy as shown in execution_table row 3.

Does the container stay unhealthy forever after one failure?

No, the container status updates on each health check. At check 5, the command succeeded again, so the container became healthy again (execution_table row 5).

Visual Quiz - 3 Questions

Look at the execution table, what is the health status after the second health check?

A Healthy

B Unhealthy

C Starting

D Unknown

💡 Hint

Check the 'Health Status' column in row 2 of the execution_table.

At which check number does the container first become unhealthy?

A 1

B 3

C 2

D 4

💡 Hint

Look for the first 'Unhealthy' status in the execution_table.

If the health check command always returns exit code 0, what will happen to the container status?

A It will alternate between healthy and unhealthy

B It will become unhealthy eventually

C It will remain healthy

D It will stop running health checks

💡 Hint

Refer to the variable_tracker showing health status changes based on exit codes.

Concept Snapshot

Docker container health checks run a command periodically.
If the command succeeds (exit code 0), container is healthy.
If it fails (non-zero exit), container is unhealthy.
Use HEALTHCHECK in Dockerfile to define the command and timing.
Docker updates container status based on these results.

Full Transcript

Container health checks in Docker work by running a command inside the container repeatedly. Each time the command runs, Docker checks its exit code. If the exit code is zero, Docker marks the container as healthy. If the exit code is not zero, Docker marks it as unhealthy. This status updates every time the health check runs. For example, a health check command might be 'curl -f http://localhost/'. If curl succeeds, the container is healthy; if curl fails, the container is unhealthy. The health check runs every few seconds as configured. The container status can change back and forth depending on the command results. This helps Docker and users know if the container is working properly.

Practice

1. What is the main purpose of a HEALTHCHECK in a Docker container?

easy

A. To restart the Docker daemon automatically

B. To update the container's image

C. To check if the container's application is running correctly

D. To increase the container's CPU usage

Solution

1. Step 1: Understand the role of HEALTHCHECK

   The HEALTHCHECK instruction runs a command inside the container to verify if the app is working properly.

2. Step 2: Identify what HEALTHCHECK does not do

   It does not restart Docker daemon, update images, or increase CPU usage.

3. Final Answer:

   To check if the container's application is running correctly -> Option C

4. Quick Check:

   HEALTHCHECK verifies app status = B [OK]

Hint: HEALTHCHECK tests app inside container, not Docker itself [OK]

Common Mistakes:

• Confusing HEALTHCHECK with Docker daemon restart
• Thinking HEALTHCHECK updates images
• Assuming HEALTHCHECK changes resource usage

2. Which of the following is the correct syntax to add a health check in a Dockerfile?

easy

A. HEALTHCHECK CMD curl -f http://localhost/ || exit 1

B. HEALTHCHECK RUN curl -f http://localhost/ || exit 1

C. HEALTHCHECK EXEC curl -f http://localhost/ || exit 1

D. HEALTHCHECK CHECK curl -f http://localhost/ || exit 1

Solution

1. Step 1: Recall Dockerfile HEALTHCHECK syntax

   The correct syntax uses HEALTHCHECK CMD followed by the command to run.

2. Step 2: Identify incorrect keywords

   RUN, EXEC, CHECK are not valid keywords for HEALTHCHECK instruction.

3. Final Answer:

   HEALTHCHECK CMD curl -f http://localhost/ || exit 1 -> Option A

4. Quick Check:

   HEALTHCHECK uses CMD keyword = C [OK]

Hint: HEALTHCHECK always uses CMD keyword in Dockerfile [OK]

Common Mistakes:

• Using RUN instead of CMD in HEALTHCHECK
• Using EXEC or CHECK which are invalid
• Omitting CMD keyword entirely

3. Given this Dockerfile snippet:

HEALTHCHECK CMD curl -f http://localhost/health || exit 1
CMD ["./start-server.sh"]

What will be the health status if curl fails?

medium

A. unhealthy

B. unknown

C. starting

D. healthy

Solution

1. Step 1: Understand HEALTHCHECK command behavior

   If the command returns a non-zero exit code (like exit 1), Docker marks the container as unhealthy.

2. Step 2: Analyze the curl failure effect

   Since curl -f fails, it triggers exit 1, so health status becomes unhealthy.

3. Final Answer:

   unhealthy -> Option A

4. Quick Check:

   Failed HEALTHCHECK command = unhealthy [OK]

Hint: Failed health check command sets status to unhealthy [OK]

Common Mistakes:

• Assuming failure means healthy
• Confusing 'starting' with unhealthy
• Thinking status stays unknown on failure

4. You wrote this in your Dockerfile:

HEALTHCHECK CMD curl http://localhost/health || exit 1

But your container health status is always starting. What is the likely problem?

medium

A. The container has no network access

B. The HEALTHCHECK syntax is invalid

C. Docker daemon is not running

D. The health check command never succeeds within the start period

Solution

1. Step 1: Understand 'starting' health status meaning

   'starting' means the container is still within the initial grace period before health checks are considered final.

2. Step 2: Analyze why health check stays 'starting'

   If the command never succeeds during this period, Docker keeps status as 'starting'. Syntax is correct, Docker daemon running, and network likely accessible.

3. Final Answer:

   The health check command never succeeds within the start period -> Option D

4. Quick Check:

   Failing health check in start period = starting [OK]

Hint: Starting means health check not yet passed in grace period [OK]

Common Mistakes:

• Assuming syntax error causes 'starting' status
• Blaming Docker daemon when it runs fine
• Ignoring network issues but they are less likely here

5. You want to create a health check that retries 3 times before marking unhealthy and waits 10 seconds between checks. Which Dockerfile snippet correctly sets this up?

hard

A. HEALTHCHECK --timeout=10s --retries=3 CMD curl -f http://localhost/health || exit 1

B. HEALTHCHECK --interval=10s --retries=3 CMD curl -f http://localhost/health || exit 1

C. HEALTHCHECK --interval=3s --retries=10 CMD curl -f http://localhost/health || exit 1

D. HEALTHCHECK --start-period=10s --retries=3 CMD curl -f http://localhost/health || exit 1

Solution

1. Step 1: Identify correct flags for interval and retries

   --interval sets wait time between checks; --retries sets how many failures before unhealthy.

2. Step 2: Match values to requirements

   We want 10 seconds between checks and 3 retries, so --interval=10s --retries=3 is correct. Timeout and start-period are different settings.

3. Final Answer:

   HEALTHCHECK --interval=10s --retries=3 CMD curl -f http://localhost/health || exit 1 -> Option B

4. Quick Check:

   Interval=10s and retries=3 flags = A [OK]

Hint: Use --interval for wait, --retries for failure count [OK]

Common Mistakes:

• Confusing timeout with interval
• Swapping retries and interval values
• Using start-period instead of interval