Skip to content

docs:Adding agent v3 docs #326

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 27, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 23 additions & 60 deletions content/agent/about.md
Original file line number Diff line number Diff line change
@@ -4,80 +4,43 @@ weight: 100
toc: true
docs: DOCS-000
---
{{<call-out "note" "F5 NGINX Agent v3.0 is available now">}}
<!-- (TODO: Link instructions ) -->
{{</call-out>}}

NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance. It enables:
### About F5 NGINX Agent
The F5 NGINX Agent is a lightweight companion daemon designed to work with NGINX One, enabling remote management of the NGINX Instance(s). It also gathers performance metrics from NGINX and transmits them to the NGINX One Console for enhanced monitoring and control.

- Remote management of NGINX configurations
- Collection and reporting of real-time NGINX performance and operating system metrics
- Notifications of NGINX events
### Key Features
- Enable Access to Key NGINX One Use Cases
- Seamlessly integrates with essential NGINX One functionality, simplifying access to its core use cases and enhancing operational workflows.
- [Connect to NGINX One Console]({{< relref "/agent/install-upgrade/install/#connect-an-instance-to-nginx-one-console" >}})

[OpenTelemetry](https://opentelemetry.io/) support comes with NGINX Agent v3, and the ability to [export the metrics data]({{< relref "/agent/how-to/export-metrics.md" >}}) for use in other applications.
- Real-Time Observability into NGINX One Data Plane Instances
- Provides live monitoring and actionable insights into the performance, status, and health of NGINX One Data Plane instances, improving decision-making and operational efficiency.

For an overview of the metrics available from NGINX Agent, read the following topics:

- [OpenTelemetry metrics]({{< relref "/agent/otel/metrics.md" >}}) (Agent v3)


{{< img src="grafana-dashboard-example.png" caption="A Grafana dashboard displaying metrics reported by NGINX Agent." alt="A Grafana dashboard displaying metrics reported by NGINX Agent.">}}
- [OpenTelemetry](https://opentelemetry.io/) support comes with F5 NGINX Agent, and the ability to [export the metrics data]({{< relref "/agent/otel/configure-otel-metrics.md" >}}) for use in other applications.

---

## How it works

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.

{{< img src="agent-flow.png" caption="How Agent works" alt="How NGINX Agent works" width="99%">}}


## Configuration management

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.

For additional information, view the [Configuration overview]({{< relref "/agent/how-to/configuration-overview.md" >}}) topic.

---

## Collecting metrics

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/).
### Configuration management

---

### NGINX Open Source
- The F5 NGINX Agent provides an interface that enables users to deploy configuration changes to NGINX from a centralized management plane.
- Additionally, the F5 NGINX Agent verifies that the configuration changes are successfully applied to NGINX.

### Metrics Collection

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.
- The F5 NGINX Agent comes pre-packaged with an embedded OpenTelemetry Collector .
- This embedded collector gathers vital performance and health metrics for both NGINX and the underlying instance it operates on.
- For example, it tracks key metrics such as active connections, requests per second, HTTP status codes, and response times. Additionally, it collects system-level data, including CPU usage, memory consumption, and disk I/O. These insights provide deep observability into NGINX's behavior, enabling teams to troubleshoot issues effectively, optimize performance, and maintain high availability.
- Collected metrics can be seamlessly exported to the NGINX One Console or integrated with third-party data aggregators.


---

### NGINX Plus

For NGINX Agent to work properly with an NGINX Plus instance, the API needs to be configured in that instance's nginx.conf. View the [Instance Metrics Overview](https://docs.nginx.com/nginx-management-suite/nim/about/overview-metrics/) topic for more details. Once NGINX Plus is configured with the `/api/` endpoint, the Agent will automatically use it on startup.
{{< img src="agent-flow.png" caption="How Agent works" alt="How NGINX Agent works" width="99%">}}

---

## Event notifications

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:

{{< raw-html>}}<div class="table-responsive">{{</raw-html>}}
{{<bootstrap-table "table table-striped table-bordered">}}
| Event | Description |
| -------------------------------- | -------------------------------------------- |
| AGENT_START_MESSAGE | Agent process started |
| AGENT_STOP_MESSAGE | Agent process stopped |
| NGINX_FOUND_MESSAGE | NGINX master process detected on system |
| NGINX_STOP_MESSAGE | NGINX master process stopped |
| NGINX_RELOAD_SUCCESS_MESSAGE | NGINX master process reloaded successfully |
| NGINX_RELOAD_FAILED_MESSAGE | NGINX master process failed to reload |
| NGINX_WORKER_START_MESSAGE | New NGINX worker process started |
| NGINX_WORKER_STOP_MESSAGE | NGINX worker process stopped |
| CONFIG_APPLY_SUCCESS_MESSAGE | Successfully applied new NGINX configuration |
| CONFIG_APPLY_FAILURE_MESSAGE | Failed to apply new NGINX configuration |
| CONFIG_ROLLBACK_SUCCESS_MESSAGE | Successfully rolled back NGINX configuration |
| CONFIG_ROLLBACK_FAILURE_MESSAGE | Failed to roll back NGINX configuration |
{{</bootstrap-table>}}
{{< raw-html>}}</div>{{</raw-html>}}


Loading
Oops, something went wrong.