Skip to content

NGINX Plus configuration to run REST API-based healthchecks for HTTP(S) and TCP/UDP upstreams

Notifications You must be signed in to change notification settings

fabriziofiorucci/NGINX-Advanced-Healthcheck

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

5 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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:

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
  1. 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

  1. 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
  1. 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:

About

NGINX Plus configuration to run REST API-based healthchecks for HTTP(S) and TCP/UDP upstreams

Resources

Stars

Watchers

Forks