From 61a125fb4e932758210e14a0836ab0998cad471e Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney Date: Wed, 2 Apr 2025 16:13:04 +0100 Subject: [PATCH 01/26] Update metrics docs, add run-container guide --- content/agent/how-to/export-metrics.md | 45 ---- content/agent/how-to/run-agent-container.md | 98 ++++++++ content/agent/otel/configure-otel-metrics.md | 223 ++----------------- content/agent/otel/metrics.md | 5 - go.mod | 2 +- go.sum | 2 + 6 files changed, 116 insertions(+), 259 deletions(-) delete mode 100644 content/agent/how-to/export-metrics.md create mode 100644 content/agent/how-to/run-agent-container.md delete mode 100644 content/agent/otel/metrics.md diff --git a/content/agent/how-to/export-metrics.md b/content/agent/how-to/export-metrics.md deleted file mode 100644 index 9edae11dc..000000000 --- a/content/agent/how-to/export-metrics.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "Export metrics data" -weight: 300 -docs: DOCS-000 ---- - -This document describes how to export the metrics data from F5 NGINX Agent. - -[//]: # "These are Markdown comments to guide you through document structure." -[//]: # "Remove them as you go, as well as unnecessary sections for this use case." - -## Overview - -[//]: # "Write a description which outlines precisely what this page of instructions will accomplish." -[//]: # "This description, like all instructions, should be direct and imperative." -[//]: # "Avoid ambiguous promises such as 'enables functionality': state precisely what it does." - ---- - -## Before you begin - -[//]: # "List all of the prerequisites for completing this task." -[//]: # "This might be the first page for a reader, so include a link to installation." - -To begin this task, you will require the following: - -- A [working NGINX Agent instance]({{< relref "/agent/install-upgrade/install.md" >}}). -- -- - ---- - -## Export metrics data - - - ---- - -## See also - -[//]: # "Examples of additional topics users might want to read include:" -[//]: # "Relevant reference information, configuration options and more complex use cases." - -- [OpenTelemetry metrics]({{< relref "/agent/otel/metrics.md" >}}) -- diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md new file mode 100644 index 000000000..08d298dd6 --- /dev/null +++ b/content/agent/how-to/run-agent-container.md @@ -0,0 +1,98 @@ +--- +title: "Running the NGINX Agent in a Container" +weight: 300 +docs: DOCS-000 +--- + +## Overview + +This guide serves as a step-by-step guide to running the NGINX Agent in a container. It covers the basic setup needed to get the NGINX Agent up and running efficiently and securely. + +## Before you begin + +Before you begin this guide ensure: + +> **Note**: This guide uses docker but the Agent will also work with other application containers. + +- **Installed Docker:** Ensure Docker is installed and configured on your system. [You can download Docker here](https://www.docker.com/products/docker-desktop/). +- **NGINX Agent Image:** You need access to the Docker image for the NGINX Agent. Find the appropriate image in your organization's registry or on Docker Hub if publicly available. +- **NGINX Configuration File:** Prepare and validate your NGINX configuration files that the Agent will monitor. +- **Credentials:** Acquire any necessary authentication tokens or credentials required for the NGINX Agent. + +1. Pull the NGINX Agent Container Image + +The NGINX Agent container image must be downloaded from a trusted source such as Docker Hub or a private container registry. + +Run the following command to pull the official image: + +```bash + +docker pull :latest +``` + +Ensure you are using the correct image version. Replace `latest` with the desired version tag if necessary. + + +2. Create a Configuration File + +1. Create a configuration file named `nginx-agent.conf` in your current directory. +2. Populate the file with the following structure: + +```vim +command: + server: + host: "" # Command server host + port: 443 # Command server port + auth: + token: "" # Authentication token for the command server + tls: + skip_verify: false +``` + +Replace the placeholder values: + +- ``: The URL of your NGINX One Console instance. +- ``: Your Data Plane access token. + + +3. Run the Container + +Run the NGINX Agent container with the configuration file mounted. + +Use the following command: + +```bash +docker run -d \ + --name nginx-agent \ + -v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf \ + nginx/agent:latest +``` + +Key options explained: + +- `-d`: Runs the container in detached mode. +- `--name nginx-agent`: Assigns a name to the container for easy identification. +- `-v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf`: Mounts the configuration file into the container. + + +4. Verify the Container is Running + +Check the running status of the container: + +```bash +docker ps +``` + +You should see an entry for `nginx-agent`. The `STATUS` field should indicate that the container is running. + +5. Monitor Logs + +To ensure the container is functioning properly and communicating with NGINX One Console, monitor the container logs. + +Run the following command: + +```bash +docker logs -f nginx-agent +``` + +Look for log entries indicating successful connection to the NGINX One Console and periodic metric transmission. diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index cac034103..aa53768ad 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -1,229 +1,36 @@ --- -title: Metrics Export +title: Exporting Metrics with NGINX Agent weight: 200 --- ## Overview -The F5 NGINX Agent v3 now includes an embedded [OpenTelemetry](https://opentelemetry.io/) Collector, streamlining observability and metric collection for NGINX instances. With this feature, you can collect: +The F5 NGINX Agent now includes an embedded [OpenTelemetry](https://opentelemetry.io/) Collector, streamlining observability and metric collection for NGINX instances. With this feature, you can collect: * Metrics from NGINX Plus and NGINX OSS * Host metrics (CPU, memory, disk, and network activity) from VMs or Containers - -This guide walks you through enabling and configuring the embedded OpenTelemetry Collector for metric export. +> **Note**: The OpenTelemetry exporter is enabled by default. Once a valid connection to the management plane is established, the Agent will automatically begin exporting metrics. -# Key Benefits +### Key Benefits * Seamless Integration: No need to deploy an external OpenTelemetry Collector. All components are embedded within the Agent for streamlined observability. * Standardized Protocol: Support for OpenTelemetry standards ensures interoperability with a wide range of observability backends, including Jaeger, Prometheus, Splunk, and more. -## Before you begin +### Verify Metrics Exported -Before you begin configuring the F5 NGINX Agent OTel Collector: +You can validate that metrics are successfully exported by using the methods below: -- [NGINX One Console Getting Started]({{< relref "/nginx-one/getting-started" >}}) -- F5 NGINX OSS/Plus installed on a Virtual Machine -- F5 NGINX Agent v3 is installed +**NGINX One Dashboard** +- When an instance has connected to NGINX One Console [Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance.md" >}}), you should be able to see metrics showing on the NGINX One Dashboard. -## Configure the OTel Collector - Virtual Machine +**Agent Logs** -1. Locate the configuration file for the F5 NGINX Agent: +Check the OpenTelemetry Collector logs for confirmation of successful metric processing: - ```bash - /etc/nginx-agent/nginx-agent.conf - ``` -2. Open the configuration file for editing: - - ```bash - sudo vim /etc/nginx-agent/nginx-agent.conf - ``` - -3. Edit the `/etc/nginx-agent/nginx-agent.conf` and add the following. - - Make sure to replace your-data-plane-key-here with the real data plane key that you are using for your application or service. - - ```vim - collector: - receivers: - host_metrics: - collection_interval: 1m0s - initial_delay: 1s - scrapers: - cpu: {} - memory: {} - disk: {} - network: {} - filesystem: {} - processors: - batch: {} - exporters: - otlp_exporters: - - server: - host: - port: 443 - authenticator: headers_setter - tls: - skip_verify: false - extensions: - headers_setter: - headers: - - action: insert - key: "authorization" - value: "your-data-plane-key-here" - ``` -4. Restart the NGINX Agent service - - ```bash - sudo systemctl restart nginx-agent - ``` - -## Running a Container to Connect to the NGINX One Console and Send Metrics - -This guide provides step-by-step instructions on how to run a container to connect to the NGINX One Console and send metrics. Follow these steps to ensure proper setup and execution. - ---- - -## Prerequisites -Before running the container, ensure the following: -1. **Docker Installed**: Docker must be installed on your system. You can download it from [Docker's official website](https://www.docker.com/). -2. **NGINX One Console**: The NGINX One Console is set up and accessible. -3. **Data Plane Token**: Obtain an access key or Data Plane token from the NGINX One Console for authentication. -4. **Network Connectivity**: Verify that the container can reach the NGINX One Console endpoint. - ---- - -## Steps to Run the Container - -### Step 1: Pull the NGINX Metrics Agent Container Image -The NGINX Metrics Agent container image must be downloaded from a trusted source such as Docker Hub or a private container registry. - -Run the following command to pull the official image: -```bash - -docker pull :latest -``` - -Ensure you are using the correct image version. Replace `latest` with the desired version tag if necessary. - ---- - -### Step 2: Create a Configuration File - -1. Create a configuration file named `nginx-agent.conf` in your current directory. -2. Populate the file with the following structure: - -```vim -command: - server: - host: "" # Command server host - port: 443 # Command server port - type: 0 # Server type (e.g., 0 for gRPC) - auth: - token: "" # Authentication token for the command server - tls: - skip_verify: false - - collector: - receivers: - host_metrics: - collection_interval: 1m0s - initial_delay: 1s - scrapers: - cpu: {} - memory: {} - disk: {} - network: {} - filesystem: {} - processors: - batch: {} - exporters: - otlp_exporters: - - server: - host: - port: 443 - authenticator: headers_setter - tls: - skip_verify: false - extensions: - headers_setter: - headers: - - action: insert - key: "authorization" - value: "your-data-plane-key-here" -``` - -Replace the placeholder values: -- ``: The URL of your NGINX One Console instance. -- ``: Your Data Plane access token. - ---- - -### Step 3: Run the Container -Run the NGINX Agent container with the configuration file mounted. - -Use the following command: -```bash -docker run -d \ - --name nginx-agent \ - -v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf \ - nginx/agent:latest -``` - -Key options explained: -- `-d`: Runs the container in detached mode. -- `--name nginx-agent`: Assigns a name to the container for easy identification. -- `-v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf`: Mounts the configuration file into the container. - ---- - -### Step 4: Verify the Container is Running -Check the running status of the container: -```bash -docker ps -``` - -You should see an entry for `nginx-agent`. The `STATUS` field should indicate that the container is running. - ---- - -### Step 5: Monitor Logs -To ensure the container is functioning properly and communicating with NGINX One Console, monitor the container logs. - -Run the following command: -```bash -docker logs -f nginx-agent -``` - -Look for log entries indicating successful connection to the NGINX One Console and periodic metric transmission. - ---- - -### Troubleshooting - -1. **Container Fails to Start**: - - Check the configuration file for errors. - - Ensure the NGINX One Console endpoint is reachable from the host. - -2. **No Metrics Sent**: - - Verify the access token is valid. - - Confirm network connectivity to the NGINX One Console. - -3. **Logs Show Errors**: - - Examine the logs for specific error messages. - - Address any permission or network-related issues. - ---- - -## Clean Up -To stop and remove the container when it is no longer needed, run: -```bash -docker stop nginx-metrics-agent -docker rm nginx-metrics-agent -``` - ---- - -## Conclusion -Following these instructions, you can successfully run a container to connect to the NGINX One Console and send metrics. For further details or issues, refer to the documentation provided by NGINX or your administrator. \ No newline at end of file +1. Open the file: ```/var/log/nginx-agent/opentelemetry-collector-agent.log``` +2. Look for the following logs: + ```vim + Everything is ready. Begin running and processing data. + ``` \ No newline at end of file diff --git a/content/agent/otel/metrics.md b/content/agent/otel/metrics.md deleted file mode 100644 index 179f413b9..000000000 --- a/content/agent/otel/metrics.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: OpenTelemetry metrics -weight: 300 -docs: DOCS-000 ---- \ No newline at end of file diff --git a/go.mod b/go.mod index 96da5bb32..90217f278 100644 --- a/go.mod +++ b/go.mod @@ -2,4 +2,4 @@ module github.com/nginxinc/docs go 1.19 -require github.com/nginxinc/nginx-hugo-theme v0.42.24 // indirect +require github.com/nginxinc/nginx-hugo-theme v0.42.25 // indirect diff --git a/go.sum b/go.sum index 55949eecc..10bea363f 100644 --- a/go.sum +++ b/go.sum @@ -4,3 +4,5 @@ github.com/nginxinc/nginx-hugo-theme v0.41.27 h1:M8ttO1ZkTGY06o0MYvnm3kc/sA6lOmI github.com/nginxinc/nginx-hugo-theme v0.41.27/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= github.com/nginxinc/nginx-hugo-theme v0.42.24 h1:aQkkTob0EpK+1ID+31E3y+RIdThldC4HgA2LcJL4TXU= github.com/nginxinc/nginx-hugo-theme v0.42.24/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v0.42.25 h1:QkLTREuOohkq+hmBZCfWELAri4AOvhc6gmIJA1esUfo= +github.com/nginxinc/nginx-hugo-theme v0.42.25/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= From c486596ed5563d03a50040f873fd9e12756adbbf Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:21:05 +0100 Subject: [PATCH 02/26] Apply suggestion to update metadata for how-to guide. Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/how-to/run-agent-container.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index 08d298dd6..c3ef81d51 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -1,7 +1,9 @@ --- title: "Running the NGINX Agent in a Container" weight: 300 -docs: DOCS-000 +toc: true +type: how-to +product: Agent --- ## Overview From e449dc4e1239e12b1db8457fedb0c58e3b1430e5 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:29:36 +0100 Subject: [PATCH 03/26] Apply suggestion to update markdown format, and code block Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/otel/configure-otel-metrics.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index aa53768ad..30598e78d 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -29,8 +29,9 @@ You can validate that metrics are successfully exported by using the methods bel Check the OpenTelemetry Collector logs for confirmation of successful metric processing: -1. Open the file: ```/var/log/nginx-agent/opentelemetry-collector-agent.log``` -2. Look for the following logs: - ```vim - Everything is ready. Begin running and processing data. - ``` \ No newline at end of file + 1. Open the file: ```/var/log/nginx-agent/opentelemetry-collector-agent.log``` + 2. Look for the following logs: + + ```text + Everything is ready. Begin running and processing data. + ``` \ No newline at end of file From 27d6bd63a9b149e24d67d945498d349ea39effa0 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:30:24 +0100 Subject: [PATCH 04/26] Apply suggestion to update locating config file Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/otel/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index 30598e78d..cc3a52c4a 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -27,7 +27,7 @@ You can validate that metrics are successfully exported by using the methods bel **Agent Logs** -Check the OpenTelemetry Collector logs for confirmation of successful metric processing: + Check the OpenTelemetry Collector logs for confirmation of successful metric processing: 1. Open the file: ```/var/log/nginx-agent/opentelemetry-collector-agent.log``` 2. Look for the following logs: From 14c7195c98a3152ec3b13100c372e87500535cd5 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:41:07 +0100 Subject: [PATCH 05/26] Apply suggestion to title Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/otel/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index cc3a52c4a..76c07337e 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -1,5 +1,5 @@ --- -title: Exporting Metrics with NGINX Agent +title: Export metrics with NGINX Agent weight: 200 --- From aeb7db45f3655146971dc2a03f42f594f8f4b92a Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:41:25 +0100 Subject: [PATCH 06/26] Apply suggestion to title Co-authored-by: Alan Dooley --- content/agent/how-to/run-agent-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index c3ef81d51..937f9ab4e 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -1,5 +1,5 @@ --- -title: "Running the NGINX Agent in a Container" +title: "Run the NGINX Agent in a container" weight: 300 toc: true type: how-to From 9ee64665afcc45c2870e44a677f0fdc9f7871a15 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:41:54 +0100 Subject: [PATCH 07/26] Apply suggestion to sentence. Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/how-to/run-agent-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index 937f9ab4e..226a285d6 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -8,7 +8,7 @@ product: Agent ## Overview -This guide serves as a step-by-step guide to running the NGINX Agent in a container. It covers the basic setup needed to get the NGINX Agent up and running efficiently and securely. +This guide serves as a step-by-step guide to run NGINX Agent in a container. It covers the basic setup needed to get the NGINX Agent up and running efficiently and securely. ## Before you begin From b5d185450955042676e5c3594120e2726de40631 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:42:25 +0100 Subject: [PATCH 08/26] Apply suggestion to use correct note element Co-authored-by: Alan Dooley --- content/agent/how-to/run-agent-container.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index 226a285d6..3b871ae11 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -14,7 +14,9 @@ This guide serves as a step-by-step guide to run NGINX Agent in a container. It Before you begin this guide ensure: -> **Note**: This guide uses docker but the Agent will also work with other application containers. +{{< note >}} +This guide uses Docker but NGINX Agent will also work with other container applications. +{{< /note >}} - **Installed Docker:** Ensure Docker is installed and configured on your system. [You can download Docker here](https://www.docker.com/products/docker-desktop/). - **NGINX Agent Image:** You need access to the Docker image for the NGINX Agent. Find the appropriate image in your organization's registry or on Docker Hub if publicly available. From af7c5b7dc4d561617fdefe11afa18d53f71fdcc4 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:43:18 +0100 Subject: [PATCH 09/26] Apply suggestion Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/how-to/run-agent-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index 3b871ae11..545caa1e9 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -18,7 +18,7 @@ Before you begin this guide ensure: This guide uses Docker but NGINX Agent will also work with other container applications. {{< /note >}} -- **Installed Docker:** Ensure Docker is installed and configured on your system. [You can download Docker here](https://www.docker.com/products/docker-desktop/). +- **Docker:** Ensure Docker is installed and configured on your system. [Download Docker from the official site](https://www.docker.com/products/docker-desktop/). - **NGINX Agent Image:** You need access to the Docker image for the NGINX Agent. Find the appropriate image in your organization's registry or on Docker Hub if publicly available. - **NGINX Configuration File:** Prepare and validate your NGINX configuration files that the Agent will monitor. - **Credentials:** Acquire any necessary authentication tokens or credentials required for the NGINX Agent. From 99daffb20333481f72e6fa1923c25185b971a7f2 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:43:43 +0100 Subject: [PATCH 10/26] Apply suggestion Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/how-to/run-agent-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index 545caa1e9..85343c225 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -19,7 +19,7 @@ This guide uses Docker but NGINX Agent will also work with other container appli {{< /note >}} - **Docker:** Ensure Docker is installed and configured on your system. [Download Docker from the official site](https://www.docker.com/products/docker-desktop/). -- **NGINX Agent Image:** You need access to the Docker image for the NGINX Agent. Find the appropriate image in your organization's registry or on Docker Hub if publicly available. +- **NGINX Agent Image:** You need access to the Docker image for NGINX Agent. Find the appropriate image in your organization's registry or on Docker Hub if publicly available. - **NGINX Configuration File:** Prepare and validate your NGINX configuration files that the Agent will monitor. - **Credentials:** Acquire any necessary authentication tokens or credentials required for the NGINX Agent. From 6a40c4d7427284ce8f1913018c478e62b25a78f5 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:43:59 +0100 Subject: [PATCH 11/26] Update content/agent/how-to/run-agent-container.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/how-to/run-agent-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index 85343c225..b139f4b99 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -23,7 +23,7 @@ This guide uses Docker but NGINX Agent will also work with other container appli - **NGINX Configuration File:** Prepare and validate your NGINX configuration files that the Agent will monitor. - **Credentials:** Acquire any necessary authentication tokens or credentials required for the NGINX Agent. -1. Pull the NGINX Agent Container Image +1. Pull the NGINX Agent container image The NGINX Agent container image must be downloaded from a trusted source such as Docker Hub or a private container registry. From 6302f0e34e8c368062f7a90f25a810180e25de5d Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:44:08 +0100 Subject: [PATCH 12/26] Update content/agent/how-to/run-agent-container.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/how-to/run-agent-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index b139f4b99..fc3f73091 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -37,7 +37,7 @@ docker pull :latest Ensure you are using the correct image version. Replace `latest` with the desired version tag if necessary. -2. Create a Configuration File +2. Create a configuration file 1. Create a configuration file named `nginx-agent.conf` in your current directory. 2. Populate the file with the following structure: From cf726ce752144630efa3ab80e3757485c4d80bb4 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:44:50 +0100 Subject: [PATCH 13/26] Update content/agent/how-to/run-agent-container.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/how-to/run-agent-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index fc3f73091..cde780e7e 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -79,7 +79,7 @@ Key options explained: - `-v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf`: Mounts the configuration file into the container. -4. Verify the Container is Running +4. Verify the container is running Check the running status of the container: From 683c2ea1385e3f956dd12e5250ab55523b873e4b Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:45:07 +0100 Subject: [PATCH 14/26] Update content/agent/how-to/run-agent-container.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/how-to/run-agent-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index cde780e7e..991f0bd94 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -89,7 +89,7 @@ docker ps You should see an entry for `nginx-agent`. The `STATUS` field should indicate that the container is running. -5. Monitor Logs +5. Monitor logs To ensure the container is functioning properly and communicating with NGINX One Console, monitor the container logs. From 20a940e93aca131f95f10819e715ca42511e2819 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:45:21 +0100 Subject: [PATCH 15/26] Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/otel/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index 76c07337e..50f70518a 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -5,7 +5,7 @@ weight: 200 ## Overview -The F5 NGINX Agent now includes an embedded [OpenTelemetry](https://opentelemetry.io/) Collector, streamlining observability and metric collection for NGINX instances. With this feature, you can collect: +F5 NGINX Agent now includes an embedded [OpenTelemetry](https://opentelemetry.io/) collector, streamlining observability and metric collection for NGINX instances. With this feature, you can collect: * Metrics from NGINX Plus and NGINX OSS * Host metrics (CPU, memory, disk, and network activity) from VMs or Containers From dc7685916bb5dccdc86c371f2fb689ffcd557f82 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:45:40 +0100 Subject: [PATCH 16/26] Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/otel/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index 50f70518a..38f2e39b6 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -7,7 +7,7 @@ weight: 200 F5 NGINX Agent now includes an embedded [OpenTelemetry](https://opentelemetry.io/) collector, streamlining observability and metric collection for NGINX instances. With this feature, you can collect: -* Metrics from NGINX Plus and NGINX OSS +* Metrics from NGINX Plus and NGINX OSS * Host metrics (CPU, memory, disk, and network activity) from VMs or Containers > **Note**: The OpenTelemetry exporter is enabled by default. Once a valid connection to the management plane is established, the Agent will automatically begin exporting metrics. From ee50b278db493f45162fa96379e5ae078eeb0506 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:46:14 +0100 Subject: [PATCH 17/26] Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/otel/configure-otel-metrics.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index 38f2e39b6..fadca7a5e 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -10,7 +10,9 @@ F5 NGINX Agent now includes an embedded [OpenTelemetry](https://opentelemetry.io * Metrics from NGINX Plus and NGINX OSS * Host metrics (CPU, memory, disk, and network activity) from VMs or Containers -> **Note**: The OpenTelemetry exporter is enabled by default. Once a valid connection to the management plane is established, the Agent will automatically begin exporting metrics. +{{< note >}} +The OpenTelemetry exporter is enabled by default. Once a valid connection to the management plane is established, the Agent will automatically begin exporting metrics. +{{< /note >}} ### Key Benefits From 2b2c5812887dc8e6114e37eb2b92c4ad75f96b6e Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:46:29 +0100 Subject: [PATCH 18/26] Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/otel/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index fadca7a5e..aff4901c0 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -14,7 +14,7 @@ F5 NGINX Agent now includes an embedded [OpenTelemetry](https://opentelemetry.io The OpenTelemetry exporter is enabled by default. Once a valid connection to the management plane is established, the Agent will automatically begin exporting metrics. {{< /note >}} -### Key Benefits +### Key benefits * Seamless Integration: No need to deploy an external OpenTelemetry Collector. All components are embedded within the Agent for streamlined observability. * Standardized Protocol: Support for OpenTelemetry standards ensures interoperability with a wide range of observability backends, including Jaeger, Prometheus, Splunk, and more. From 07dbd7188afee83fc38f88bc4c94ea8007dbff3b Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:46:41 +0100 Subject: [PATCH 19/26] Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/otel/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index aff4901c0..fdd727854 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -19,7 +19,7 @@ The OpenTelemetry exporter is enabled by default. Once a valid connection to the * Seamless Integration: No need to deploy an external OpenTelemetry Collector. All components are embedded within the Agent for streamlined observability. * Standardized Protocol: Support for OpenTelemetry standards ensures interoperability with a wide range of observability backends, including Jaeger, Prometheus, Splunk, and more. -### Verify Metrics Exported +### Verify that metrics are exported You can validate that metrics are successfully exported by using the methods below: From c8c3e3a463f4ad6e12cdf96aced0a4cad4fefae2 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:46:52 +0100 Subject: [PATCH 20/26] Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/otel/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index fdd727854..e7a42bf90 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -23,7 +23,7 @@ The OpenTelemetry exporter is enabled by default. Once a valid connection to the You can validate that metrics are successfully exported by using the methods below: -**NGINX One Dashboard** +- **NGINX One dashboard** - When an instance has connected to NGINX One Console [Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance.md" >}}), you should be able to see metrics showing on the NGINX One Dashboard. From ff618801f570a2661cb0156202916efe3cd59190 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:47:01 +0100 Subject: [PATCH 21/26] Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/otel/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index e7a42bf90..bbc5bc717 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -25,7 +25,7 @@ You can validate that metrics are successfully exported by using the methods bel - **NGINX One dashboard** -- When an instance has connected to NGINX One Console [Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance.md" >}}), you should be able to see metrics showing on the NGINX One Dashboard. + - When an instance has connected to NGINX One Console [See: Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance.md" >}}), you should see metrics showing on the NGINX One Dashboard. **Agent Logs** From 49c039d4ac60f63323ac9a7b62ebb06648dd9aaf Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:47:20 +0100 Subject: [PATCH 22/26] Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> --- content/agent/otel/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index bbc5bc717..0d992d371 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -27,7 +27,7 @@ You can validate that metrics are successfully exported by using the methods bel - When an instance has connected to NGINX One Console [See: Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance.md" >}}), you should see metrics showing on the NGINX One Dashboard. -**Agent Logs** +- **Agent logs** Check the OpenTelemetry Collector logs for confirmation of successful metric processing: From 03f08f58f07dd613cac0becccb7aa0c48125025d Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney Date: Mon, 7 Apr 2025 14:59:13 +0100 Subject: [PATCH 23/26] docs: Change Container to container, based on PR feedback --- content/agent/how-to/run-agent-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index 991f0bd94..7aa62ab35 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -59,7 +59,7 @@ Replace the placeholder values: - ``: Your Data Plane access token. -3. Run the Container +3. Run the container Run the NGINX Agent container with the configuration file mounted. From 794366771a6ac2bab69eece989b4c381d0b4e344 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Tue, 8 Apr 2025 12:40:56 +0100 Subject: [PATCH 24/26] Update content/agent/otel/configure-otel-metrics.md Co-authored-by: yar --- content/agent/otel/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index 0d992d371..0e302b7a4 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -7,7 +7,7 @@ weight: 200 F5 NGINX Agent now includes an embedded [OpenTelemetry](https://opentelemetry.io/) collector, streamlining observability and metric collection for NGINX instances. With this feature, you can collect: -* Metrics from NGINX Plus and NGINX OSS +* Metrics from NGINX Plus and NGINX Open Source * Host metrics (CPU, memory, disk, and network activity) from VMs or Containers {{< note >}} From 58194d4aece7782728ee7f2d35403ee131d8e8ff Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Tue, 8 Apr 2025 12:44:48 +0100 Subject: [PATCH 25/26] Apply suggestions from code review Co-authored-by: Mike Jang <3287976+mjang@users.noreply.github.com> --- content/agent/how-to/run-agent-container.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index 7aa62ab35..e60b4ce26 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -15,7 +15,7 @@ This guide serves as a step-by-step guide to run NGINX Agent in a container. It Before you begin this guide ensure: {{< note >}} -This guide uses Docker but NGINX Agent will also work with other container applications. +This guide uses Docker but NGINX Agent also works with other container applications. {{< /note >}} - **Docker:** Ensure Docker is installed and configured on your system. [Download Docker from the official site](https://www.docker.com/products/docker-desktop/). @@ -42,7 +42,7 @@ Ensure you are using the correct image version. Replace `latest` with the desire 1. Create a configuration file named `nginx-agent.conf` in your current directory. 2. Populate the file with the following structure: -```vim +```yaml command: server: host: "" # Command server host @@ -87,7 +87,7 @@ Check the running status of the container: docker ps ``` -You should see an entry for `nginx-agent`. The `STATUS` field should indicate that the container is running. +You should see an entry for `nginx-agent`. The `STATUS` field indicates that the container is running. 5. Monitor logs From 5bd709340df9c2695bd39f320682a3ba88c80b5a Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Tue, 8 Apr 2025 13:22:52 +0100 Subject: [PATCH 26/26] docs: improve layout --- content/agent/how-to/run-agent-container.md | 21 ++++++++++++--------- go.mod | 2 +- go.sum | 2 ++ 3 files changed, 15 insertions(+), 10 deletions(-) diff --git a/content/agent/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md index e60b4ce26..09c7397c6 100644 --- a/content/agent/how-to/run-agent-container.md +++ b/content/agent/how-to/run-agent-container.md @@ -19,11 +19,14 @@ This guide uses Docker but NGINX Agent also works with other container applicati {{< /note >}} - **Docker:** Ensure Docker is installed and configured on your system. [Download Docker from the official site](https://www.docker.com/products/docker-desktop/). -- **NGINX Agent Image:** You need access to the Docker image for NGINX Agent. Find the appropriate image in your organization's registry or on Docker Hub if publicly available. -- **NGINX Configuration File:** Prepare and validate your NGINX configuration files that the Agent will monitor. - **Credentials:** Acquire any necessary authentication tokens or credentials required for the NGINX Agent. -1. Pull the NGINX Agent container image +## Prepare the environment + +To run NGINX Agent in a container you will need to download the NGINX Agent +container image and create a configuration file. + +### Pull the NGINX Agent container image The NGINX Agent container image must be downloaded from a trusted source such as Docker Hub or a private container registry. @@ -37,10 +40,10 @@ docker pull :latest Ensure you are using the correct image version. Replace `latest` with the desired version tag if necessary. -2. Create a configuration file +### Create a configuration file -1. Create a configuration file named `nginx-agent.conf` in your current directory. -2. Populate the file with the following structure: +Create a configuration file named `nginx-agent.conf` in your current directory +and populate the file with the following structure: ```yaml command: @@ -59,7 +62,7 @@ Replace the placeholder values: - ``: Your Data Plane access token. -3. Run the container +## Run the container Run the NGINX Agent container with the configuration file mounted. @@ -79,7 +82,7 @@ Key options explained: - `-v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf`: Mounts the configuration file into the container. -4. Verify the container is running +### Verify the container is running Check the running status of the container: @@ -89,7 +92,7 @@ docker ps You should see an entry for `nginx-agent`. The `STATUS` field indicates that the container is running. -5. Monitor logs +### Monitor logs To ensure the container is functioning properly and communicating with NGINX One Console, monitor the container logs. diff --git a/go.mod b/go.mod index 90217f278..a3d4d13aa 100644 --- a/go.mod +++ b/go.mod @@ -2,4 +2,4 @@ module github.com/nginxinc/docs go 1.19 -require github.com/nginxinc/nginx-hugo-theme v0.42.25 // indirect +require github.com/nginxinc/nginx-hugo-theme v0.42.26 // indirect diff --git a/go.sum b/go.sum index 10bea363f..8ff764f5f 100644 --- a/go.sum +++ b/go.sum @@ -6,3 +6,5 @@ github.com/nginxinc/nginx-hugo-theme v0.42.24 h1:aQkkTob0EpK+1ID+31E3y+RIdThldC4 github.com/nginxinc/nginx-hugo-theme v0.42.24/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= github.com/nginxinc/nginx-hugo-theme v0.42.25 h1:QkLTREuOohkq+hmBZCfWELAri4AOvhc6gmIJA1esUfo= github.com/nginxinc/nginx-hugo-theme v0.42.25/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v0.42.26 h1:DCJMXt/l3DY646sB+RgojnSRaWPNAz9o6imKfXZF8gA= +github.com/nginxinc/nginx-hugo-theme v0.42.26/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=