Add v2 to v3 migration guide

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:
 

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/
+---

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=<config-sync-group-name>
+{{< /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 >}}
+

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: <registry>/nginx-plus/agent/debian:<v3-tag>
+       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=<config-sync-group-name>
+   ```
+
+2. Restart the service:
+   ```shell
+   docker compose down
+   docker compose up -d
+   ```
+
+3. Validate the migration:
+   ```shell
+   docker logs <nginx-agent-container-name>
+   ```
+   - 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

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 <registry>/nginx-plus/agentv3:debian
+   ```
+
+2. Run the container:
+   ```shell
+   docker run -d \
+     --restart=always \
+     -e NGINX_LICENSE_JWT="<jwt>" \
+     -e NGINX_AGENT_COMMAND_SERVER_HOST=agent.connect.nginx.com \
+     -e NGINX_AGENT_COMMAND_SERVER_PORT=443 \
+     -e NGINX_AGENT_COMMAND_AUTH_TOKEN="<data-plane-key>" \
+     -e NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY=false \
+     <registry>/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=<config-sync-group-name>
+
+## Validate
+
+- Check logs for a successful connection message:
+  ```shell
+  docker logs <container>
+  ```
+  - 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

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: <namespace>
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: nginx-agent
+     template:
+       metadata:
+         labels:
+           app: nginx-agent
+       spec:
+         containers:
+           - name: nginx-agent
+             image: <registry>/nginx-plus/agent/debian:<v3-tag>
+             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: "<auth-token>"
+               - 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=<config-sync-group-name>"
+   ```
+
+2. Apply the Deployment and monitor the rollout:
+   ```shell
+   kubectl apply -n <namespace> -f nginx-agent-v3-deployment.yaml
+   kubectl rollout status deployment/nginx-agent -n <namespace>
+   ```
+
+3. Validate the replacement:
+   ```shell
+   kubectl get pods -n <namespace>
+   kubectl logs <pod-name> -n <namespace>
+   ```
+   - 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 <pod-name> -n <namespace>
+  ```
+
+## 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

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=<config-sync-group-name>
+
+## 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

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,25 +9,28 @@ nd-product: NAGENT
 
 ## Overview
 
-{{< include "/agent/installation/update.md" >}}
+Follow the steps below to upgrade NGINX v3 Agent to the latest version.
 
-## Migrate NGINX Agent running in containers
+1. Open an SSH connection to the server where you've installed NGINX Agent.
 
-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)
+1. Make a backup copy of the following locations to ensure that you can successfully recover if the upgrade does not complete
+   successfully:
 
-To upgrade the configuration, you can follow this example:
+    - `/etc/nginx-agent`
+    - Every configuration directory specfied in `/etc/nginx-agent/nginx-agent.conf` as a `config_dirs` value
 
-```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
-```
+1. Install the updated version of NGINX Agent:
 
-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.
+    - CentOS, RHEL, RPM-Based
 
-### Rolling back from NGINX Agent v3 to v2
+        ```shell
+        sudo yum -y makecache
+        sudo yum update -y nginx-agent
+        ```
 
-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`.
+    - Debian, Ubuntu, Deb-Based
 
-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.
+        ```shell
+        sudo apt-get update
+        sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold"