From 3fcf9ac4973812192576d3c270ac51df33962caf Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney Date: Thu, 9 Apr 2026 14:57:56 +0100 Subject: [PATCH 01/17] Add v2 to v3 migration guide --- .../agent/install-upgrade/update.md | 20 -- .../agent/install-upgrade/upgrade-v2-v3.md | 218 ++++++++++++++++++ go.sum | 3 +- 3 files changed, 220 insertions(+), 21 deletions(-) create mode 100644 content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md diff --git a/content/nginx-one-console/agent/install-upgrade/update.md b/content/nginx-one-console/agent/install-upgrade/update.md index a43ae085e6..e23d780383 100644 --- a/content/nginx-one-console/agent/install-upgrade/update.md +++ b/content/nginx-one-console/agent/install-upgrade/update.md @@ -11,23 +11,3 @@ nd-product: NAGENT {{< include "/agent/installation/update.md" >}} -## Migrate NGINX Agent running in containers - -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://raw.githubusercontent.com/nginx/agent/refs/heads/main/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-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/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md b/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md new file mode 100644 index 0000000000..dc7c315f08 --- /dev/null +++ b/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md @@ -0,0 +1,218 @@ +--- +title: Migrate NGINX Agent v2 to v3 +weight: 600 +toc: true +nd-docs: DOCS-1227 +nd-content-type: how-to +nd-product: NAGENT +--- + +This guide explains how to migrate deployments from **NGINX Agent v2** to **NGINX agent v3**. Agent v3 introduces architectural and configuration changes. As a result, migrating from v2 to v3 should be approached as a controlled migration. + +{{< call-out class="warning" title="Breaking Changes in NGINX Agent v3 Migration" >}} + +The migration from Agent v2 to Agent v3 introduces critical changes that may disrupt existing workflows: + +### **Changed Configuration Structure** + +- **Environment Variables**: + - Agent v3 replaces Agent v2 environment variables for GRPC connectivity: + - `NGINX_AGENT_SERVER_HOST` -> `NGINX_AGENT_COMMAND_SERVER_HOST` + - `NGINX_AGENT_SERVER_GRPCPORT` -> `NGINX_AGENT_COMMAND_SERVER_PORT` + - `NGINX_AGENT_SERVER_TOKEN` -> `NGINX_AGENT_COMMAND_AUTH_TOKEN` + - Ensure the new variables are correctly updated in Agent v3 configuration before deployment. + +- **Config Sync Groups** + - In v3 config sync groups are defined using the following format: + ```yaml + - name: NGINX_AGENT_LABELS + value: "config-sync-group=" + ``` + {{< /call-out >}} + +## Migrate NGINX Agent running using Virtual Machines +{{< include "/agent/installation/update.md" >}} + + + +## Migrate NGINX Agent running in Kubernetes + +{{< call-out class="info">}} +Docker images are available in the [Deploying NGINX and NGINX Plus on Docker](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-docker/) NGINX documentation. + {{< /call-out >}} + +- Prepare NGINX Agent v3 Deployment YAML, for example: + ```yaml + containers: + - name: nginx-agent + image: /nginx-plus/agent/debian:r36 + env: + - name: NGINX_AGENT_COMMAND_SERVER_HOST + value: "agent.connect.nginx.com" + - name: NGINX_AGENT_COMMAND_SERVER_PORT + value: "443" + - name: NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY + value: "false" + - name: NGINX_AGENT_COMMAND_AUTH_TOKEN + value: "" + - name: NGINX_LICENSE_JWT + valueFrom: + secretKeyRef: + name: nginx-secret + key: NGINX_LICENSE_JWT + ``` +- Deploy the Updated Manifest, Apply the Deployment using kubectl: + ```shell + kubectl apply -f nginx-agent-v3-deployment.yaml + ``` +- Monitor the Rollout Progress +kubectl rollout status deployment/ -n nginxone + +- Validate the Replacement +Once the rollout is complete, ensure all v2 pods have been replaced with v3 pods: + +- Confirm all pods transistion to running: + ```shell + kubectl get pods -n + ``` + +### Post-Migration Validations + +1. Check for agent connected message, example: **msg="Agent connected"** + ```shell + kubectl logs -n + ``` +2. Search for the Instance on NGINX One Console + +1. **Open the Instances View**: + - Navigate to the **Instances View** in the NGINX One Console. + +2. **Search for the NGINX Instance**: + - Enter the **Pod Name** in the search field located in the top-right corner of the Instances View. + +3. **Check Instance Availability Status**: + - Ensure the **Availability** status of the instance shows **Online**. + +4. **Check Config Sync Group (If Applicable)**: + - If your instance is part of a **Config Sync Group**: + - Open the **Config Sync Groups** section. + - Locate your specific **Config Sync Group**. + - Verify that instances listed in the group are also shown as **Online** in the **Instances Section**. + + +### Troubleshooting + +If issues arise during migration, follow these steps: + +1. Check for any errors in the logs: + ```shell + kubectl logs -n + ``` +2. Environment Variables: +Inspect the pod to confirm all environment variables are correctly set: + ```shell + kubectl describe pod -n + ``` +3. Rollback to NGINX Agent v2 + ```shell + kubectl apply -f nginx-agent-v2-deployment.yaml + ``` + +## Migrate NGINX Agent running using docker compose + +#### v2 Docker Compose Configuration + +```yaml + version: "3.8" + services: + nginx-agent: + image: /nginx-agent:v2 + environment: + - NGINX_AGENT_SERVER_HOST=agent.connect.nginx.com + - NGINX_AGENT_SERVER_GRPCPORT=50051 + - NGINX_AGENT_SERVER_TOKEN= + - NGINX_LICENSE_JWT=${NGINX_LICENSE_JWT} + secrets: + - nginx_license_jwt + + secrets: + nginx_license_jwt: + file: ./nginx_license_jwt.txt +``` + +#### v3 Docker Compose Configuration + +```yaml +version: "3.8" +services: + nginx-agent: + image: /nginx-plus/agent/debian:r36 + environment: + - NGINX_AGENT_COMMAND_SERVER_HOST=agent.connect.nginx.com + - NGINX_AGENT_COMMAND_SERVER_PORT=443 + - NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY=false + - NGINX_AGENT_COMMAND_AUTH_TOKEN= + - NGINX_LICENSE_JWT=${NGINX_LICENSE_JWT} + - NGINX_AGENT_LABELS=config-sync-group= + secrets: + - nginx_license_jwt + +secrets: + nginx_license_jwt: + file: ./nginx_license_jwt.txt +``` + +### Migration Steps for Docker Compose +1. Backup Your Existing Configuration + - Save a copy of your current docker-compose.yaml file to ensure you can roll back if necessary. + +2. Modify the Configuration + - Update your service configuration as shown in the v3 Docker Compose Configuration. + +3. Restart the Agent Service + - Bring down the existing agent running with v2: + ```bash + docker-compose down + ``` + - Start the agent with the updated v3 configuration: + ```bash + docker-compose up -d + ``` +4. Validate the Migration + - Confirm the agent is running with the v3 changes: + ```bash + docker logs + ``` + - Check the logs for successful connection messages: + ```msg="Agent connected"``` + + 5. Check in NGINX One Console + - Ensure the updated instance is listed and active in the Instances View. + - If the agent belongs to a Config Sync Group, verify that it is displayed as Online under the Config Sync Groups section. + +## Rollback Procedure + +If any issues occur, you can roll back to v2 by replacing the configuration with the v2 docker-compose.yaml and restarting the service: + ```bash + $ docker-compose down + $ docker-compose up -d + ``` +## Migrate NGINX Agent running in containers + +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://raw.githubusercontent.com/nginx/agent/refs/heads/main/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-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}) for more information. + +### Rollback Procedure + +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. \ No newline at end of file diff --git a/go.sum b/go.sum index 8b586e7df6..90072b6f6b 100644 --- a/go.sum +++ b/go.sum @@ -1,2 +1,3 @@ +github.com/nginxinc/nginx-hugo-theme/v2 v2.0.5/go.mod h1:TAmEMc0T/RKTQ0pI4LROWoUmyLXstrRmM2jE2ErdxWY= github.com/nginxinc/nginx-hugo-theme/v2 v2.0.7 h1:p00vkLFPgg7tEHt2ZJIg6jjxo8evJf9fYzWzkI3brrM= -github.com/nginxinc/nginx-hugo-theme/v2 v2.0.7/go.mod h1:TAmEMc0T/RKTQ0pI4LROWoUmyLXstrRmM2jE2ErdxWY= \ No newline at end of file +github.com/nginxinc/nginx-hugo-theme/v2 v2.0.7/go.mod h1:TAmEMc0T/RKTQ0pI4LROWoUmyLXstrRmM2jE2ErdxWY= From 1188708a743f30df1864b2d193464adf414ea9d8 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney Date: Mon, 13 Apr 2026 16:10:14 +0100 Subject: [PATCH 02/17] Improve instructions when running with a mounted file --- .../agent/install-upgrade/upgrade-v2-v3.md | 88 ++++++++++--------- 1 file changed, 48 insertions(+), 40 deletions(-) diff --git a/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md b/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md index dc7c315f08..f61b703f9b 100644 --- a/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md +++ b/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md @@ -13,10 +13,8 @@ This guide explains how to migrate deployments from **NGINX Agent v2** to **NGIN The migration from Agent v2 to Agent v3 introduces critical changes that may disrupt existing workflows: -### **Changed Configuration Structure** - - **Environment Variables**: - - Agent v3 replaces Agent v2 environment variables for GRPC connectivity: + - Environment variables renamed (v2 → v3): - `NGINX_AGENT_SERVER_HOST` -> `NGINX_AGENT_COMMAND_SERVER_HOST` - `NGINX_AGENT_SERVER_GRPCPORT` -> `NGINX_AGENT_COMMAND_SERVER_PORT` - `NGINX_AGENT_SERVER_TOKEN` -> `NGINX_AGENT_COMMAND_AUTH_TOKEN` @@ -63,17 +61,19 @@ Docker images are available in the [Deploying NGINX and NGINX Plus on Docker](ht ``` - Deploy the Updated Manifest, Apply the Deployment using kubectl: ```shell - kubectl apply -f nginx-agent-v3-deployment.yaml + kubectl apply -n -f nginx-agent-v3-deployment.yaml ``` - Monitor the Rollout Progress -kubectl rollout status deployment/ -n nginxone + ```shell + kubectl rollout status deployment/ -n + ``` - Validate the Replacement Once the rollout is complete, ensure all v2 pods have been replaced with v3 pods: - Confirm all pods transistion to running: ```shell - kubectl get pods -n + kubectl get pods -n ``` ### Post-Migration Validations @@ -123,21 +123,16 @@ Inspect the pod to confirm all environment variables are correctly set: #### v2 Docker Compose Configuration ```yaml - version: "3.8" - services: - nginx-agent: - image: /nginx-agent:v2 - environment: - - NGINX_AGENT_SERVER_HOST=agent.connect.nginx.com - - NGINX_AGENT_SERVER_GRPCPORT=50051 - - NGINX_AGENT_SERVER_TOKEN= - - NGINX_LICENSE_JWT=${NGINX_LICENSE_JWT} - secrets: - - nginx_license_jwt - - secrets: - nginx_license_jwt: - file: ./nginx_license_jwt.txt +version: "3.8" +services: +nginx-agent: + image: /nginx-agent:v2 + environment: + NGINX_AGENT_SERVER_HOST: agent.connect.nginx.com + NGINX_AGENT_SERVER_GRPCPORT: "443" + NGINX_AGENT_SERVER_TOKEN: ${NGINX_AGENT_SERVER_TOKEN} + NGINX_LICENSE_JWT: ${NGINX_LICENSE_JWT} + ``` #### v3 Docker Compose Configuration @@ -146,20 +141,14 @@ Inspect the pod to confirm all environment variables are correctly set: version: "3.8" services: nginx-agent: - image: /nginx-plus/agent/debian:r36 + image: /nginx-plus/agent/debian: environment: - - NGINX_AGENT_COMMAND_SERVER_HOST=agent.connect.nginx.com - - NGINX_AGENT_COMMAND_SERVER_PORT=443 - - NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY=false - - NGINX_AGENT_COMMAND_AUTH_TOKEN= - - NGINX_LICENSE_JWT=${NGINX_LICENSE_JWT} - - NGINX_AGENT_LABELS=config-sync-group= - secrets: - - nginx_license_jwt - -secrets: - nginx_license_jwt: - file: ./nginx_license_jwt.txt + NGINX_AGENT_COMMAND_SERVER_HOST: agent.connect.nginx.com + NGINX_AGENT_COMMAND_SERVER_PORT: "443" + NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY: "false" + NGINX_AGENT_COMMAND_AUTH_TOKEN: ${NGINX_AGENT_COMMAND_AUTH_TOKEN} + NGINX_LICENSE_JWT: ${NGINX_LICENSE_JWT} + NGINX_AGENT_LABELS: config-sync-group= ``` ### Migration Steps for Docker Compose @@ -198,18 +187,37 @@ If any issues occur, you can roll back to v2 by replacing the configuration with $ docker-compose up -d ``` ## Migrate NGINX Agent running in containers +1. Pull a docker image +```shell +sudo docker pull private-registry.nginx.com/nginx-plus/agentv3:debian +``` +2. Run the container +```shell +sudo docker run \ +--env=NGINX_LICENSE_JWT="YOUR_JWT_HERE" \ +--env=NGINX_AGENT_COMMAND_SERVER_PORT=443 \ +--env=NGINX_AGENT_COMMAND_SERVER_HOST=agent.connect.nginx.com \ +--env=NGINX_AGENT_COMMAND_AUTH_TOKEN="" \ +--env=NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY=false \ +--restart=always \ +--runtime=runc \ +-d private-registry.nginx.com/nginx-plus/agentv3:debian +``` -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: +Note: If you container is setup to run with a mounted configuration file use the following steps to convert to a v3 configuration file. +1. Download the conversion script (v3 branch): +```shell +wget https://raw.githubusercontent.com/nginx/agent/v3/scripts/packages/upgrade-agent-config.sh +chmod +x upgrade-agent-config.sh +``` +2. Run the script to conver the configuration file. ```shell -wget https://raw.githubusercontent.com/nginx/agent/refs/heads/main/scripts/packages/upgrade-agent-config.sh -./upgrade-agent-config.sh --v2-config-file=./nginx-agent-v2.conf --v3-config-file=nginx-agent-v3.conf +./upgrade-agent-config.sh --v2-config-file=./nginx-agent-v2.conf --v3-config-file=./nginx-agent-v3.conf ``` +If your v2 agent belonged to a Config Sync Group, manually add the Config Sync Group label to the v3 config. See “Add Config Sync Group” in your docs. -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. ### Rollback Procedure From ab21ecc404c4c534064a506d4a7e6d1c654eda5b Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney Date: Thu, 16 Apr 2026 09:27:39 +0100 Subject: [PATCH 03/17] Refactor the update page Add in a link to full list of v3 env vars --- .../agent/install-upgrade/update.md | 27 +++++++++++++++++-- .../agent/install-upgrade/upgrade-v2-v3.md | 1 + 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/content/nginx-one-console/agent/install-upgrade/update.md b/content/nginx-one-console/agent/install-upgrade/update.md index e23d780383..a24ba8ef09 100644 --- a/content/nginx-one-console/agent/install-upgrade/update.md +++ b/content/nginx-one-console/agent/install-upgrade/update.md @@ -1,5 +1,5 @@ --- -title: Upgrade NGINX Agent +title: Upgrade NGINX Agent v3 to a new version toc: true weight: 400 nd-content-type: how-to @@ -9,5 +9,28 @@ nd-product: NAGENT ## Overview -{{< include "/agent/installation/update.md" >}} +Follow the steps below to upgrade NGINX v3 Agent to the latest version. + +1. Open an SSH connection to the server where you've installed NGINX Agent. + +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 + +1. Install the updated version of NGINX Agent: + + - CentOS, RHEL, RPM-Based + + ```shell + sudo yum -y makecache + sudo yum update -y nginx-agent + ``` + + - Debian, Ubuntu, Deb-Based + + ```shell + sudo apt-get update + sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold" diff --git a/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md b/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md index f61b703f9b..4b75f19a34 100644 --- a/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md +++ b/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md @@ -19,6 +19,7 @@ The migration from Agent v2 to Agent v3 introduces critical changes that may dis - `NGINX_AGENT_SERVER_GRPCPORT` -> `NGINX_AGENT_COMMAND_SERVER_PORT` - `NGINX_AGENT_SERVER_TOKEN` -> `NGINX_AGENT_COMMAND_AUTH_TOKEN` - Ensure the new variables are correctly updated in Agent v3 configuration before deployment. + - [Complete list of Agent v3 environment variables](https://docs.nginx.com/nginx-one-console/agent/configure-instances/configuration-overview/) - **Config Sync Groups** - In v3 config sync groups are defined using the following format: From e6137aee46593956c993a9b1ada02b4caee42c05 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney Date: Thu, 16 Apr 2026 13:07:07 +0100 Subject: [PATCH 04/17] =?UTF-8?q?docs(agent):=20migrate=20v2=E2=86=92v3=20?= =?UTF-8?q?upgrade=20guide;=20update=20installation=20docs;=20add=20migrat?= =?UTF-8?q?ion/;=20remove=20deprecated=20upgrade-v2-v3.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/includes/agent/installation/update.md | 2 +- .../agent/install-upgrade/migration/_index.md | 10 + .../migration/breaking-changes-overview.md | 31 +++ .../migration/docker-compose.md | 64 +++++ .../migration/docker-standalone.md | 64 +++++ .../install-upgrade/migration/kubernetes.md | 96 ++++++++ .../agent/install-upgrade/migration/vm.md | 63 +++++ .../agent/install-upgrade/upgrade-v2-v3.md | 227 ------------------ 8 files changed, 329 insertions(+), 228 deletions(-) create mode 100644 content/nginx-one-console/agent/install-upgrade/migration/_index.md create mode 100644 content/nginx-one-console/agent/install-upgrade/migration/breaking-changes-overview.md create mode 100644 content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md create mode 100644 content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md create mode 100644 content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md create mode 100644 content/nginx-one-console/agent/install-upgrade/migration/vm.md delete mode 100644 content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md diff --git a/content/includes/agent/installation/update.md b/content/includes/agent/installation/update.md index 26656b3684..0619481c2f 100644 --- a/content/includes/agent/installation/update.md +++ b/content/includes/agent/installation/update.md @@ -23,7 +23,7 @@ The same steps apply if you are **upgrading from NGINX Agent v2 to NGINX Agent v successfully: - `/etc/nginx-agent` - - Every configuration directory specfied in `/etc/nginx-agent/nginx-agent.conf` as a `config_dirs` value + - Every configuration directory specified in `/etc/nginx-agent/nginx-agent.conf` as a `config_dirs` value 1. Install the updated version of NGINX Agent: diff --git a/content/nginx-one-console/agent/install-upgrade/migration/_index.md b/content/nginx-one-console/agent/install-upgrade/migration/_index.md new file mode 100644 index 0000000000..42ed44a463 --- /dev/null +++ b/content/nginx-one-console/agent/install-upgrade/migration/_index.md @@ -0,0 +1,10 @@ +--- +title: Migrate NGINX Agent v2 to v3 +weight: 590 +toc: true +nd-docs: DOCS-1227 +nd-content-type: how-to +nd-product: NAGENT +aliases: + - /nginx-one-console/agent/install-upgrade/upgrade-v2-v3/ +--- diff --git a/content/nginx-one-console/agent/install-upgrade/migration/breaking-changes-overview.md b/content/nginx-one-console/agent/install-upgrade/migration/breaking-changes-overview.md new file mode 100644 index 0000000000..e4980ab54a --- /dev/null +++ b/content/nginx-one-console/agent/install-upgrade/migration/breaking-changes-overview.md @@ -0,0 +1,31 @@ +--- +title: Breaking Changes +weight: 590 +toc: true +nd-docs: DOCS-1227 +nd-content-type: how-to +nd-product: NAGENT +aliases: + - /nginx-one-console/agent/install-upgrade/upgrade-v2-v3/ +--- + +Use this section to choose the environment‑specific guide for migrating from NGINX Agent v2 to NGINX Agent v3. + +{{< call-out class="warning" title="Breaking changes" >}} + +- Environment variables renamed (v2 → v3): + - NGINX_AGENT_SERVER_HOST → NGINX_AGENT_COMMAND_SERVER_HOST + - NGINX_AGENT_SERVER_GRPCPORT → NGINX_AGENT_COMMAND_SERVER_PORT + - NGINX_AGENT_SERVER_TOKEN → NGINX_AGENT_COMMAND_AUTH_TOKEN + - Ensure the new variables are set correctly before deployment. + - [Complete list of Agent v3 environment variables:]({{< ref "/nginx-one-console/agent/configure-instances/configuration-overview/" >}}) + + +- Config Sync Groups: + - In v3, apply the label using: NGINX_AGENT_LABELS: config-sync-group= +{{< /call-out >}} + +{{< call-out class="caution" title="Plan and test your migration" >}} +Do not run v2 and v3 concurrently on the same host, pod, or container. Test in a non‑production environment first and schedule a maintenance window for production. +{{< /call-out >}} + diff --git a/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md b/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md new file mode 100644 index 0000000000..56cdc1a023 --- /dev/null +++ b/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md @@ -0,0 +1,64 @@ +--- +title: Migrate NGINX Agent v2 to v3 with Docker Compose +toc: true +weight: 120 +nd-content-type: how-to +nd-product: NAGENT +--- + +## Before you begin + +- Ensure you have: + - docker compose installed + - Registry credentials (if required) + - `NGINX_LICENSE_JWT` and the NGINX Agent command auth token (data plane key) +- Back up your existing docker-compose.yaml. +- Plan a maintenance window and test this procedure in a non‑production environment first. + +{{< call-out class="caution" title="Do not run v2 and v3 concurrently" >}} +Do not run NGINX Agent v2 and v3 concurrently in the same container or on the same host. +{{< /call-out >}} + +## Steps + +1. Update your compose file to use the v3 image and environment variables. Example: + ```yaml + version: "3.8" + services: + nginx-agent: + image: /nginx-plus/agent/debian: + environment: + NGINX_AGENT_COMMAND_SERVER_HOST: agent.connect.nginx.com + NGINX_AGENT_COMMAND_SERVER_PORT: "443" + NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY: "false" + NGINX_AGENT_COMMAND_AUTH_TOKEN: ${NGINX_AGENT_COMMAND_AUTH_TOKEN} + NGINX_LICENSE_JWT: ${NGINX_LICENSE_JWT} + # Optional: If using Config Sync Groups + # NGINX_AGENT_LABELS: config-sync-group= + ``` + +2. Restart the service: + ```shell + docker compose down + docker compose up -d + ``` + +3. Validate the migration: + ```shell + docker logs + ``` + - Look for: msg="Agent connected" + - Verify the instance is Online in the NGINX One Console. + +## Rollback + +- Restore the previous docker-compose.yaml and run: + ```shell + docker compose down && docker compose up -d + ``` + +## References + +- [Agent v3 environment variables:]({{< ref "/nginx-one-console/agent/configure-instances/configuration-overview/" >}}) +- [Docker images:]({{< ref "https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-docker/" >}}) +- Config conversion script: https://raw.githubusercontent.com/nginx/agent/v3/scripts/packages/upgrade-agent-config.sh \ No newline at end of file diff --git a/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md b/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md new file mode 100644 index 0000000000..d101908a74 --- /dev/null +++ b/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md @@ -0,0 +1,64 @@ +--- +title: Migrate NGINX Agent v2 to v3 in a Docker container +toc: true +weight: 130 +nd-content-type: how-to +nd-product: NAGENT +--- + +## Before you begin + +- Registry access for agent v3 images. +- NGINX_LICENSE_JWT and the NGINX Agent command auth token (data plane key). +- Plan a maintenance window and test this procedure in a non‑production environment first. + +{{< call-out class="caution" title="Do not run v2 and v3 concurrently" >}} +Do not run NGINX Agent v2 and v3 concurrently in the same container or on the same host. +{{< /call-out >}} + +## Steps + +1. Pull the v3 image: + ```shell + docker pull /nginx-plus/agentv3:debian + ``` + +2. Run the container: + ```shell + docker run -d \ + --restart=always \ + -e NGINX_LICENSE_JWT="" \ + -e NGINX_AGENT_COMMAND_SERVER_HOST=agent.connect.nginx.com \ + -e NGINX_AGENT_COMMAND_SERVER_PORT=443 \ + -e NGINX_AGENT_COMMAND_AUTH_TOKEN="" \ + -e NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY=false \ + /nginx-plus/agentv3:debian + ``` + +3. (Optional) Convert a mounted v2 config file to v3: + ```shell + wget https://raw.githubusercontent.com/nginx/agent/v3/scripts/packages/upgrade-agent-config.sh + chmod +x upgrade-agent-config.sh + ./upgrade-agent-config.sh --v2-config-file=./nginx-agent-v2.conf --v3-config-file=./nginx-agent-v3.conf + ``` + - If you used Config Sync Groups in v2, add to the v3 config: + - NGINX_AGENT_LABELS=config-sync-group= + +## Validate + +- Check logs for a successful connection message: + ```shell + docker logs + ``` + - Look for: msg="Agent connected" +- Verify the instance is Online in the NGINX One Console. + +## Rollback + +- Stop/remove the v3 container and run the previous v2 image. + +## References + +- [Agent v3 environment variables:]({{< ref "/nginx-one-console/agent/configure-instances/configuration-overview/" >}}) +- [Docker images:]({{< ref "https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-docker/" >}}) +- Config conversion script: https://raw.githubusercontent.com/nginx/agent/v3/scripts/packages/upgrade-agent-config.sh \ No newline at end of file diff --git a/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md b/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md new file mode 100644 index 0000000000..a14b777c64 --- /dev/null +++ b/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md @@ -0,0 +1,96 @@ +--- +title: Migrate NGINX Agent v2 to v3 on Kubernetes +toc: true +weight: 110 +nd-content-type: how-to +nd-product: NAGENT +--- + +## Before you begin + +- kubectl context is set to the target cluster and namespace. +- You have permissions to deploy to the namespace. +- Registry credentials are available if required. +- A Secret exists for NGINX_LICENSE_JWT or you can create one. +- Plan a maintenance window and test in a non‑production environment first. + +{{< call-out class="caution" title="Do not run v2 and v3 concurrently" >}} +Do not run NGINX Agent v2 and v3 in the same pod or on the same node as part of the migration. +{{< /call-out >}} + +## Steps + +1. Prepare the Deployment manifest for NGINX Agent v3. Example: + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: nginx-agent + namespace: + spec: + replicas: 1 + selector: + matchLabels: + app: nginx-agent + template: + metadata: + labels: + app: nginx-agent + spec: + containers: + - name: nginx-agent + image: /nginx-plus/agent/debian: + env: + - name: NGINX_AGENT_COMMAND_SERVER_HOST + value: "agent.connect.nginx.com" + - name: NGINX_AGENT_COMMAND_SERVER_PORT + value: "443" + - name: NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY + value: "false" + - name: NGINX_AGENT_COMMAND_AUTH_TOKEN + value: "" + - name: NGINX_LICENSE_JWT + valueFrom: + secretKeyRef: + name: nginx-secret + key: NGINX_LICENSE_JWT + # Optional: If using Config Sync Groups + # - name: NGINX_AGENT_LABELS + # value: "config-sync-group=" + ``` + +2. Apply the Deployment and monitor the rollout: + ```shell + kubectl apply -n -f nginx-agent-v3-deployment.yaml + kubectl rollout status deployment/nginx-agent -n + ``` + +3. Validate the replacement: + ```shell + kubectl get pods -n + kubectl logs -n + ``` + - Look for: msg="Agent connected" in the logs. + +4. Verify in NGINX One Console: + - The instance appears Online in the Instances view. + - If using Config Sync Groups, confirm group members are Online. + +## Troubleshoot + +- Describe the pod to verify env vars and image tag: + ```shell + kubectl describe pod -n + ``` + +## Rollback + +- Reapply the previous v2 Deployment manifest: + ```shell + kubectl apply -f nginx-agent-v2-deployment.yaml + ``` + +## References +- [Agent v3 environment variables:]({{< ref "/nginx-one-console/agent/configure-instances/configuration-overview/" >}}) +- [Docker images:]({{< ref "https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-docker/" >}}) +- Config conversion script: https://raw.githubusercontent.com/nginx/agent/v3/scripts/packages/upgrade-agent-config.sh \ No newline at end of file diff --git a/content/nginx-one-console/agent/install-upgrade/migration/vm.md b/content/nginx-one-console/agent/install-upgrade/migration/vm.md new file mode 100644 index 0000000000..4daba27174 --- /dev/null +++ b/content/nginx-one-console/agent/install-upgrade/migration/vm.md @@ -0,0 +1,63 @@ +--- +title: Migrate NGINX Agent v2 to v3 on VMs (RPM/DEB) +toc: true +weight: 100 +nd-content-type: how-to +nd-product: NAGENT +--- + +## Before you begin + +- Ensure you have the following: + - NGINX_LICENSE_JWT + - NGINX Agent command auth token (data plane key) + - Repository access and package manager permissions for your distribution +- Back up configuration: + - /etc/nginx-agent + - Every configuration directory specified as a `config_dirs` value in /etc/nginx-agent/nginx-agent.conf +- Plan a maintenance window and test this procedure in a non‑production environment first. + +{{< call-out class="caution" title="Do not run v2 and v3 concurrently" >}} +Do not run NGINX Agent v2 and v3 concurrently on the same host. +{{< /call-out >}} + +## Steps + +1. If you are using a version older than NGINX Agent v2.31.0, stop the agent before upgrading and start it again after the upgrade. + - sudo systemctl stop nginx-agent + +2. Upgrade the package to v3. + - CentOS, RHEL (RPM‑based): + ```shell + sudo yum -y makecache + sudo yum update -y nginx-agent + ``` + - Debian, Ubuntu (DEB‑based): + ```shell + sudo apt-get update + sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold" + ``` + +3. If using a config file, ensure required values are present. If you used Config Sync Groups in v2, add the following label in v3: + - NGINX_AGENT_LABELS: config-sync-group= + +## Validate + +- Check service status and logs for a successful connection, for example: msg="Agent connected". +- Verify the instance appears Online in the NGINX One Console. + +## Troubleshoot + +- Review the nginx-agent service status and logs for authentication or configuration errors. + - View logs by running: `sudo journalctl -u nginx-agent -xe` +- Confirm that credentials (NGINX_LICENSE_JWT, data plane key) are valid. + +## Rollback + +- Reinstall the previous v2 package and restore your configuration backup if required. + +## References + +- [Agent v3 environment variables:]({{< ref "/nginx-one-console/agent/configure-instances/configuration-overview/" >}}) +- [Docker images:]({{< ref "https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-docker/" >}}) +- Config conversion script: https://raw.githubusercontent.com/nginx/agent/v3/scripts/packages/upgrade-agent-config.sh diff --git a/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md b/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md deleted file mode 100644 index 4b75f19a34..0000000000 --- a/content/nginx-one-console/agent/install-upgrade/upgrade-v2-v3.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: Migrate NGINX Agent v2 to v3 -weight: 600 -toc: true -nd-docs: DOCS-1227 -nd-content-type: how-to -nd-product: NAGENT ---- - -This guide explains how to migrate deployments from **NGINX Agent v2** to **NGINX agent v3**. Agent v3 introduces architectural and configuration changes. As a result, migrating from v2 to v3 should be approached as a controlled migration. - -{{< call-out class="warning" title="Breaking Changes in NGINX Agent v3 Migration" >}} - -The migration from Agent v2 to Agent v3 introduces critical changes that may disrupt existing workflows: - -- **Environment Variables**: - - Environment variables renamed (v2 → v3): - - `NGINX_AGENT_SERVER_HOST` -> `NGINX_AGENT_COMMAND_SERVER_HOST` - - `NGINX_AGENT_SERVER_GRPCPORT` -> `NGINX_AGENT_COMMAND_SERVER_PORT` - - `NGINX_AGENT_SERVER_TOKEN` -> `NGINX_AGENT_COMMAND_AUTH_TOKEN` - - Ensure the new variables are correctly updated in Agent v3 configuration before deployment. - - [Complete list of Agent v3 environment variables](https://docs.nginx.com/nginx-one-console/agent/configure-instances/configuration-overview/) - -- **Config Sync Groups** - - In v3 config sync groups are defined using the following format: - ```yaml - - name: NGINX_AGENT_LABELS - value: "config-sync-group=" - ``` - {{< /call-out >}} - -## Migrate NGINX Agent running using Virtual Machines -{{< include "/agent/installation/update.md" >}} - - - -## Migrate NGINX Agent running in Kubernetes - -{{< call-out class="info">}} -Docker images are available in the [Deploying NGINX and NGINX Plus on Docker](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-docker/) NGINX documentation. - {{< /call-out >}} - -- Prepare NGINX Agent v3 Deployment YAML, for example: - ```yaml - containers: - - name: nginx-agent - image: /nginx-plus/agent/debian:r36 - env: - - name: NGINX_AGENT_COMMAND_SERVER_HOST - value: "agent.connect.nginx.com" - - name: NGINX_AGENT_COMMAND_SERVER_PORT - value: "443" - - name: NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY - value: "false" - - name: NGINX_AGENT_COMMAND_AUTH_TOKEN - value: "" - - name: NGINX_LICENSE_JWT - valueFrom: - secretKeyRef: - name: nginx-secret - key: NGINX_LICENSE_JWT - ``` -- Deploy the Updated Manifest, Apply the Deployment using kubectl: - ```shell - kubectl apply -n -f nginx-agent-v3-deployment.yaml - ``` -- Monitor the Rollout Progress - ```shell - kubectl rollout status deployment/ -n - ``` - -- Validate the Replacement -Once the rollout is complete, ensure all v2 pods have been replaced with v3 pods: - -- Confirm all pods transistion to running: - ```shell - kubectl get pods -n - ``` - -### Post-Migration Validations - -1. Check for agent connected message, example: **msg="Agent connected"** - ```shell - kubectl logs -n - ``` -2. Search for the Instance on NGINX One Console - -1. **Open the Instances View**: - - Navigate to the **Instances View** in the NGINX One Console. - -2. **Search for the NGINX Instance**: - - Enter the **Pod Name** in the search field located in the top-right corner of the Instances View. - -3. **Check Instance Availability Status**: - - Ensure the **Availability** status of the instance shows **Online**. - -4. **Check Config Sync Group (If Applicable)**: - - If your instance is part of a **Config Sync Group**: - - Open the **Config Sync Groups** section. - - Locate your specific **Config Sync Group**. - - Verify that instances listed in the group are also shown as **Online** in the **Instances Section**. - - -### Troubleshooting - -If issues arise during migration, follow these steps: - -1. Check for any errors in the logs: - ```shell - kubectl logs -n - ``` -2. Environment Variables: -Inspect the pod to confirm all environment variables are correctly set: - ```shell - kubectl describe pod -n - ``` -3. Rollback to NGINX Agent v2 - ```shell - kubectl apply -f nginx-agent-v2-deployment.yaml - ``` - -## Migrate NGINX Agent running using docker compose - -#### v2 Docker Compose Configuration - -```yaml -version: "3.8" -services: -nginx-agent: - image: /nginx-agent:v2 - environment: - NGINX_AGENT_SERVER_HOST: agent.connect.nginx.com - NGINX_AGENT_SERVER_GRPCPORT: "443" - NGINX_AGENT_SERVER_TOKEN: ${NGINX_AGENT_SERVER_TOKEN} - NGINX_LICENSE_JWT: ${NGINX_LICENSE_JWT} - -``` - -#### v3 Docker Compose Configuration - -```yaml -version: "3.8" -services: - nginx-agent: - image: /nginx-plus/agent/debian: - environment: - NGINX_AGENT_COMMAND_SERVER_HOST: agent.connect.nginx.com - NGINX_AGENT_COMMAND_SERVER_PORT: "443" - NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY: "false" - NGINX_AGENT_COMMAND_AUTH_TOKEN: ${NGINX_AGENT_COMMAND_AUTH_TOKEN} - NGINX_LICENSE_JWT: ${NGINX_LICENSE_JWT} - NGINX_AGENT_LABELS: config-sync-group= -``` - -### Migration Steps for Docker Compose -1. Backup Your Existing Configuration - - Save a copy of your current docker-compose.yaml file to ensure you can roll back if necessary. - -2. Modify the Configuration - - Update your service configuration as shown in the v3 Docker Compose Configuration. - -3. Restart the Agent Service - - Bring down the existing agent running with v2: - ```bash - docker-compose down - ``` - - Start the agent with the updated v3 configuration: - ```bash - docker-compose up -d - ``` -4. Validate the Migration - - Confirm the agent is running with the v3 changes: - ```bash - docker logs - ``` - - Check the logs for successful connection messages: - ```msg="Agent connected"``` - - 5. Check in NGINX One Console - - Ensure the updated instance is listed and active in the Instances View. - - If the agent belongs to a Config Sync Group, verify that it is displayed as Online under the Config Sync Groups section. - -## Rollback Procedure - -If any issues occur, you can roll back to v2 by replacing the configuration with the v2 docker-compose.yaml and restarting the service: - ```bash - $ docker-compose down - $ docker-compose up -d - ``` -## Migrate NGINX Agent running in containers -1. Pull a docker image -```shell -sudo docker pull private-registry.nginx.com/nginx-plus/agentv3:debian -``` -2. Run the container -```shell -sudo docker run \ ---env=NGINX_LICENSE_JWT="YOUR_JWT_HERE" \ ---env=NGINX_AGENT_COMMAND_SERVER_PORT=443 \ ---env=NGINX_AGENT_COMMAND_SERVER_HOST=agent.connect.nginx.com \ ---env=NGINX_AGENT_COMMAND_AUTH_TOKEN="" \ ---env=NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY=false \ ---restart=always \ ---runtime=runc \ --d private-registry.nginx.com/nginx-plus/agentv3:debian -``` - - -Note: If you container is setup to run with a mounted configuration file use the following steps to convert to a v3 configuration file. -1. Download the conversion script (v3 branch): -```shell -wget https://raw.githubusercontent.com/nginx/agent/v3/scripts/packages/upgrade-agent-config.sh -chmod +x upgrade-agent-config.sh -``` - -2. Run the script to conver the configuration file. -```shell -./upgrade-agent-config.sh --v2-config-file=./nginx-agent-v2.conf --v3-config-file=./nginx-agent-v3.conf -``` -If your v2 agent belonged to a Config Sync Group, manually add the Config Sync Group label to the v3 config. See “Add Config Sync Group” in your docs. - - -### Rollback Procedure - -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. \ No newline at end of file From c6c4de1e97d28f549599e5e6aa7b452e8384a770 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:30:12 +0100 Subject: [PATCH 05/17] Update content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md Feedback from PR Co-authored-by: kkyle-f5 --- .../agent/install-upgrade/migration/docker-compose.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md b/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md index 56cdc1a023..8e5207ab9e 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md @@ -1,5 +1,5 @@ --- -title: Migrate NGINX Agent v2 to v3 with Docker Compose +title: Migrate with Docker Compose toc: true weight: 120 nd-content-type: how-to From 7fa3b983618f1c951ec929fe90c0906e75bf725a Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:30:36 +0100 Subject: [PATCH 06/17] Update content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md Feedback from PR Co-authored-by: kkyle-f5 --- .../agent/install-upgrade/migration/docker-compose.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md b/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md index 8e5207ab9e..a8ef581692 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md @@ -19,7 +19,7 @@ nd-product: NAGENT Do not run NGINX Agent v2 and v3 concurrently in the same container or on the same host. {{< /call-out >}} -## Steps +## Migrate 1. Update your compose file to use the v3 image and environment variables. Example: ```yaml From 1d62582d231fdcf07f666a3081401a651a10d53c Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:30:48 +0100 Subject: [PATCH 07/17] Update content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md Feedback from PR Co-authored-by: kkyle-f5 --- .../agent/install-upgrade/migration/docker-standalone.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md b/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md index d101908a74..57b37a81d8 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md @@ -1,5 +1,5 @@ --- -title: Migrate NGINX Agent v2 to v3 in a Docker container +title: Migrate in a Docker container toc: true weight: 130 nd-content-type: how-to From d014b582395c95a8f1eaba53d7be3fe66d3f84a0 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:31:07 +0100 Subject: [PATCH 08/17] Update content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md Feedback from PR Co-authored-by: kkyle-f5 --- .../agent/install-upgrade/migration/docker-standalone.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md b/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md index 57b37a81d8..5e23e3cb86 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md @@ -7,7 +7,10 @@ nd-product: NAGENT --- ## Before you begin - +- Ensure you have: + - Registry access for agent v3 images. + - NGINX_LICENSE_JWT and the NGINX Agent command auth token (data plane key). + - Registry access for agent v3 images. - NGINX_LICENSE_JWT and the NGINX Agent command auth token (data plane key). - Plan a maintenance window and test this procedure in a non‑production environment first. From c4a552aec98efb08e348f41b555afb33156adf86 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:31:22 +0100 Subject: [PATCH 09/17] Update content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md Feedback from PR Co-authored-by: kkyle-f5 --- .../agent/install-upgrade/migration/docker-standalone.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md b/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md index 5e23e3cb86..85dac593e6 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md @@ -19,7 +19,7 @@ nd-product: NAGENT Do not run NGINX Agent v2 and v3 concurrently in the same container or on the same host. {{< /call-out >}} -## Steps +## Migrate 1. Pull the v3 image: ```shell From 840ec70a252d8fcc7eea6dceb871fb2844d4a1aa Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:33:02 +0100 Subject: [PATCH 10/17] Update content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md Feedback from PR Co-authored-by: kkyle-f5 --- .../agent/install-upgrade/migration/kubernetes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md b/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md index a14b777c64..11b54aa6a8 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md @@ -1,5 +1,5 @@ --- -title: Migrate NGINX Agent v2 to v3 on Kubernetes +title: Migrate on Kubernetes toc: true weight: 110 nd-content-type: how-to From 241c6c13c8c32be6c23f47f86b57a6ef361a72e3 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:34:16 +0100 Subject: [PATCH 11/17] Update content/nginx-one-console/agent/install-upgrade/update.md Feeback from PR Co-authored-by: kkyle-f5 --- content/nginx-one-console/agent/install-upgrade/update.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/agent/install-upgrade/update.md b/content/nginx-one-console/agent/install-upgrade/update.md index a24ba8ef09..a7bb553200 100644 --- a/content/nginx-one-console/agent/install-upgrade/update.md +++ b/content/nginx-one-console/agent/install-upgrade/update.md @@ -13,7 +13,7 @@ Follow the steps below to upgrade NGINX v3 Agent to the latest version. 1. Open an SSH connection to the server where you've installed NGINX Agent. -1. Make a backup copy of the following locations to ensure that you can successfully recover if the upgrade does not complete +1. Make a backup copy of the following locations to ensure that you can recover if the upgrade does not complete successfully: - `/etc/nginx-agent` From 2ce36558b873281fd1a7a59729a9973c9dd0b6a4 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney Date: Mon, 20 Apr 2026 14:58:21 +0100 Subject: [PATCH 12/17] Feedback from pr --- .../agent/install-upgrade/migration/docker-compose.md | 3 +-- .../agent/install-upgrade/migration/docker-standalone.md | 4 +--- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md b/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md index a8ef581692..d9844fabe8 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md @@ -7,9 +7,8 @@ nd-product: NAGENT --- ## Before you begin - - Ensure you have: - - docker compose installed + - Docker compose installed - Registry credentials (if required) - `NGINX_LICENSE_JWT` and the NGINX Agent command auth token (data plane key) - Back up your existing docker-compose.yaml. diff --git a/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md b/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md index 85dac593e6..dab8930d4f 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md @@ -8,11 +8,9 @@ nd-product: NAGENT ## Before you begin - Ensure you have: + - Docker installed - Registry access for agent v3 images. - NGINX_LICENSE_JWT and the NGINX Agent command auth token (data plane key). - -- Registry access for agent v3 images. -- NGINX_LICENSE_JWT and the NGINX Agent command auth token (data plane key). - Plan a maintenance window and test this procedure in a non‑production environment first. {{< call-out class="caution" title="Do not run v2 and v3 concurrently" >}} From 76790e3cad7ddb278c5ad1e4c5bbe1cefc097dbc Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 15:01:53 +0100 Subject: [PATCH 13/17] Update content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md Feedback from PR Co-authored-by: kkyle-f5 --- .../agent/install-upgrade/migration/kubernetes.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md b/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md index 11b54aa6a8..f2b013eab7 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md @@ -7,6 +7,12 @@ nd-product: NAGENT --- ## Before you begin +- Ensure you have: + - kubectl context set to the target cluster and namespace. + - Permissions to deploy to the namespace. + - Required registry credentials available. + - A Secret for NGINX_LICENSE_JWT or that you can create one. +- Plan a maintenance window and test in a non‑production environment first. - kubectl context is set to the target cluster and namespace. - You have permissions to deploy to the namespace. From c52cb11d90277c3bd5216094314c73e4d89a279c Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 15:02:07 +0100 Subject: [PATCH 14/17] Update content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md Feedback from PR Co-authored-by: kkyle-f5 --- .../agent/install-upgrade/migration/kubernetes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md b/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md index f2b013eab7..9f3b2f7986 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md @@ -24,7 +24,7 @@ nd-product: NAGENT Do not run NGINX Agent v2 and v3 in the same pod or on the same node as part of the migration. {{< /call-out >}} -## Steps +## Migrate 1. Prepare the Deployment manifest for NGINX Agent v3. Example: ```yaml From b78b3179ebde2760b63791d2d6408271b79e5a6b Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 15:02:28 +0100 Subject: [PATCH 15/17] Update content/nginx-one-console/agent/install-upgrade/migration/vm.md Feedback from PR Co-authored-by: kkyle-f5 --- content/nginx-one-console/agent/install-upgrade/migration/vm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/vm.md b/content/nginx-one-console/agent/install-upgrade/migration/vm.md index 4daba27174..afca3a48bd 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/vm.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/vm.md @@ -21,7 +21,7 @@ nd-product: NAGENT Do not run NGINX Agent v2 and v3 concurrently on the same host. {{< /call-out >}} -## Steps +## Migrate 1. If you are using a version older than NGINX Agent v2.31.0, stop the agent before upgrading and start it again after the upgrade. - sudo systemctl stop nginx-agent From 672a0057e513854f45c152afe3b415c3471e5821 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 15:02:41 +0100 Subject: [PATCH 16/17] Update content/nginx-one-console/agent/install-upgrade/migration/vm.md Feedback from PR Co-authored-by: kkyle-f5 --- content/nginx-one-console/agent/install-upgrade/migration/vm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/vm.md b/content/nginx-one-console/agent/install-upgrade/migration/vm.md index afca3a48bd..dfa2509ff2 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/vm.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/vm.md @@ -1,5 +1,5 @@ --- -title: Migrate NGINX Agent v2 to v3 on VMs (RPM/DEB) +title: Migrate on VMs (RPM/DEB) toc: true weight: 100 nd-content-type: how-to From 61a6fea1244f5ee4883e364b420d56f278e2fd5c Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 20 Apr 2026 15:02:59 +0100 Subject: [PATCH 17/17] Update content/nginx-one-console/agent/install-upgrade/migration/vm.md Feedback from PR Co-authored-by: kkyle-f5 --- content/nginx-one-console/agent/install-upgrade/migration/vm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/agent/install-upgrade/migration/vm.md b/content/nginx-one-console/agent/install-upgrade/migration/vm.md index dfa2509ff2..7ed3eed538 100644 --- a/content/nginx-one-console/agent/install-upgrade/migration/vm.md +++ b/content/nginx-one-console/agent/install-upgrade/migration/vm.md @@ -38,7 +38,7 @@ Do not run NGINX Agent v2 and v3 concurrently on the same host. sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold" ``` -3. If using a config file, ensure required values are present. If you used Config Sync Groups in v2, add the following label in v3: +3. If you are using a config file, ensure required values are present. If you used Config Sync Groups in v2, add the following label in v3: - NGINX_AGENT_LABELS: config-sync-group= ## Validate