Add health checks documentation (#673)

* Add health checks documentation * Clean up * Apply suggestions from code review Co-authored-by: Jon Torre <[email protected]> * Add env vars * Apply suggestions from code review Co-authored-by: Jon Torre <[email protected]> * 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 <[email protected]> Co-authored-by: Alan Dooley <[email protected]>
nginx · May 28, 2024 · 10193ba · 10193ba
1 parent ab64080
commit 10193ba
Show file tree

Hide file tree

Showing 2 changed files with 66 additions and 0 deletions.
diff --git 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*                             |
 
 {{</bootstrap-table>}}
 

diff --git a/site/content/configuration/health-checks.md 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.
+