nginx · JTorreG · May 1, 2025 · Apr 29, 2025 · Apr 29, 2025 · Apr 29, 2025
@@ -5,4 +5,5 @@ description: NGINX Agent is a companion daemon for your NGINX Open Source or NGI
 url: /nginx-agent/
 cascade:
   logo: NGINX-product-icon.png
+  type: agent-v2-migration
 ---
@@ -1,57 +1,67 @@
 ---
-title: "About"
+title: About
+draft: false
 weight: 100
 toc: true
-docs: DOCS-000
+nd-docs: DOCS-1091
+nd-content-type: how-to
 ---
-{{<call-out "note" "F5 NGINX Agent v3.0 is available now">}}
-NGINX Agent v3.0 is a major release that introduces new features and enhancements.
-
-Visit our [Update]({{< ref "/agent/install-upgrade/update.md" >}}) guide to install the latest version in your environment.
-{{</call-out>}}
-
-{{< include "agent/about.md" >}}
-
-## Architecture
-
-```mermaid
-graph BT
-
-    %% Define colors for the subgraphs
-    style ManagementPlane fill:#d0eac4,stroke:#228B22,stroke-width:2px,color:#000000
-    style CommandControl fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000
-    style OTelManagementPlane fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000
-    style Compute fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000
-    style NGINX fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000
-    style NGINXConfig fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000
-    style ErrorLogs fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000
-    style Agent fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000
-
-    subgraph ManagementPlane["NGINX One"]
-        CommandControl["Command Server"]
-        OTelManagementPlane["OTel Receiver"]
-    end
-
-    subgraph Compute["NGINX Instance"]
-        subgraph Agent["Agent Process"]
-            OTelDataPlane["OTel Collector"]
-        end
-
-        subgraph NGINX["NGINX Process"]
-            NGINXMetrics["Metrics"]
-        end
-        NGINXConfig["NGINX Configuration Files"]
-        ErrorLogs["NGINX Error Logs"]
-
-        Metrics["Host Metrics"] --> |Collects| OTelDataPlane
-        NGINXMetrics --> |Reads| OTelDataPlane["OTel Collector"]
-        Agent --> |Watch/Reload| NGINX
-        Agent --> |Reads| ErrorLogs
-        OTelDataPlane --> |Reads| AccessLogs["NGINX Access Logs"]
-        Agent <--> |Reads/Writes| NGINXConfig
-    end
-
-    Compute <--> |gRPC| ManagementPlane
-```
-
-{{< include "agent/architecture.md" >}}
+
+## Overview
+
+NGINX Agent v2 is a companion daemon for your NGINX Open Source or NGINX Plus instance. It enables:
+
+- Remote management of NGINX configurations
+- Collection and reporting of real-time NGINX performance and operating system metrics
+- Notifications of NGINX events
+
+
+{{< 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%">}}
+
+## 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/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.
+
+## 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/).
+
+### NGINX Open Source
+
+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.
+
+### 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. 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.
+
+## 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:
+
+
+{{<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>}}
+
+
+
@@ -6,10 +6,7 @@ toc: true
 
 {{< note >}}You can find the full changelog, contributor list and assets for NGINX Agent in the [GitHub repository](https://github.com/nginx/agent/releases).{{< /note >}}
 
-See the list of supported Operating Systems and architectures in the [Technical Specifications]({{< ref "./tech-specs.md" >}}).
-
----
-## Release [v3.0.0](https//github.com/nginx/agent/releases/tag/v3.0.0)
+See the list of supported Operating Systems and architectures in the [Technical Specifications]({{< ref "/agent/technical-specifications.md" >}}).
 
 ---
 ## Release [v2.40.0](https://github.com/nginx/agent/releases/tag/v2.40.0)

@@ -0,0 +1,20 @@
+---
+title: "Community and contribution"
+toc: true
+weight: 600
+nd-docs: DOCS-000
+---
+
+Discover the various ways you can participate in the F5 NGINX Agent project:
+
+## Community
+
+- Have questions or ideas to discuss? Join the conversation about NGINX Agent in the [NGINX Community Forum](https://community.nginx.org/).
+
+## Contribute
+
+Get involved with the project by contributing! Please see our [contributing guide](https://github.com/nginx/agent/blob/main/CONTRIBUTING.md) for details.
+
+## License
+
+[Apache License, Version 2.0](https://github.com/nginx/agent/blob/main/LICENSE)
@@ -0,0 +1,10 @@
+---
+title: "Configuration"
+weight: "400"
+url: /nginx-agent/configuration/
+cascade:
+  logo: NGINX-product-icon.png
+  layout: agent-v2-migration
+---
+
+Learn how to configure NGINX Agent.
@@ -3,9 +3,10 @@ title: Basic configuration
 draft: false
 weight: 100
 toc: true
-docs: DOCS-1229
-type:
-- how-to
+nd-docs: DOCS-1229
+nd-content-type: how-to
+
+
 ---
 
 The following sections explain how to configure NGINX Agent using configuration files, CLI flags, and environment variables.

@@ -3,9 +3,8 @@ title: "Add NGINX users to nginx-agent group"
 draft: false
 weight: 300
 toc: true
-docs: DOCS-933
-type:
-- how-to
+nd-docs: DOCS-933
+nd-content-type: how-to
 ---
 
 ## Overview

@@ -2,7 +2,7 @@
 title: Encrypt communication
 toc: true
 weight: 200
-docs: DOCS-802
+nd-docs: DOCS-802
 ---
 
 ## Overview

@@ -3,8 +3,7 @@ title: Health checks
 draft: false
 weight: 400
 toc: true
-type:
-- how-to
+nd-content-type: how-to
 ---
 
 ## Overview

@@ -2,7 +2,8 @@
 title: "Development environment setup"
 toc: true
 weight: 200
-docs: DOCS-000
+nd-docs: DOCS-000
+draft: true
 ---
 
 ## Overview
@@ -17,7 +18,7 @@ Ubuntu is the recommended operating system for development, as it comes with mos
 
 To begin this task, you will require the following:
 
-- A [working NGINX Agent instance]({{< ref "/agent/install-upgrade/" >}}).
+- A [working NGINX Agent instance]({{< ref "/nginx-one/agent/install-upgrade/" >}}).
 - A [Go installation](https://go.dev/dl/) of version 1.22.2 or newer.
 - A [Protocol Buffer Compiler](https://grpc.io/docs/protoc-installation/) installation.
 
@@ -29,7 +30,7 @@ git clone [email protected]:nginx/agent.git
 
 Read [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for more information
 
-Follow the steps in the [Installation]({{< ref "/agent/install-upgrade/" >}}) topic to install NGINX Agent.
+Follow the steps in the [Installation]({{< ref "/nginx-one/agent/install-upgrade/" >}}) topic to install NGINX Agent.
 
 ## Install prerequisite packages
 Depending on the operating system distribution, it may be necessary to install the following packages in order to build NGINX Agent.

@@ -2,7 +2,8 @@
 title: Start mock control plane interface
 toc: true
 weight: 300
-docs: DOCS-000
+nd-docs: DOCS-000
+draft: true
 ---
 
 This document describes how to configure and run F5 NGINX Agent using a mock interface ("control plane") for NGINX Agent to report to.
@@ -13,7 +14,7 @@ The mock interface is useful when developing NGINX Agent, as it allows you to vi
 
 To begin this task, you will require the following:
 
-- A [working NGINX Agent instance]({{< ref "/agent/install-upgrade/" >}}).
+- A [working NGINX Agent instance]({{< ref "/nginx-one/agent/install-upgrade/" >}}).
 - A [Go installation](https://go.dev/dl/) of version 1.22.2 or newer.
 - A [go-swagger](https://goswagger.io/go-swagger/install/) installation.
 

@@ -3,4 +3,7 @@ title: Installation and upgrade
 description: Learn how to install, upgrade, and uninstall NGINX Agent.
 weight: 300
 url: /nginx-agent/v2/installation-upgrade/
+cascade:
+  logo: NGINX-product-icon.png
+  type: agent-v2-migration
 ---
@@ -3,4 +3,7 @@ title: Container environments
 description: Learn how to build and run NGINX Agent docker images.
 weight: 800
 url: /nginx-agent/v2/installation-upgrade/container-environments/
+cascade:
+  logo: NGINX-product-icon.png
+  type: agent-v2-migration
 ---
@@ -3,9 +3,8 @@ title: Build container images
 draft: false
 weight: 100
 toc: true
-docs: DOCS-1410
-type:
-- how-to
+nd-docs: DOCS-1410
+nd-content-type: how-to
 ---
 
 ## Overview
@@ -14,7 +13,7 @@ NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instances
 
 If you want to use NGINX Agent with NGINX Plus, you need to purchase an NGINX Plus license. Contact your F5 Sales representative for assistance.
 
-See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< ref "/agent/tech-specs.md" >}}) topic.
+See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< ref "/agent/technical-specifications.md" >}}) topic.
 
 ## Deploy Offical NGINX and NGINX Plus Containers
 
@@ -113,7 +112,7 @@ docker tag docker-registry.nginx.com/nginx/agent:mainline nginx-agent
 docker run --name nginx-agent -d nginx-agent
 ```
 
-{{<note>}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< ref "/agent/v2/configuration/configuration-overview" >}}).{{</note>}}
+{{<note>}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< ref "/agent/configuration/configuration-overview" >}}).{{</note>}}
 
 ### Enable the gRPC interface
 

@@ -3,16 +3,16 @@ title: Container support and troubleshooting
 draft: false
 toc: true
 weight: 200
-docs: DOCS-909
-type:
+nd-docs: DOCS-909
+nd-content-type:
 - task
 ---
 
 ## Overview
 
-The NGINX Agent repository includes [Dockerfiles](https://github.com/nginx/agent/tree/main/scripts/docker) that can be used to [build custom container images]({{< ref "/agent/v2/installation-upgrade/container-environments/docker-images.md" >}}). Images are created with an NGINX Open Source or NGINX Plus instance and are available for various operating systems.
+The NGINX Agent repository includes [Dockerfiles](https://github.com/nginx/agent/tree/main/scripts/docker) that can be used to [build custom container images]({{< ref "/agent/installation-upgrade/container-environments/docker-images.md" >}}). Images are created with an NGINX Open Source or NGINX Plus instance and are available for various operating systems.
 
-See the [Technical Specifications]({{< ref "/agent/tech-specs.md#container-support" >}}) for a list of supported operationg systems.
+See the [Technical Specifications]({{< ref "/agent/technical-specifications.md" >}}) for a list of supported operationg systems.
 
 NGINX Agent running in a container has some limitations that need to be considered, and are listed below.
 

@@ -3,9 +3,8 @@ title: Getting started
 draft: false
 weight: 100
 toc: true
-docs: DOCS-1089
-type:
-- how-to
+nd-docs: DOCS-1089
+nd-content-type: how-to
 ---
 
 ## Overview
@@ -176,5 +175,5 @@ NGINX Agent uses formatted log files to collect metrics. Expanding log formats a
 {{< important >}}
 Without log rotation or storage on a separate partition, log files could use up all the free drive space and cause your system to become unresponsive to certain services.
 
-For more information, see [NGINX Agent Log Rotation]({{< ref "/agent/v2/configuration/configuration-overview.md#nginx-agent-log-rotation" >}}).
+For more information, see [NGINX Agent Log Rotation]({{< ref "/agent/configuration/configuration-overview.md#nginx-agent-log-rotation" >}}).
 {{< /important >}}
@@ -3,9 +3,8 @@ title: Installation from GitHub release
 draft: false
 weight: 200
 toc: true
-docs: DOCS-1090
-type:
-- how-to
+nd-docs: DOCS-1090
+nd-content-type: how-to
 ---
 
 ## Overview