|
1 | 1 | --- |
2 | | -title: "About" |
| 2 | +title: About |
| 3 | +draft: false |
3 | 4 | weight: 100 |
4 | 5 | toc: true |
5 | | -docs: DOCS-000 |
| 6 | +nd-docs: DOCS-1091 |
| 7 | +nd-content-type: how-to |
6 | 8 | --- |
7 | | -{{<call-out "note" "F5 NGINX Agent v3.0 is available now">}} |
8 | | -NGINX Agent v3.0 is a major release that introduces new features and enhancements. |
9 | | - |
10 | | -Visit our [Update]({{< ref "/agent/install-upgrade/update.md" >}}) guide to install the latest version in your environment. |
11 | | -{{</call-out>}} |
12 | | - |
13 | | -{{< include "agent/about.md" >}} |
14 | | - |
15 | | -## Architecture |
16 | | - |
17 | | -```mermaid |
18 | | -graph BT |
19 | | -
|
20 | | - %% Define colors for the subgraphs |
21 | | - style ManagementPlane fill:#d0eac4,stroke:#228B22,stroke-width:2px,color:#000000 |
22 | | - style CommandControl fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 |
23 | | - style OTelManagementPlane fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 |
24 | | - style Compute fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 |
25 | | - style NGINX fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 |
26 | | - style NGINXConfig fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 |
27 | | - style ErrorLogs fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 |
28 | | - style Agent fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 |
29 | | -
|
30 | | - subgraph ManagementPlane["NGINX One"] |
31 | | - CommandControl["Command Server"] |
32 | | - OTelManagementPlane["OTel Receiver"] |
33 | | - end |
34 | | -
|
35 | | - subgraph Compute["NGINX Instance"] |
36 | | - subgraph Agent["Agent Process"] |
37 | | - OTelDataPlane["OTel Collector"] |
38 | | - end |
39 | | -
|
40 | | - subgraph NGINX["NGINX Process"] |
41 | | - NGINXMetrics["Metrics"] |
42 | | - end |
43 | | - NGINXConfig["NGINX Configuration Files"] |
44 | | - ErrorLogs["NGINX Error Logs"] |
45 | | -
|
46 | | - Metrics["Host Metrics"] --> |Collects| OTelDataPlane |
47 | | - NGINXMetrics --> |Reads| OTelDataPlane["OTel Collector"] |
48 | | - Agent --> |Watch/Reload| NGINX |
49 | | - Agent --> |Reads| ErrorLogs |
50 | | - OTelDataPlane --> |Reads| AccessLogs["NGINX Access Logs"] |
51 | | - Agent <--> |Reads/Writes| NGINXConfig |
52 | | - end |
53 | | -
|
54 | | - Compute <--> |gRPC| ManagementPlane |
55 | | -``` |
56 | | - |
57 | | -{{< include "agent/architecture.md" >}} |
| 9 | + |
| 10 | +## Overview |
| 11 | + |
| 12 | +NGINX Agent v2 is a companion daemon for your NGINX Open Source or NGINX Plus instance. It enables: |
| 13 | + |
| 14 | +- Remote management of NGINX configurations |
| 15 | +- Collection and reporting of real-time NGINX performance and operating system metrics |
| 16 | +- Notifications of NGINX events |
| 17 | + |
| 18 | + |
| 19 | +{{< img src="agent/grafana-dashboard-example.png" caption="Grafana dashboard showing metrics reported by NGINX Agent" alt="Grafana dashboard showing metrics reported by NGINX Agent" width="99%">}} |
| 20 | + |
| 21 | +## How it Works |
| 22 | + |
| 23 | +NGINX Agent runs as a companion process on a system running NGINX. It provides gRPC and REST interfaces for configuration management and metrics collection from the NGINX process and operating system. NGINX Agent enables remote interaction with NGINX using common Linux tools and unlocks the ability to build sophisticated monitoring and control systems that can manage large collections of NGINX instances. |
| 24 | + |
| 25 | +{{< img src="agent/agent-flow.png" caption="How Agent works" alt="How NGINX Agent works" width="99%">}} |
| 26 | + |
| 27 | + |
| 28 | +## Configuration Management |
| 29 | + |
| 30 | +NGINX Agent provides an API interface for submission of updated configuration files. Upon receipt of a new file, it checks the output of `nginx -V` to determine the location of existing configurations. It then validates the new configuration with `nginx -t` before applying it via a signal HUP to the NGINX master process. |
| 31 | + |
| 32 | +## Collecting Metrics |
| 33 | + |
| 34 | +NGINX Agent interfaces with NGINX process information and parses NGINX logs to calculate and report metrics. When interfacing with NGINX Plus, NGINX Agent pulls relevant information from the NGINX Plus API. Reported metrics may be aggregated by [Prometheus](https://prometheus.io/) and visualized with tools like [Grafana](https://grafana.com/). |
| 35 | + |
| 36 | +### NGINX Open Source |
| 37 | + |
| 38 | +When running alongside an open source instance of NGINX, NGINX Agent requires that NGINX Access and Error logs are turned on and contain all default variables. |
| 39 | + |
| 40 | +### NGINX Plus |
| 41 | + |
| 42 | +For NGINX Agent to work properly with an NGINX Plus instance, the API needs to be configured in that instance's nginx.conf. See [Instance Metrics Overview](https://docs.nginx.com/nginx-instance-manager/monitoring/overview-metrics/) for more details. Once NGINX Plus is configured with the `/api/` endpoint, the Agent will automatically use it on startup. |
| 43 | + |
| 44 | +## Event Notifications |
| 45 | + |
| 46 | +NGINX Agent allows a gRPC connected control system to register a listener for a specific event. The control mechanism is then invoked when NGINX Agent sends an associated system signal. The source of a notification can be either the NGINX instance or NGINX Agent itself. Here's a list of currently supported events: |
| 47 | + |
| 48 | + |
| 49 | +{{<bootstrap-table "table table-striped table-bordered">}} |
| 50 | +| Event | Description | |
| 51 | +| -------------------------------- | -------------------------------------------- | |
| 52 | +| AGENT_START_MESSAGE | Agent process started | |
| 53 | +| AGENT_STOP_MESSAGE | Agent process stopped | |
| 54 | +| NGINX_FOUND_MESSAGE | NGINX master process detected on system | |
| 55 | +| NGINX_STOP_MESSAGE | NGINX master process stopped | |
| 56 | +| NGINX_RELOAD_SUCCESS_MESSAGE | NGINX master process reloaded successfully | |
| 57 | +| NGINX_RELOAD_FAILED_MESSAGE | NGINX master process failed to reload | |
| 58 | +| NGINX_WORKER_START_MESSAGE | New NGINX worker process started | |
| 59 | +| NGINX_WORKER_STOP_MESSAGE | NGINX worker process stopped | |
| 60 | +| CONFIG_APPLY_SUCCESS_MESSAGE | Successfully applied new NGINX configuration | |
| 61 | +| CONFIG_APPLY_FAILURE_MESSAGE | Failed to apply new NGINX configuration | |
| 62 | +| CONFIG_ROLLBACK_SUCCESS_MESSAGE | Successfully rolled back NGINX configuration | |
| 63 | +| CONFIG_ROLLBACK_FAILURE_MESSAGE | Failed to roll back NGINX configuration | |
| 64 | +{{</bootstrap-table>}} |
| 65 | + |
| 66 | + |
| 67 | + |
0 commit comments