Health checks in Nginx - Commands & Configuration

Introduction

Health checks help you know if your web server is working well. They automatically test if your server can respond to requests. This helps keep your website reliable and available.

When you want to make sure your nginx server is running and ready to serve web pages.

When you have multiple servers and want to send traffic only to the healthy ones.

When you want to monitor your server status automatically without manual checks.

When you want to restart or fix your server quickly if it stops responding.

When you want to improve user experience by avoiding broken or slow servers.

Config File - nginx.conf

nginx.conf

worker_processes 1;
events {
    worker_connections 1024;
}
http {
    server {
        listen 8080;

        location / {
            add_header Content-Type text/plain;
            return 200 'Server is healthy';
        }

        location /health {
            access_log off;
            add_header Content-Type text/plain;
            return 200 'OK';
        }
    }
}

This nginx configuration sets up a simple web server listening on port 8080.

The /health location is the health check endpoint. It returns a plain text 'OK' with HTTP status 200 to indicate the server is healthy.

The main / location returns a simple message to show the server is running.

Commands

Start nginx using the custom configuration file to enable the health check endpoint.

Terminal

nginx -c $(pwd)/nginx.conf

Expected Output

No output (command runs silently)

→

-c - Specify the path to the nginx configuration file.

Send a request to the health check endpoint to verify the server is healthy and responding.

Terminal

curl -i http://localhost:8080/health

Expected Output

HTTP/1.1 200 OK

Server: nginx/1.24.0

Date: Thu, 01 Jun 2024 12:00:00 GMT

Content-Type: text/plain

Content-Length: 2

Connection: keep-alive



OK

Send a request to the main server endpoint to confirm the server is running and serving content.

Terminal

curl -i http://localhost:8080/

Expected Output

HTTP/1.1 200 OK

Server: nginx/1.24.0

Date: Thu, 01 Jun 2024 12:00:00 GMT

Content-Type: text/plain

Content-Length: 16

Connection: keep-alive



Server is healthy

Stop the nginx server after testing to free system resources.

Terminal

nginx -s stop

Expected Output

No output (command runs silently)

→

-s - Send a signal to the nginx process (stop in this case).

Key Concept

If you remember nothing else from this pattern, remember: a simple HTTP endpoint returning 200 OK is the easiest way to check if your nginx server is healthy.

Common Mistakes

Not creating a dedicated /health endpoint and checking the main page instead.

The main page might be complex or slow, causing false negatives in health checks.

Create a lightweight /health endpoint that returns a simple 200 OK response quickly.

Forgetting to reload or restart nginx after changing the configuration.

Changes won't take effect until nginx reloads the config, so health checks may fail or be outdated.

Always reload nginx with 'nginx -s reload' or restart it after config changes.

Using a health check that returns non-200 status codes or large content.

Health check systems expect a quick 200 OK response; other codes or big responses may cause false alarms.

Ensure the health check endpoint returns HTTP 200 with minimal content.

Summary

Configure nginx with a simple /health endpoint that returns HTTP 200 OK.

Start nginx with the custom configuration to enable health checks.

Use curl to verify the /health endpoint responds correctly.

Stop nginx after testing to clean up.

Practice

1. What is the main purpose of a health check in an nginx setup?

easy

A. To increase the server's CPU speed

B. To verify if a server is ready to handle requests

C. To change the server's IP address automatically

D. To backup server files regularly

Solution

1. Step 1: Understand health check concept

   Health checks are used to confirm if a server is ready and able to serve requests.

2. Step 2: Identify the purpose in nginx context

   In nginx, health checks help route traffic only to servers that respond correctly, ensuring reliability.

3. Final Answer:

   To verify if a server is ready to handle requests -> Option B

4. Quick Check:

   Health check purpose = Verify readiness [OK]

Hint: Health checks confirm server readiness to serve requests [OK]

Common Mistakes:

• Thinking health checks speed up the server
• Confusing health checks with backups
• Assuming health checks change server IP

2. Which of the following is the correct way to define a simple health check endpoint in nginx configuration?

easy

A. location /healthcheck { return 200 "OK"; }

B. location /healthcheck { proxy_pass http://backend; }

C. location /healthcheck { error_page 404 /404.html; }

D. location /healthcheck { deny all; }

Solution

1. Step 1: Review nginx location syntax for health check

   A simple health check returns a 200 status with a message like 'OK'.

2. Step 2: Identify correct return directive

   location /healthcheck { return 200 "OK"; } uses return 200 "OK"; which correctly sends a success response for health checks.

3. Final Answer:

   location /healthcheck { return 200 "OK"; } -> Option A

4. Quick Check:

   Simple health check = return 200 [OK]

Hint: Health check returns 200 with OK message [OK]

Common Mistakes:

• Using proxy_pass instead of return for simple checks
• Setting error_page instead of success response
• Denying access blocks health check

3. Given this nginx config snippet, what will be the HTTP status code when accessing /health?

location /health {
  return 204;
}

medium

A. 204

B. 404

C. 500

D. 200

Solution

1. Step 1: Understand the return directive in nginx

   The return 204; sends an HTTP status code 204 (No Content) response.

2. Step 2: Match the status code with the request

   Accessing /health triggers this location and returns 204 as configured.

3. Final Answer:

   204 -> Option A

4. Quick Check:

   return 204 sends status 204 [OK]

Hint: return 204 sends HTTP 204 No Content status [OK]

Common Mistakes:

• Assuming default 200 status without checking return
• Confusing 204 with 404 or 500 errors
• Ignoring the explicit return directive

4. You configured this health check in nginx:

location /healthcheck {
  return 200 "OK"
}

But the health check fails with a syntax error. What is the problem?

medium

A. The return directive cannot include a message string

B. The return code 200 is invalid

C. The location block is missing a semicolon after return

D. The location path must be /health, not /healthcheck

Solution

1. Step 1: Check nginx configuration syntax

   All nginx directives must end with a semicolon (;).

2. Step 2: Locate the error in the snippet

   The return 200 "OK" line is missing the trailing semicolon, causing a syntax error.

3. Final Answer:

   The location block is missing a semicolon after return -> Option C

4. Quick Check:

   nginx directives require semicolon [OK]

Hint: Every nginx directive must end with a semicolon [OK]

Common Mistakes:

• Adding message string directly after return
• Missing semicolon causing syntax error
• Using wrong location path for health check

5. You want to configure nginx to perform active health checks on backend servers and mark them unhealthy if they fail. Which directive and module combination should you use?

hard

A. Use proxy_pass with proxy_next_upstream and enable ngx_http_healthcheck_module

B. Use deny all in location to block unhealthy servers

C. Use return 200 in location block for backend health

D. Use check directive inside upstream block with ngx_http_upstream_check_module

Solution

1. Step 1: Identify active health check method in nginx

   Active health checks require special modules like ngx_http_upstream_check_module and directives like check inside upstream blocks.

2. Step 2: Match correct directive and module

   Use check directive inside upstream block with ngx_http_upstream_check_module correctly pairs check directive with ngx_http_upstream_check_module for active health checks.

3. Final Answer:

   Use check directive inside upstream block with ngx_http_upstream_check_module -> Option D

4. Quick Check:

   Active health checks = check + upstream_check_module [OK]

Hint: Active health checks need check directive and module [OK]

Common Mistakes:

• Confusing passive proxy_next_upstream with active health checks
• Using return 200 for backend health checks
• Blocking servers instead of checking health