Health checks in Docker in Spring Boot - Step-by-Step Execution

Concept Flow - Health checks in Docker

Start Docker Container

↓

Docker runs Health Check Command

↓

Health Check Command executes Spring Boot Actuator Endpoint

↓

Spring Boot returns status (UP/DOWN)

↓

Docker receives status

↓

Docker marks container as healthy or unhealthy

↓

Docker takes action based on health (restart, alert, etc.)

Docker runs a health check command that calls Spring Boot's actuator endpoint to get app status, then marks container health accordingly.

Execution Sample

Spring Boot

HEALTHCHECK --interval=10s --timeout=5s \
  CMD curl -f http://localhost:8080/actuator/health || exit 1

Docker runs this command every 10 seconds to check if the Spring Boot app is healthy.

Execution Table

Step	Action	Command Output	Docker Health Status	Container State
1	Docker starts container	N/A	starting	container running
2	Docker runs health check command	HTTP 200 {"status":"UP"}	healthy	container running
3	Wait 10 seconds	N/A	healthy	container running
4	Docker runs health check command	HTTP 200 {"status":"UP"}	healthy	container running
5	Wait 10 seconds	N/A	healthy	container running
6	Docker runs health check command	curl: (7) Failed to connect	unhealthy	container running
7	Docker marks container unhealthy	N/A	unhealthy	container running
8	Docker restarts container	N/A	starting	container restarting
9	Docker runs health check command	HTTP 200 {"status":"UP"}	healthy	container running

💡 Docker stops unhealthy state by restarting container after failed health check

Variable Tracker

Variable	Start	After 2	After 4	After 6	After 8	After 9
Docker Health Status	starting	healthy	healthy	unhealthy	starting	healthy
Container State	container running	container running	container running	container running	container restarting	container running

Key Moments - 3 Insights

Why does Docker mark the container unhealthy even though it is still running?

Docker bases health on the health check command result, not container running state. See step 6 in execution_table where command fails but container is still running.

What happens after Docker marks the container unhealthy?

Docker restarts the container to try to fix the problem, as shown in step 8 and 9 in execution_table.

Why use Spring Boot actuator endpoint for health check?

Because it returns a simple UP/DOWN status that Docker can easily interpret, shown in steps 2 and 4 where HTTP 200 with status UP means healthy.

Visual Quiz - 3 Questions

Look at the execution_table, what is the Docker Health Status at step 4?

A starting

B unhealthy

C healthy

D restarting

💡 Hint

Check the 'Docker Health Status' column at step 4 in execution_table

At which step does the health check command fail causing Docker to mark the container unhealthy?

A Step 2

B Step 6

C Step 4

D Step 8

💡 Hint

Look for 'curl: (7) Failed to connect' in 'Command Output' column in execution_table

If the health check command always returns HTTP 200 with status UP, what will Docker do?

A Keep container healthy and running

B Restart container repeatedly

C Mark container unhealthy

D Stop the container

💡 Hint

Refer to steps 2 and 4 in execution_table where HTTP 200 means healthy

Concept Snapshot

Docker health checks run a command periodically.
Spring Boot actuator /health endpoint returns app status.
Docker marks container healthy if command succeeds.
If command fails, Docker marks unhealthy and can restart.
Use HEALTHCHECK in Dockerfile with curl to actuator.
This helps keep apps running smoothly.

Full Transcript

This visual execution shows how Docker performs health checks on a Spring Boot application. Docker starts the container and runs a health check command every 10 seconds. The command calls the Spring Boot actuator health endpoint. If the endpoint returns HTTP 200 with status UP, Docker marks the container healthy. If the command fails, Docker marks the container unhealthy but the container keeps running. After marking unhealthy, Docker restarts the container to recover. Variables like Docker Health Status and Container State change step by step. Key moments include understanding that health is based on the command result, not container running state, and that Docker restarts unhealthy containers. The visual quiz tests understanding of health status at different steps and Docker's reaction to health check results.

Practice

1.

What is the main purpose of adding a HEALTHCHECK instruction in a Dockerfile for a Spring Boot application?

easy

A. To let Docker monitor if the app is running correctly and restart if needed

B. To speed up the app startup time inside the container

C. To reduce the container size by removing unused files

D. To automatically update the Spring Boot version inside the container

Solution

1. Step 1: Understand the role of HEALTHCHECK in Docker

   The HEALTHCHECK instruction tells Docker how to test if the container's app is healthy.

2. Step 2: Connect HEALTHCHECK to app monitoring

   It helps Docker detect problems and restart the app if it stops working properly.

3. Final Answer:

   To let Docker monitor if the app is running correctly and restart if needed -> Option A

4. Quick Check:

   HEALTHCHECK monitors app health [OK]

Hint: HEALTHCHECK = Docker watches app health and restarts if unhealthy [OK]

Common Mistakes:

• Thinking HEALTHCHECK speeds up app startup
• Confusing HEALTHCHECK with image size optimization
• Assuming HEALTHCHECK updates app versions automatically

2.

Which of the following is the correct syntax to add a health check in a Dockerfile for a Spring Boot app that exposes /actuator/health on port 8080?

?

easy

A. HEALTHCHECK RUN curl http://localhost:8080/actuator/health

B. HEALTHCHECK CMD curl --fail http://localhost:8080/actuator/health || exit 1

C. HEALTHCHECK CMD ping localhost:8080/actuator/health

D. HEALTHCHECK EXEC curl http://localhost:8080/actuator/health

Solution

1. Step 1: Identify correct HEALTHCHECK syntax

   The HEALTHCHECK instruction uses CMD followed by a command that returns 0 on success or non-zero on failure.

2. Step 2: Verify the command tests the health endpoint properly

   Using curl with --fail returns error if the endpoint is unhealthy, triggering Docker restart.

3. Final Answer:

   HEALTHCHECK CMD curl --fail http://localhost:8080/actuator/health || exit 1 -> Option B

4. Quick Check:

   HEALTHCHECK CMD + curl --fail = correct syntax [OK]

Hint: Use HEALTHCHECK CMD with curl --fail for health endpoint [OK]

Common Mistakes:

• Using RUN instead of CMD in HEALTHCHECK
• Using ping instead of curl for HTTP check
• Using EXEC keyword which is invalid

3.

Given this Dockerfile snippet, what will Docker report as the container health status if the Spring Boot app's /actuator/health endpoint returns HTTP 500?

HEALTHCHECK CMD curl --fail http://localhost:8080/actuator/health || exit 1

medium

A. healthy

B. unknown

C. starting

D. unhealthy

Solution

1. Step 1: Understand curl --fail behavior on HTTP 500

   The curl --fail option causes curl to exit with error on HTTP status codes 400 or above.

2. Step 2: Connect curl failure to Docker health status

   Since curl fails, the HEALTHCHECK command exits with 1, marking container as unhealthy.

3. Final Answer:

   unhealthy -> Option D

4. Quick Check:

   HTTP 500 triggers curl failure = unhealthy [OK]

Hint: curl --fail fails on HTTP 500, so container becomes unhealthy [OK]

Common Mistakes:

• Assuming HTTP 500 still means healthy
• Confusing 'starting' with unhealthy status
• Thinking Docker ignores health check failures

4.

Identify the error in this Dockerfile health check instruction for a Spring Boot app:

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

medium

A. Incorrect URL path for health endpoint

B. Using CMD instead of RUN for HEALTHCHECK

C. Missing --fail option in curl to detect HTTP errors

D. Missing port number in the URL

Solution

1. Step 1: Check curl command correctness for health check

   Without --fail, curl returns success even if HTTP status is error (like 500).

2. Step 2: Understand impact on Docker health status

   Docker will wrongly mark container healthy because curl does not fail on bad HTTP codes.

3. Final Answer:

   Missing --fail option in curl to detect HTTP errors -> Option C

4. Quick Check:

   curl needs --fail to detect HTTP errors [OK]

Hint: Always add --fail to curl in HEALTHCHECK to catch errors [OK]

Common Mistakes:

• Using RUN instead of CMD in HEALTHCHECK
• Wrong health endpoint URL
• Forgetting port number in URL

5.

You want Docker to check your Spring Boot app health every 30 seconds, retry 3 times before marking unhealthy, and start checking only after 10 seconds of container start. Which HEALTHCHECK instruction correctly implements this?

hard

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

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

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

D. HEALTHCHECK CMD curl --fail http://localhost:8080/actuator/health || exit 1

Solution

1. Step 1: Match timing parameters to requirements

   Interval 30s means check every 30 seconds, start-period 10s delays first check, retries 3 means try 3 times before unhealthy.

2. Step 2: Verify curl command correctness

   curl uses --fail to detect HTTP errors, with exit 1 to signal failure to Docker.

3. Final Answer:

   HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD curl --fail http://localhost:8080/actuator/health || exit 1 -> Option A

4. Quick Check:

   Correct timing + curl --fail = HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD curl --fail http://localhost:8080/actuator/health || exit 1 [OK]

Hint: Set interval, retries, start-period explicitly with curl --fail [OK]

Common Mistakes:

• Mixing up interval and timeout values
• Omitting --fail in curl command
• Not setting start-period to delay checks