From c9615a44eef41ce28a331d53a49c9421358ac38b Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney Date: Thu, 11 Dec 2025 12:10:24 +0000 Subject: [PATCH 1/3] docs: Update the NGINX Agent upgrade page --- .../agent/installation/update-container.md | 6 -- content/includes/agent/installation/update.md | 99 ++++++++++++++++++- 2 files changed, 95 insertions(+), 10 deletions(-) diff --git a/content/includes/agent/installation/update-container.md b/content/includes/agent/installation/update-container.md index 4266bfb63..a8f1b42ef 100644 --- a/content/includes/agent/installation/update-container.md +++ b/content/includes/agent/installation/update-container.md @@ -15,9 +15,3 @@ wget https://raw.githubusercontent.com/nginx/agent/refs/heads/main/scripts/packa 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-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}) for more information. - -### Rolling back from NGINX Agent v3 to v2 - -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 contents 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. diff --git a/content/includes/agent/installation/update.md b/content/includes/agent/installation/update.md index 4814a9eae..3572b93ac 100644 --- a/content/includes/agent/installation/update.md +++ b/content/includes/agent/installation/update.md @@ -4,7 +4,25 @@ nd-files: - content/nginx-one-console/agent/install-upgrade/update.md --- -{{< call-out "note" >}} If you are using a version **older than NGINX Agent v2.31.0**, you must stop NGINX Agent before updating: + +The following is a summary of changes and improvements that went into NGINX Agent v3. + +- Enhanced connection handling with improved error management and retry logic. +- Improved reliability when publishing NGINX configurations to NGINX Data planes. +- Revamped logging framework for easier troubleshooting and diagnostics. +- Improved NGINX Data plane health monitoring. +- Agent Configuration file has been simplified. +- Built-in OpenTelemetry (OTel) support for standardized observability and monitoring. +[Learn more about exporting metrics to NGINX One Console]({{< ref "/nginx-one-console/agent/configure-otel-metrics/" >}}) +- Explicit forward proxy support. +- Enable Kubernetes control planes connections NGINX One Console + +## Upgrading the Agent on Virtual Machine/Bare Metal Server + +When upgrading to NGINX Agent v3, the installer automatically backs up all configuration files before proceeding. It also converts your v2 configuration to the v3 format, ensuring compatibility and preserving settings. + +{{< call-out "note" >}} +If you are using a version **older than NGINX Agent v2.31.0**, you must stop NGINX Agent before updating: - `sudo systemctl stop nginx-agent` @@ -20,9 +38,9 @@ The same steps apply if you are **upgrading from NGINX Agent v2 to NGINX Agent v 1. Make a backup copy of the following locations to ensure that you can successfully recover if the upgrade does not complete successfully: - - - `/etc/nginx-agent` - - Every configuration directory specfied in `/etc/nginx-agent/nginx-agent.conf` as a `config_dirs` value + ```shell + sudo cp -r /etc/nginx-agent /etc/nginx-agent.bak + ``` 1. Install the updated version of NGINX Agent: @@ -39,3 +57,76 @@ The same steps apply if you are **upgrading from NGINX Agent v2 to NGINX Agent v sudo apt-get update sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold" ``` +1. Verify the installation by checking the version: + ```shell + sudo nginx-agent -v + ``` +1. Verify the agent service is running by checking the logs + + ```shell + sudo cat /var/log/nginx-agent/agent.log | grep -i "Starting NGINX Agent" + ``` + +### Rolling back from NGINX Agent v3 to v2 + +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.conf.v2-backup`. + +Replace the contents of `/etc/nginx-agent/nginx-agent.conf` with the contents of `/etc/nginx-agent/nginx-agent.conf.v2-backup` and then reinstall an older version of NGINX Agent. + + +## Upgrading Container and Kubernetes deployments + +{{< call-out "warning" >}} NGINX Agent v3 introduces a new configuration schema that replaces all v2 environment variables. The names, structure, and sometimes the semantics of these variables have changed. There is no backward compatibility, so any automation or manifests using v2 variables must be updated to the new v3 equivalents before upgrading. + +{{< /call-out >}} + +### Recommended Approach + +Start by reviewing the configuration in the yaml file, this example shows a subset of the v2 env vars. +To the complete v2 and v3 list use the following links: + +- [Full list of v2 environment variables]({{< ref "/agent/configuration/configuration-overview" >}}) +- [Full list of v3 environment variables]({{< ref "/nginx-one-console/agent/configure-instances/configuration-overview/" >}}) + + +Taking an example docker-compose file running a NGINX Agent v2 and update to v3. + +```yaml + # NGINX Agent v2 + nginx-agent: + image: private-registry.nginx.com/nginx-plus/agent:debian + container_name: nginx-agent + environment: + NGINX_LICENSE_JWT: + NGINX_AGENT_SERVER_GRPCPORT: 443 + NGINX_AGENT_SERVER_HOST: + NGINX_AGENT_SERVER_TOKEN: + NGINX_AGENT_TLS_ENABLE: true +``` + + +1. Update the image to point to NGINX Agent v3 + +1. Replace the v2 envioronment variables with v3 + +1. Start the updated services: + ```shell + docker-compose up -d + ``` +```yaml + # NGINX Agent v3 + nginx-agent: + image: private-registry.nginx.com/nginx-plus/agentv3:debian + container_name: nginx-agent + environment: + NGINX_LICENSE_JWT: + NGINX_AGENT_COMMAND_SERVER_PORT: 443 + NGINX_AGENT_COMMAND_SERVER_HOST: + NGINX_AGENT_COMMAND_AUTH_TOKEN: + NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY: false +``` + +1. Testing +- Verify the container is running +- Check agent logs to confirm the upgrade: `"Starting NGINX Agent" version=v3` +- Verify the container is showing on NGINX Console view From 4d2070a21025c69b983615ffa53c0721951272c6 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney Date: Thu, 11 Dec 2025 12:15:18 +0000 Subject: [PATCH 2/3] docs: updates --- content/includes/agent/installation/update.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/includes/agent/installation/update.md b/content/includes/agent/installation/update.md index 3572b93ac..6ae9c0deb 100644 --- a/content/includes/agent/installation/update.md +++ b/content/includes/agent/installation/update.md @@ -11,7 +11,7 @@ The following is a summary of changes and improvements that went into NGINX Agen - Improved reliability when publishing NGINX configurations to NGINX Data planes. - Revamped logging framework for easier troubleshooting and diagnostics. - Improved NGINX Data plane health monitoring. -- Agent Configuration file has been simplified. +- Simplified Agent Configuration file. - Built-in OpenTelemetry (OTel) support for standardized observability and monitoring. [Learn more about exporting metrics to NGINX One Console]({{< ref "/nginx-one-console/agent/configure-otel-metrics/" >}}) - Explicit forward proxy support. @@ -126,7 +126,7 @@ Taking an example docker-compose file running a NGINX Agent v2 and update to v3. NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY: false ``` -1. Testing -- Verify the container is running +4. Testing +- Verify the container is running - Check agent logs to confirm the upgrade: `"Starting NGINX Agent" version=v3` -- Verify the container is showing on NGINX Console view +- Verify NGINX instance is displayed as online NGINX Console instances view From d7f3055871566ac5c889c9aeb82162de672d410b Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Thu, 11 Dec 2025 13:04:37 +0000 Subject: [PATCH 3/3] PR feedback Co-authored-by: Daniel Edgar --- content/includes/agent/installation/update.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/includes/agent/installation/update.md b/content/includes/agent/installation/update.md index 6ae9c0deb..b64729d3e 100644 --- a/content/includes/agent/installation/update.md +++ b/content/includes/agent/installation/update.md @@ -83,7 +83,7 @@ Replace the contents of `/etc/nginx-agent/nginx-agent.conf` with the contents of ### Recommended Approach Start by reviewing the configuration in the yaml file, this example shows a subset of the v2 env vars. -To the complete v2 and v3 list use the following links: +To see the complete v2 and v3 lists use the following links: - [Full list of v2 environment variables]({{< ref "/agent/configuration/configuration-overview" >}}) - [Full list of v3 environment variables]({{< ref "/nginx-one-console/agent/configure-instances/configuration-overview/" >}})