From 10193ba64c7867254400e8cf779363174bb84aad Mon Sep 17 00:00:00 2001 From: Donal Hurley Date: Tue, 28 May 2024 11:26:53 +0100 Subject: [PATCH] Add health checks documentation (#673) * Add health checks documentation * Clean up * Apply suggestions from code review Co-authored-by: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> * Add env vars * Apply suggestions from code review Co-authored-by: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> * Update health-checks.md * Change environment variable list to table with CLI references This commit changes the list of NGINX Agent variables to a table showing how it maps to the CLI flags, with an exception for the variable that doesn't have a flag yet. It links to the CLI flag section so that the reader can view the descriptions for additional context. * Fix small typo in Docker documentation * Add pending health status (#672) * Add pending health status for Agent v2 --------- Co-authored-by: Jon Torre <78599298+Jcahilltorre@users.noreply.github.com> Co-authored-by: Alan Dooley --- .../configuration/configuration-overview.md | 4 ++ site/content/configuration/health-checks.md | 62 +++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 site/content/configuration/health-checks.md diff --git a/site/content/configuration/configuration-overview.md b/site/content/configuration/configuration-overview.md index 78e19f43e6..2a331b279d 100644 --- a/site/content/configuration/configuration-overview.md +++ b/site/content/configuration/configuration-overview.md @@ -249,6 +249,10 @@ This section displays the configurable options for NGINX Agent that can be set w | *NMS_TLS_ENABLE* | *--tls-enable* | | *NMS_TLS_KEY* | *--tls-key* | | *NMS_TLS_SKIP_VERIFY* | *--tls-skip-verify* | +| *NMS_API_HOST* | *--api-host* | +| *NMS_API_PORT* | *--api-port* | +| *NMS_API_KEY* | *--api-key* | +| *NMS_API_CERT* | *--api-cert* | {{}} diff --git a/site/content/configuration/health-checks.md b/site/content/configuration/health-checks.md new file mode 100644 index 0000000000..f045955fbd --- /dev/null +++ b/site/content/configuration/health-checks.md @@ -0,0 +1,62 @@ +--- +title: "Health checks" +draft: false +weight: 400 +toc: true +tags: [ "docs" ] +categories: ["configuration"] +doctypes: ["task"] +--- + +## Overview + +The REST API includes a health endpoint to verify the status of NGINX Agent. + +## Configure the REST API + +To enable the REST API, add the following configuration to the NGINX Agent configuration file, `/etc/nginx-agent/nginx-agent.conf`: + +```nginx +api: + host: 127.0.0.1 + port: 8038 +``` + +## Using health checks + +After you enable the REST API, calling the `/health` endpoint returns the following JSON response: + +```json +{ + "status": "OK", + "checks": [ + { + "name": "registration", + "status": "OK" + }, + { + "name": "commandConnection", + "status": "OK" + }, + { + "name": "metricsConnection", + "status": "OK" + } + ] +} +``` + +The top-level `status` field is the overall health status of NGINX Agent. The health status can return three different states: + +1. `PENDING`: NGINX Agent is still determining its health status. +2. `OK`: NGINX Agent is in a healthy state. +3. `ERROR`: NGINX Agent is in an unhealthy state. + +The health checkpoint performs three checks to determine the overall health of the NGINX Agent: + +1. `registration`: Checks if NGINX Agent has successfully registered with the management plane server. +2. `commandConnection`: Checks if NGINX Agent is still able to receive and send commands. +3. `metricsConnection`: Checks if NGINX Agent is still able to send metric reports. + +If any of the checks are in an `ERROR` status, then the overall status of NGINX Agent will change to `ERROR` as well. +