Skip to content

Commit 85b6d64

Browse files
JTorreGJTorreG
authored
Move Agent v3 Docs under NGINX One Console (#468)
* move agent v3 docs to NGINX One * fix: update community pages * remove github discussions from agent v3 docs * one line content types * update message * update messaging * remove agent connect instances doc * modify N1 doc to cover v2 and v3
1 parent 8c4573b commit 85b6d64

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

59 files changed

+219
-790
lines changed

‎content/agent/_index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,5 @@ description: NGINX Agent is a companion daemon for your NGINX Open Source or NGI
55
url: /nginx-agent/
66
cascade:
77
logo: NGINX-product-icon.png
8+
type: agent-v2-migration
89
---

‎content/agent/about.md

Lines changed: 63 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,67 @@
11
---
2-
title: "About"
2+
title: About
3+
draft: false
34
weight: 100
45
toc: true
5-
docs: DOCS-000
6+
nd-docs: DOCS-1091
7+
nd-content-type: how-to
68
---
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+

‎content/agent/changelog.md

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,7 @@ toc: true
66

77
{{< 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 >}}
88

9-
See the list of supported Operating Systems and architectures in the [Technical Specifications]({{< ref "./tech-specs.md" >}}).
10-
11-
---
12-
## Release [v3.0.0](https//github.com/nginx/agent/releases/tag/v3.0.0)
9+
See the list of supported Operating Systems and architectures in the [Technical Specifications]({{< ref "/agent/technical-specifications.md" >}}).
1310

1411
---
1512
## Release [v2.40.0](https://github.com/nginx/agent/releases/tag/v2.40.0)

‎content/agent/community.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: "Community and contribution"
3+
toc: true
4+
weight: 600
5+
nd-docs: DOCS-000
6+
---
7+
8+
Discover the various ways you can participate in the F5 NGINX Agent project:
9+
10+
## Community
11+
12+
- Have questions or ideas to discuss? Join the conversation about NGINX Agent in the [NGINX Community Forum](https://community.nginx.org/).
13+
14+
## Contribute
15+
16+
Get involved with the project by contributing! Please see our [contributing guide](https://github.com/nginx/agent/blob/main/CONTRIBUTING.md) for details.
17+
18+
## License
19+
20+
[Apache License, Version 2.0](https://github.com/nginx/agent/blob/main/LICENSE)

‎content/agent/configuration/_index.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: "Configuration"
3+
weight: "400"
4+
url: /nginx-agent/configuration/
5+
cascade:
6+
logo: NGINX-product-icon.png
7+
layout: agent-v2-migration
8+
---
9+
10+
Learn how to configure NGINX Agent.

‎content/agent/v2/configuration/configuration-overview.md renamed to ‎content/agent/configuration/configuration-overview.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,10 @@ title: Basic configuration
33
draft: false
44
weight: 100
55
toc: true
6-
docs: DOCS-1229
7-
type:
8-
- how-to
6+
nd-docs: DOCS-1229
7+
nd-content-type: how-to
8+
9+
910
---
1011

1112
The following sections explain how to configure NGINX Agent using configuration files, CLI flags, and environment variables.

‎content/agent/v2/configuration/configure-nginx-agent-group.md renamed to ‎content/agent/configuration/configure-nginx-agent-group.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,8 @@ title: "Add NGINX users to nginx-agent group"
33
draft: false
44
weight: 300
55
toc: true
6-
docs: DOCS-933
7-
type:
8-
- how-to
6+
nd-docs: DOCS-933
7+
nd-content-type: how-to
98
---
109

1110
## Overview

‎content/agent/v2/configuration/encrypt-communication.md renamed to ‎content/agent/configuration/encrypt-communication.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Encrypt communication
33
toc: true
44
weight: 200
5-
docs: DOCS-802
5+
nd-docs: DOCS-802
66
---
77

88
## Overview

‎content/agent/v2/configuration/health-checks.md renamed to ‎content/agent/configuration/health-checks.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@ title: Health checks
33
draft: false
44
weight: 400
55
toc: true
6-
type:
7-
- how-to
6+
nd-content-type: how-to
87
---
98

109
## Overview

‎content/agent/contribute/_index.md

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎content/agent/contribute/community.md

Lines changed: 0 additions & 22 deletions
This file was deleted.

‎content/agent/contribute/dev-environment-setup.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22
title: "Development environment setup"
33
toc: true
44
weight: 200
5-
docs: DOCS-000
5+
nd-docs: DOCS-000
6+
draft: true
67
---
78

89
## Overview
@@ -17,7 +18,7 @@ Ubuntu is the recommended operating system for development, as it comes with mos
1718

1819
To begin this task, you will require the following:
1920

20-
- A [working NGINX Agent instance]({{< ref "/agent/install-upgrade/" >}}).
21+
- A [working NGINX Agent instance]({{< ref "/nginx-one/agent/install-upgrade/" >}}).
2122
- A [Go installation](https://go.dev/dl/) of version 1.22.2 or newer.
2223
- A [Protocol Buffer Compiler](https://grpc.io/docs/protoc-installation/) installation.
2324

@@ -29,7 +30,7 @@ git clone [email protected]:nginx/agent.git
2930

3031
Read [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for more information
3132

32-
Follow the steps in the [Installation]({{< ref "/agent/install-upgrade/" >}}) topic to install NGINX Agent.
33+
Follow the steps in the [Installation]({{< ref "/nginx-one/agent/install-upgrade/" >}}) topic to install NGINX Agent.
3334

3435
## Install prerequisite packages
3536
Depending on the operating system distribution, it may be necessary to install the following packages in order to build NGINX Agent.

‎content/agent/contribute/start-mock-interface.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22
title: Start mock control plane interface
33
toc: true
44
weight: 300
5-
docs: DOCS-000
5+
nd-docs: DOCS-000
6+
draft: true
67
---
78

89
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
1314

1415
To begin this task, you will require the following:
1516

16-
- A [working NGINX Agent instance]({{< ref "/agent/install-upgrade/" >}}).
17+
- A [working NGINX Agent instance]({{< ref "/nginx-one/agent/install-upgrade/" >}}).
1718
- A [Go installation](https://go.dev/dl/) of version 1.22.2 or newer.
1819
- A [go-swagger](https://goswagger.io/go-swagger/install/) installation.
1920

‎content/agent/v2/installation-upgrade/_index.md renamed to ‎content/agent/installation-upgrade/_index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,7 @@ title: Installation and upgrade
33
description: Learn how to install, upgrade, and uninstall NGINX Agent.
44
weight: 300
55
url: /nginx-agent/v2/installation-upgrade/
6+
cascade:
7+
logo: NGINX-product-icon.png
8+
type: agent-v2-migration
69
---

‎content/agent/v2/installation-upgrade/container-environments/_index.md renamed to ‎content/agent/installation-upgrade/container-environments/_index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,7 @@ title: Container environments
33
description: Learn how to build and run NGINX Agent docker images.
44
weight: 800
55
url: /nginx-agent/v2/installation-upgrade/container-environments/
6+
cascade:
7+
logo: NGINX-product-icon.png
8+
type: agent-v2-migration
69
---

‎content/agent/v2/installation-upgrade/container-environments/docker-images.md renamed to ‎content/agent/installation-upgrade/container-environments/docker-images.md

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,8 @@ title: Build container images
33
draft: false
44
weight: 100
55
toc: true
6-
docs: DOCS-1410
7-
type:
8-
- how-to
6+
nd-docs: DOCS-1410
7+
nd-content-type: how-to
98
---
109

1110
## Overview
@@ -14,7 +13,7 @@ NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instances
1413

1514
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.
1615

17-
See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< ref "/agent/tech-specs.md" >}}) topic.
16+
See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< ref "/agent/technical-specifications.md" >}}) topic.
1817

1918
## Deploy Offical NGINX and NGINX Plus Containers
2019

@@ -113,7 +112,7 @@ docker tag docker-registry.nginx.com/nginx/agent:mainline nginx-agent
113112
docker run --name nginx-agent -d nginx-agent
114113
```
115114

116-
{{<note>}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< ref "/agent/v2/configuration/configuration-overview" >}}).{{</note>}}
115+
{{<note>}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< ref "/agent/configuration/configuration-overview" >}}).{{</note>}}
117116

118117
### Enable the gRPC interface
119118

‎content/agent/v2/installation-upgrade/container-environments/docker-support.md renamed to ‎content/agent/installation-upgrade/container-environments/docker-support.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,16 @@ title: Container support and troubleshooting
33
draft: false
44
toc: true
55
weight: 200
6-
docs: DOCS-909
7-
type:
6+
nd-docs: DOCS-909
7+
nd-content-type:
88
- task
99
---
1010

1111
## Overview
1212

13-
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.
13+
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.
1414

15-
See the [Technical Specifications]({{< ref "/agent/tech-specs.md#container-support" >}}) for a list of supported operationg systems.
15+
See the [Technical Specifications]({{< ref "/agent/technical-specifications.md" >}}) for a list of supported operationg systems.
1616

1717
NGINX Agent running in a container has some limitations that need to be considered, and are listed below.
1818

‎content/agent/v2/installation-upgrade/getting-started.md renamed to ‎content/agent/installation-upgrade/getting-started.md

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,8 @@ title: Getting started
33
draft: false
44
weight: 100
55
toc: true
6-
docs: DOCS-1089
7-
type:
8-
- how-to
6+
nd-docs: DOCS-1089
7+
nd-content-type: how-to
98
---
109

1110
## Overview
@@ -176,5 +175,5 @@ NGINX Agent uses formatted log files to collect metrics. Expanding log formats a
176175
{{< important >}}
177176
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.
178177

179-
For more information, see [NGINX Agent Log Rotation]({{< ref "/agent/v2/configuration/configuration-overview.md#nginx-agent-log-rotation" >}}).
178+
For more information, see [NGINX Agent Log Rotation]({{< ref "/agent/configuration/configuration-overview.md#nginx-agent-log-rotation" >}}).
180179
{{< /important >}}

‎content/agent/v2/installation-upgrade/installation-github.md renamed to ‎content/agent/installation-upgrade/installation-github.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,8 @@ title: Installation from GitHub release
33
draft: false
44
weight: 200
55
toc: true
6-
docs: DOCS-1090
7-
type:
8-
- how-to
6+
nd-docs: DOCS-1090
7+
nd-content-type: how-to
98
---
109

1110
## Overview

0 commit comments

Comments
 (0)