NGINX Advanced Healthcheck

Description

This repository provides a sample NGINX Plus configuration to support advanced active healthchecks.

Upstream servers availability status is dynamically set based on evaluation of external REST API that can provide any type of JSON reply. JSON responses can be evaluated by custom logic by adapting the sample healthcheck.js configuration provided.

Prerequisites

To use this NGINX Plus configuration:

• NGINX Plus R27 or later with njs support

To set up the sample lab:

• One "Load balancer" Linux host to run NGINX Plus and the configuration from this repo. See here for NGINX Plus supported distributions
• Two "Webserver" Linux hosts to run the sample webservers (upstream servers)
• One client host to access NGINX Plus dashboard and test load balancing using curl / a web browser
• Python 3.10+ on all Linux hosts

Setup description

NGINX Plus:

• Runs healthcheck evaluation by querying the external REST API service and applying the custom healthcheck logic
• Sets upstream servers up/down state through its REST API
• Load balances client requests
  • For HTTP(S) services
  • For TCP/UDP services

Deploying this repository

1. Setup Linux hosts (IP addresses reference the sample NGINX configuration) and install required packages

Hostname	IP Address	Distribution	Packages to be installed	Description
client	192.168.1.20	Your favorite client OS	Your favorite web browser, curl	This is used to access NGINX Plus dashboard and to test using curl
nginx	192.168.1.21	Any NGINX Plus supported distribution	NGINX Plus to be installed here	NGINX Plus load balancer with advanced healthchecks
webserver1	192.168.1.30	Your favorite Linux distro	Python 3.10+, webserver, health API	This is an upstream server NGINX will load balance requests to
webserver2	192.168.1.31	Your favorite Linux distro	Python 3.10+, webserver, health API	This is an upstream server NGINX will load balance requests to

2. Configure and start services

Hostname	Description
nginx	Copy all files in nginx/conf.d to /etc/nginx/conf.d/ and all files in nginx/stream-conf.d to /etc/nginx/stream-conf.d/. Start NGINX Plus
webserver1	Run the sample webserver (listening on 8080/TCP) and the health API (listening on 5000/TCP)
webserver2	Run the sample webserver (listening on 8080/TCP) and the health API (listening on 5000/TCP)

Testing

1. NGINX Plus dashboard can be accessed from client browsing to http://192.168.1.20:8080/dashboard.html

2. Running curl from the client host check where requests are balanced:

$ curl -H "Host: app.test.lab" http://192.168.1.21
This is the webserver running on webserver1

3. The default configuration sets upstream servers as available when 1 minute CPU load is lower than 5, see healthcheck.js. The actual logic is fully customizable.

     // Evaluation logic goes here, this example checks the 1 minute CPU load
      if(jsonReply.cpu.load.1minute < 5) {
        // Set the upstream server up
        r.warn('Healthcheck: server #[' + backend_server_entry + '] is up');
        r.subrequest("/upstream/up/" + backend_server_entry,postUpstreamUpdate);
      } else {
        // Set the upstream server down
        r.warn('Healthcheck: server #[' + backend_server_entry + '] is down');
        r.subrequest("/upstream/down/" + backend_server_entry,postUpstreamUpdate);
      }

Customizing

To customize the NGINX Plus configuration refer to:

• nginx/conf.d/healthcheck.conf - Fully commented NGINX Plus configuration to define healtcheck REST API endpoints
• nginx/conf.d/healthcheck.js - To customize the healthcheck evaluation logic
• nginx/conf.d/loadbalancer.conf - HTTP(S) upstream and server {} configuration
• nginx/stream-conf.d/stream-loadbalancer.conf - TCP/UDP upstream and server {} configuration