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..d9844fabe8 --- /dev/null +++ b/content/nginx-one-console/agent/install-upgrade/migration/docker-compose.md @@ -0,0 +1,63 @@ +--- +title: Migrate 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 >}} + +## Migrate + +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..dab8930d4f --- /dev/null +++ b/content/nginx-one-console/agent/install-upgrade/migration/docker-standalone.md @@ -0,0 +1,65 @@ +--- +title: Migrate in a Docker container +toc: true +weight: 130 +nd-content-type: how-to +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). +- 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 >}} + +## Migrate + +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..9f3b2f7986 --- /dev/null +++ b/content/nginx-one-console/agent/install-upgrade/migration/kubernetes.md @@ -0,0 +1,102 @@ +--- +title: Migrate on Kubernetes +toc: true +weight: 110 +nd-content-type: how-to +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. +- 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 >}} + +## Migrate + +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..7ed3eed538 --- /dev/null +++ b/content/nginx-one-console/agent/install-upgrade/migration/vm.md @@ -0,0 +1,63 @@ +--- +title: Migrate 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 >}} + +## 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 + +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 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 + +- 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/update.md b/content/nginx-one-console/agent/install-upgrade/update.md index a43ae085e6..a7bb553200 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,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 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" 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=