diff --git a/content/agent/about.md b/content/agent/about.md index 1e9f0f32f..022dcdd90 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -4,80 +4,43 @@ weight: 100 toc: true docs: DOCS-000 --- +{{}} + +{{}} -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>}}
{{}} -{{}} -| 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 | -{{}} -{{< raw-html>}}
{{}} - - diff --git a/content/agent/how-to/configuration-overview.md b/content/agent/how-to/configuration-overview.md index 26c2a41b2..03fbe48ac 100644 --- a/content/agent/how-to/configuration-overview.md +++ b/content/agent/how-to/configuration-overview.md @@ -1,7 +1,7 @@ --- title: "Configuration overview" toc: true -weight: 100 +weight: 300 docs: DOCS-1229 --- @@ -19,272 +19,32 @@ This page describes how to configure F5 NGINX Agent using configuration files, C {{}} -## Configuration files +## Configuration via Configuration Files -The default locations of configuration files for NGINX Agent are `/etc/nginx-agent/nginx-agent.conf` and `/var/lib/nginx-agent/agent-dynamic.conf`. The `agent-dynamic.conf` file default location is different for FreeBSD which is located `/var/db/nginx-agent/agent-dynamic.conf`. These files have comments at the top indicating their purpose. +The NGINX Agent configuration file is created using a YAML structure and can be found in `/etc/nginx-agent/nginx-agent.conf` -Examples of the configuration files are provided below: - -
- example nginx-agent.conf - -{{}} -In the following example `nginx-agent.conf` file, you can change the `server.host` and `server.grpcPort` to connect to the control plane. -{{}} - -```nginx {hl_lines=[13]} -# -# /etc/nginx-agent/nginx-agent.conf -# -# Configuration file for NGINX Agent. -# -# This file tracks agent configuration values that are meant to be statically set. There -# are additional NGINX Agent configuration values that are set via the API and agent install script -# which can be found in /etc/nginx-agent/agent-dynamic.conf. - -# specify the server grpc port to connect to -server: - # host of the control plane - host: - grpcPort: 443 - backoff: # note: default values are prepopulated - initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour - randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10 - multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5 - max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour - max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour -# tls options -tls: - # enable tls in the nginx-agent setup for grpcs - # default to enable to connect with secure connection but without client cert for mtls - enable: true - # controls whether the server certificate chain and host name are verified. - # for production use, see instructions for configuring TLS - skip_verify: false +1. Edit the configuration file `sudo vim /etc/nginx-agent/nginx-agent.conf` +2. Add the log property +```bash log: - # set log level (panic, fatal, error, info, debug, trace; default "info") - level: info - # set log path. if empty, don't log to file. - path: /var/log/nginx-agent/ -nginx: - # path of NGINX logs to exclude - exclude_logs: "" - # Set to true when NGINX configuration should contain no warnings when performing a configuration apply (nginx -t is used to carry out this check) - treat_warnings_as_errors: false # Default is false -# data plane status message / 'heartbeat' -dataplane: - status: - # poll interval for dataplane status - the frequency the NGINX Agent will query the dataplane for changes - poll_interval: 30s - # report interval for dataplane status - the maximum duration to wait before syncing dataplane information if no updates have been observed - report_interval: 24h -metrics: - # specify the size of a buffer to build before sending metrics - bulk_size: 20 - # specify metrics poll interval - report_interval: 1m - collection_interval: 15s - mode: aggregated - backoff: # note: default values are prepopulated - initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour - randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10 - multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5 - max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour - max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour - -# OSS NGINX default config path -# path to aux file dirs can also be added -config_dirs: "/etc/nginx:/usr/local/etc/nginx" - -# Internal queue size -queue_size: 100 - -extensions: - - nginx-app-protect - -# Enable reporting NGINX App Protect details to the control plane. -nginx_app_protect: - # Report interval for NGINX App Protect details - the frequency NGINX Agent checks NGINX App Protect for changes. - report_interval: 15s - # Enable precompiled publication from the NGINX Management Suite (true) or perform compilation on the data plane host (false). - precompiled_publication: true + level: debug ``` +3. Save and exit +4. `sudo systemctl restart nginx-agent` -
- - -
- example dynamic-agent.conf +## Configuration via CLI Parameters -{{}} -Default location in Linux environments: `/var/lib/nginx-agent/agent-dynamic.conf` - -Default location in FreeBSD environments: `/var/db/nginx-agent/agent-dynamic.conf` -{{}} - -```yaml -# Dynamic configuration file for NGINX Agent. -# -# The purpose of this file is to track agent configuration -# values that can be dynamically changed via the API and the agent install script. -# You may edit this file, but API calls that modify the tags on this system will -# overwrite the tag values in this file. -# -# The agent configuration values that API calls can modify are as follows: -# tags: -# - dev -# - qa -# -# The agent configuration value that the agent install script can modify are as follows: -# instance_group: my-instance-group - -instance_group: my-instance-group -tags: - - dev - - qa -``` - -
- -## CLI flags and environment variables - -This section details the CLI flags and corresponding environment variables used to configure the NGINX Agent. - -### CLI flags - -```sh -nginx-agent [flags] -``` - -### Environment variables - -```sh -export ENV_VARIABLE_NAME="value" -nginx-agent +From a command line terminal: +```bash +sudo nginx-agent \ + --log-level=debug ``` -### Flag and environment arguments - -{{< warning >}} - -Before version 2.35.0, the environment variables were prefixed with `NMS_` instead of `NGINX_AGENT_`. - -If you are upgrading from an older version, update your configuration accordingly. +## Configuration via Environment Variables +Environment variables are another way to set configuration values, especially in containerized deployments or CI/CD pipelines. -{{< /warning >}} - -{{}} -| CLI flag | Environment variable | Description | -|---------------------------------------------|--------------------------------------|-----------------------------------------------------------------------------| -| `--api-cert` | `NGINX_AGENT_API_CERT` | Specifies the certificate used by the Agent API. | -| `--api-host` | `NGINX_AGENT_API_HOST` | Sets the host used by the Agent API. Default: *127.0.0.1* | -| `--api-key` | `NGINX_AGENT_API_KEY` | Specifies the key used by the Agent API. | -| `--api-port` | `NGINX_AGENT_API_PORT` | Sets the port for exposing nginx-agent to HTTP traffic. | -| `--config-dirs` | `NGINX_AGENT_CONFIG_DIRS` | Defines directories NGINX Agent can read/write. Default: *"/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms"* | -| `--dataplane-report-interval` | `NGINX_AGENT_DATAPLANE_REPORT_INTERVAL` | Sets the interval for dataplane reporting. Default: *24h0m0s* | -| `--dataplane-status-poll-interval` | `NGINX_AGENT_DATAPLANE_STATUS_POLL_INTERVAL` | Sets the interval for polling dataplane status. Default: *30s* | -| `--display-name` | `NGINX_AGENT_DISPLAY_NAME` | Sets the instance's display name. | -| `--dynamic-config-path` | `NGINX_AGENT_DYNAMIC_CONFIG_PATH` | Specifies the path of the Agent dynamic config file. Default: *"/var/lib/nginx-agent/agent-dynamic.conf"* | -| `--features` | `NGINX_AGENT_FEATURES` | Specifies a comma-separated list of features enabled for the agent. Default: *[registration, nginx-config-async, nginx-ssl-config, nginx-counting, metrics, dataplane-status, process-watcher, file-watcher, activity-events, agent-api]* | -| `--ignore-directives` | | Specifies a comma-separated list of directives to ignore for sensitive info.| -| `--instance-group` | `NGINX_AGENT_INSTANCE_GROUP` | Sets the instance's group value. | -| `--log-level` | `NGINX_AGENT_LOG_LEVEL` | Sets the logging level (e.g., panic, fatal, error, info, debug, trace). Default: *info* | -| `--log-path` | `NGINX_AGENT_LOG_PATH` | Specifies the path to output log messages. | -| `--metrics-bulk-size` | `NGINX_AGENT_METRICS_BULK_SIZE` | Specifies the number of metrics reports collected before sending data. Default: *20* | -| `--metrics-collection-interval` | `NGINX_AGENT_METRICS_COLLECTION_INTERVAL` | Sets the interval for metrics collection. Default: *15s* | -| `--metrics-mode` | `NGINX_AGENT_METRICS_MODE` | Sets the metrics collection mode: streaming or aggregation. Default: *aggregated* | -| `--metrics-report-interval` | `NGINX_AGENT_METRICS_REPORT_INTERVAL` | Sets the interval for reporting collected metrics. Default: *1m0s* | -| `--nginx-config-reload-monitoring-period` | | Sets the duration to monitor error logs after an NGINX reload. Default: *10s* | -| `--nginx-exclude-logs` | `NGINX_AGENT_NGINX_EXCLUDE_LOGS` | Specifies paths of NGINX access logs to exclude from metrics collection. | -| `--nginx-socket` | `NGINX_AGENT_NGINX_SOCKET` | Specifies the location of the NGINX Plus counting Unix socket. Default: *unix:/var/run/nginx-agent/nginx.sock* | -| `--nginx-treat-warnings-as-errors` | `NGINX_AGENT_NGINX_TREAT_WARNINGS_AS_ERRORS` | Treats warnings as failures on configuration application. | -| `--queue-size` | `NGINX_AGENT_QUEUE_SIZE` | Specifies the size of the NGINX Agent internal queue. | -| `--server-command` | | Specifies the name of the command server sent in the TLS configuration. | -| `--server-grpcport` | `NGINX_AGENT_SERVER_GRPCPORT` | Sets the desired GRPC port for NGINX Agent traffic. | -| `--server-host` | `NGINX_AGENT_SERVER_HOST` | Specifies the IP address of the server host. | -| `--server-metrics` | | Specifies the name of the metrics server sent in the TLS configuration. | -| `--server-token` | `NGINX_AGENT_SERVER_TOKEN` | Sets the authentication token for accessing the commander and metrics services. Default: *e202f883-54c6-4702-be15-3ba6e507879a* | -| `--tags` | `NGINX_AGENT_TAGS` | Specifies a comma-separated list of tags for the instance or machine. | -| `--tls-ca` | `NGINX_AGENT_TLS_CA` | Specifies the path to the CA certificate file for TLS. | -| `--tls-cert` | `NGINX_AGENT_TLS_CERT` | Specifies the path to the certificate file for TLS. | -| `--tls-enable` | `NGINX_AGENT_TLS_ENABLE` | Enables TLS for secure communications. | -| `--tls-key` | `NGINX_AGENT_TLS_KEY` | Specifies the path to the certificate key file for TLS. | -| `--tls-skip-verify` | `NGINX_AGENT_TLS_SKIP_VERIFY` | Insecurely skips verification for gRPC TLS credentials. | -{{}} - -
- -{{}} -Use the `--config-dirs` command-line option, or the `config_dirs` key in the `nginx-agent.conf` file, to identify the directories NGINX Agent can read from or write to. This setting also defines the location to which you can upload config files when using a control plane. - -NGINX Agent cannot write to directories outside the specified location when updating a config and cannot upload files to directories outside of the configured location. - -NGINX Agent follows NGINX configuration directives to file paths outside the designated directories and reads certificates' metadata. NGINX Agent uses the following directives: - -- [`ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate) - -{{}} - -{{}} Use the `--dynamic-config-path` command-line option to set the location of the dynamic config file. This setting also requires you to move your dynamic config to the new path, or create a new dynamic config file at the specified location. - -Default location in Linux environments: `/var/lib/nginx-agent/agent-dynamic.conf` - -Default location in FreeBSD environments: `/var/db/nginx-agent/agent-dynamic.conf` - -{{}} - -## Logs - -NGINX Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of the NGINX Agent log files. - -We recommend adding a separate partition for `/var/log/nginx-agent`. - -{{< 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. -{{< /important >}} - -By default, NGINX Agent rotates logs daily using logrotate with the following configuration: - -
- NGINX Agent Logrotate Configuration - -``` yaml -/var/log/nginx-agent/*.log -{ - # log files are rotated every day - daily - # log files are rotated if they grow bigger than 5M - size 5M - # truncate the original log file after creating a copy - copytruncate - # remove rotated logs older than 10 days - maxage 10 - # log files are rotated 10 times before being removed - rotate 10 - # old log files are compressed - compress - # if the log file is missing it will go on to the next one without issuing an error message - missingok - # do not rotate the log if it is empty - notifempty -} +```bash +sudo docker run \ + --env=NGINX_AGENT_LOG_LEVEL=debug \ + -d agent ``` -
- -If you need to change the default configuration, update the file at `/etc/logrotate.d/nginx-agent`. - -For more details on logrotate configuration, see [Logrotate Configuration Options](https://linux.die.net/man/8/logrotate). - - -## Extensions - -An extension is noncritical code to the main functionality of NGINX Agent. They generally cover functionality outside of managing NGINX configuration and reporting metrics. - -To enable an extension, it must be added to the extensions list in the `/etc/nginx-agent/nginx-agent.conf`. - -This example enables the advanced metrics extension: - -```yaml -extensions: - - advanced-metrics -``` \ No newline at end of file diff --git a/content/agent/install-upgrade/install.md b/content/agent/install-upgrade/install.md index d95291816..d9660cc1b 100644 --- a/content/agent/install-upgrade/install.md +++ b/content/agent/install-upgrade/install.md @@ -7,6 +7,7 @@ docs: DOCS-000 This document describes the three main ways to install F5 NGINX agent: +- Using NGINX One Console - Using the NGINX Open Source repository - Using the NGINX Plus repository - Using the GitHub package files @@ -15,17 +16,34 @@ This document describes the three main ways to install F5 NGINX agent: There are a few prerequisites shared between all installation methods: +- [NGINX One Console Getting Started]({{< relref "/nginx-one/getting-started" >}}) - A [supported operating system and architecture](../technical-specifications/#supported-distributions) - `root` privilege -## NGINX Open Source repository - -Before you install NGINX Agent, you must install and run NGINX. - -If you don't have it installed already, read the [Installing NGINX Open Source -](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) topic. - - +When F5 NGINX Agent is installed, it will remain idle in the background. For proper functionality, two actions are required: +- **Install NGINX:** Ensure the NGINX is installed on the system. +- **Connect to the NGINX One Console:** Establish a connection between the installed NGINX instance and the NGINX One Console." + + +## Connect to NGINX One Console +For a quick guide on how to connect to NGINX One Console see: [Connect to NGINX One Console]({{< relref "/nginx-one/how-to/nginx-configs/add-instance" >}}) + +### Manual Connect +1. Ensure the F5 NGINX Agent is installed +1. Locate the F5 NGINX Agent Configuration File: + ```bash + /etc/nginx-agent/nginx-agent.conf + ``` +1. Open the NGINX Agent configuration file in a text editor like vim: +`sudo vim /etc/nginx-agent/nginx-agent.conf` +1. Uncomment the command block, and set the token to your data plane key +1. Save the changes and close the editor +1. Restart the F5 NGINX Agent service: + ```bash + sudo systemctl stop nginx-agent + ``` + +## Manual Installations ### Configure NGINX OSS Repository for installing NGINX Agent Before you install NGINX Agent for the first time on your system, you need to set up the `nginx-agent` packages repository. Afterward, you can install and update NGINX Agent from the repository. @@ -318,19 +336,6 @@ Before you install NGINX Agent for the first time on your system, you need to se sudo pkg install nginx-agent ``` -## NGINX Plus repository - -Before you install NGINX Agent, you must install and run NGINX Plus. - -If you don’t have it installed already, read the [Installing NGINX Plus -](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) topic. - -You will also need the following: - -- Your credentials to the MyF5 Customer Portal, provided by email from F5, Inc. -- An NGINX Plus subscription (Full or trial) -- Your NGINX Plus certificate and public key (`nginx-repo.crt` and `nginx-repo.key` files), provided by email from F5, Inc. - ### Configure NGINX Plus Repository for installing NGINX Agent Before you install NGINX Agent for the first time on your system, you need to set up the `nginx-agent` packages repository. Afterward, you can install and update NGINX Agent from the repository. @@ -755,7 +760,7 @@ Use your system's package manager to install the package. Some examples: sudo pkg add nginx-agent-.pkg ``` -## systemd environments +## Starting, Stopping, and Enabling NGINX Agent To start NGINX Agent on `systemd` systems, run the following command: @@ -769,16 +774,21 @@ To enable NGINX Agent to start on boot, run the following command: sudo systemctl enable nginx-agent ``` +To stop NGINX Agent, run the following command: + +```shell +sudo systemctl stop nginx-agent +``` + ## Verify that NGINX Agent is running Once you have installed NGINX Agent, you can verify that it is running with the following command: ```shell -sudo nginx-agent -v +sudo systemctl status nginx-agent ``` -## Enable interfaces - -Once NGINX Agent is successfully running, you can enable the required interfaces, which is described in the [Enable gRPC and REST interfaces]({{< relref "/agent/how-to/enable-interfaces.md" >}}) topic. - -You may also be interested in the [Start mock control plane interface]({{< relref "/agent/contribute/start-mock-interface.md" >}}) topic for development work. \ No newline at end of file +To check the version installed, run the following command: +```shell +sudo nginx-agent -v +``` \ No newline at end of file diff --git a/content/agent/install-upgrade/migrate-v3.md b/content/agent/install-upgrade/migrate-v3.md index 32811a075..8e557f368 100644 --- a/content/agent/install-upgrade/migrate-v3.md +++ b/content/agent/install-upgrade/migrate-v3.md @@ -6,39 +6,41 @@ docs: DOCS-000 This topic describes how to migrate from F5 NGINX Agent v2 to NGINX Agent v3. -[//]: # "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" >}}). -- -- +- A [working NGINX Agent instance]({{< ref "/agent/install-upgrade/install.md" >}}). +- An NGINX Agent connected to NGINX One. For a quick guide on how to connect to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance.md" >}}) --- ## Migrate from NGINX Agent v2 to v3 +The migration from NGINX Agent v2 to v3 is handled automatically by the package manager on your OS during the installation of NGINX Agent v3. + +To install NGINX Agent v3 see [Install NGINX Agent]({{< ref "/agent/install-upgrade/install.md" >}}) + +To migrate NGINX Agent containers, we provide a script to convert NGINX Agent v2 config files to NGINX Agent v3 config files: [NGINX Agent Config Upgrade Script](https://github.com/nginx/agent/blob/v3/scripts/packages/upgrade-agent-config.sh) + +To upgrade the configuration, you can follow this example: + +```shell +wget https://github.com/nginx/agent/blob/v3/scripts/packages/upgrade-agent-config.sh +./upgrade-agent-config.sh --v2-config-file=./nginx-agent-v2.conf --v3-config-file=nginx-agent-v3.conf +``` + +If your NGINX Agent container was previously a member of a config sync group, then your NGINX Agent config must be manually updated to add the config sync group label. +See [Add Config Sync Group]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}}) for more information. --- -## See also +## Rolling back from NGINX Agent v3 to v2 -[//]: # "Examples of additional topics users might want to read include:" -[//]: # "Relevant reference information, configuration options and more complex use cases." +If you need to roll back your environment to NGINX Agent v2, the upgrade process creates a backup of the NGINX Agent v2 config in the file `/etc/nginx-agent/nginx-agent-v2-backup.conf`. -- -- +Replace the conents of `/etc/nginx-agent/nginx-agent.conf` with the contents of `/etc/nginx-agent/nginx-agent-v2-backup.conf` and then reinstall an older version of NGINX Agent. \ No newline at end of file diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md new file mode 100644 index 000000000..cac034103 --- /dev/null +++ b/content/agent/otel/configure-otel-metrics.md @@ -0,0 +1,229 @@ +--- +title: Metrics Export +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: + +* 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. + +# 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 + +Before you begin configuring the F5 NGINX Agent OTel Collector: + +- [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 + + +## Configure the OTel Collector - Virtual Machine + +1. Locate the configuration file for the F5 NGINX Agent: + + ```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 diff --git a/content/agent/technical-specifications.md b/content/agent/technical-specifications.md index f11a5cde4..5bcd11efc 100644 --- a/content/agent/technical-specifications.md +++ b/content/agent/technical-specifications.md @@ -1,60 +1,73 @@ --- -title: "Technical specifications" +title: "Technical Specifications" toc: true -weight: 200 +weight: 700 docs: DOCS-000 --- ## Overview -This document provides technical specifications for F5 NGINX Agent. It includes information on supported distributions, deployment environments, NGINX versions, sizing recommendations, and logging. +This document outlines the technical specifications for the F5 NGINX Agent, including details on supported operating systems, deployment environments, compatible NGINX versions, minimum system sizing requirements, and logging considerations. -## Supported distributions +--- -NGINX Agent can run in most environments. We support the following distributions: +## Supported Distributions -{{< bootstrap-table "table table-striped table-bordered" >}} -| | AlmaLinux | Alpine Linux | Amazon Linux | Amazon Linux 2 | CentOS | Debian | -|-|-----------|--------------|--------------|----------------|--------|--------| -|**Version**|8
9 | 3.16
3.17
3.18
3.19| 2023| LTS| 7.4+| 11
12| -|**Architecture**| x86_84
aarch64| x86_64
aarch64 | x86_64
aarch64 | x86_64
aarch64 | x86_64
aarch64 | x86_64
aarch64 | -{{< /bootstrap-table >}} +The NGINX Agent is versatile and can operate across various environments. Currently, the following distributions are supported: -{{< bootstrap-table "table table-striped table-bordered" >}} -| |FreeBSD | Oracle Linux | Red Hat
Enterprise Linux
(RHEL) | Rocky Linux | SUSE Linux
Enterprise Server
(SLES) | Ubuntu | -|-|--------|--------------|---------------------------------|-------------|-------------------------------------|--------| -|**Version**|13
14|7.4+
8.1+
9|7.4+
8.1+
9.0+|8
9|12 SP5
15 SP2|20.04 LTS
22.04 LTS| -|**Architecture**|amd64|x86_64|x86_64
aarch64|x86_64
aarch64|x86_64|x86_64
aarch64| -{{< /bootstrap-table >}} +| Distribution | Supported Versions | Architectures | +|------------------------------------|---------------------------------------|---------------------| +| **AlmaLinux** | 8, 9 | x86_64, aarch64 | +| **Alpine Linux** | 3.16, 3.17, 3.18, 3.19 | x86_64, aarch64 | +| **Amazon Linux** | 2023 | x86_64, aarch64 | +| **Amazon Linux 2** | LTS | x86_64, aarch64 | +| **CentOS** | 7.4+ | x86_64, aarch64 | +| **Debian** | 11, 12 | x86_64, aarch64 | +| **Oracle Linux** | 7.4+, 8.1+, 9 | x86_64 | +| **Red Hat Enterprise Linux (RHEL)**| 7.4+, 8.1+, 9.0+ | x86_64, aarch64 | +| **Rocky Linux** | 8, 9 | x86_64, aarch64 | +| **SUSE Linux Enterprise Server (SLES)** | 12 SP5, 15 SP2 | x86_64 | +| **Ubuntu** | 20.04 LTS, 22.04 LTS | x86_64, aarch64 | +--- -## Supported deployment environments +## Supported Deployment Environments -NGINX Agent can be deployed in the following environments: +The NGINX Agent supports deployment in the following environments: -- Bare Metal -- Container -- Public Cloud: AWS, Google Cloud Platform, and Microsoft Azure -- Virtual Machine +- **Bare Metal** machines +- **Containers** +- **Public Cloud** platforms, including AWS, Google Cloud Platform, and Microsoft Azure +- **Virtual Machines** -## Supported NGINX versions +--- -NGINX Agent works with all supported versions of NGINX Open Source and NGINX Plus. +## Supported NGINX Versions +The NGINX Agent is compatible with all supported releases of NGINX Open Source and NGINX Plus. + +--- -## Sizing recommendations +## Minimum System Requirements -Minimum system sizing recommendations for NGINX Agent: -{{< bootstrap-table "table table-striped table-bordered" >}} -| CPU | Memory | Network | Storage | -|------------|----------|-----------|---------| -| 1 CPU core | 1 GB RAM | 1 GbE NIC | 20 GB | -{{< /bootstrap-table >}} +Below are the recommended minimum system specifications for running the NGINX Agent: + +| **Resource** | **Minimum Requirement** | +|--------------|--------------------------| +| **CPU** | 1 CPU core | +| **Memory** | 1 GB RAM | +| **Network** | 1 GbE NIC | +| **Storage** | 20 GB | + +--- ## Logging -NGINX Agent utilizes log files and formats to collect metrics. Increasing the log formats and instance counts will result in increased log file sizes. +The NGINX Agent uses log files in standardized formats to collect metrics. As the number of log formats or instances grows, the size of these log files will increase correspondingly. + +To avoid system storage constraints caused by expanding log directories, it is recommended to: -To prevent system storage issues due to a growing log directory, it is recommended to add a separate partition for `/var/log/nginx-agent` and enable [log rotation](http://nginx.org/en/docs/control.html#logs). +- Set up a **dedicated partition** for `/var/log/nginx-agent`. +- Enable **[log rotation](https://linux.die.net/man/8/logrotate)** to manage log file growth effectively. -More information is available in the [Configuration overview]({{< relref "/agent/how-to/configuration-overview.md#logs" >}}) \ No newline at end of file +For additional details on managing logs, refer to the [Configuration Overview]({{< relref "/agent/how-to/configuration-overview.md#logs" >}}). \ No newline at end of file diff --git a/content/agent/troubleshooting.md b/content/agent/troubleshooting.md new file mode 100644 index 000000000..cd2c1ceef --- /dev/null +++ b/content/agent/troubleshooting.md @@ -0,0 +1,30 @@ +--- +title: Troubleshooting +toc: true +weight: 700 +docs: DOCS-000 +--- + +## F5 NGINX Agent Troubleshooting + +**1. Container running but Agent is not connected to NGINX One Console?** +- Check Agent logs ```bash + docker logs + ``` +- If you are using NGINX Plus, a valid license will need to be passed into the container run command. +- Ensure that the values sent with the container run command are correct. + +**2. Container running but instance is showing offline on NGINX One Console?** +- Check Agent logs ```bash + docker logs c5e1e3234900 | grep "nginx" + ``` +- Verify the following log message is shown: ```2025/02/17 19:02:58 [notice] 32#32: nginx/1.27.2 (nginx-plus-r33-p2 ``` +- If not found, it could mean the container image is missing the NGINX service +- Make sure NGINX is running ```ps -ef | grep "nginx"``` +- Make sure NGINX is part of the image file. + + +**3. NGINX Agent is installed on my Virtual Machine, but not showing up on NGINX One Console?** +- Verify the agent is running ```sudo systemctl status nginx-agent``` +- Check for any errors in the logs ```sudo tail -f /var/log/nginx-agent/agent.log``` +- Check ```/etc/nginx-agent/nginx-agent.conf``` for any misconfigurations. diff --git a/go.mod b/go.mod index 36306b1cd..96da5bb32 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.41.27 // indirect +require github.com/nginxinc/nginx-hugo-theme v0.42.24 // indirect diff --git a/go.sum b/go.sum index 81af599e2..55949eecc 100644 --- a/go.sum +++ b/go.sum @@ -2,3 +2,5 @@ github.com/nginxinc/nginx-hugo-theme v0.41.22 h1:Gb/OLbpumNqp8vOPkZzO2GmgPDRd1yr github.com/nginxinc/nginx-hugo-theme v0.41.22/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= github.com/nginxinc/nginx-hugo-theme v0.41.27 h1:M8ttO1ZkTGY06o0MYvnm3kc/sA6lOmIjVA3tF3cAses= 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=