From 3fcf9ac4973812192576d3c270ac51df33962caf Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney Date: Thu, 9 Apr 2026 14:57:56 +0100 Subject: [PATCH] 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=