Add v2 to v3 migration guide by nginx-seanmoloney · Pull Request #1843 · nginx/documentation

nginx-seanmoloney · 2026-04-09T14:00:34Z

Proposed changes

Add v2 to v3 migration guide
- Document differerent upgrade scenarios
- Add troubleshooting and post migration checks

Checklist

Before sharing this pull request, I completed the following checklist:

I read the Contributing guidelines
My branch adheres to the Git conventions
My content changes adhere to the F5 NGINX Documentation style guide
If my changes involve potentially sensitive information¹, I have assessed the possible impact
I have waited to ensure my changes pass tests, and addressed any discovered issues

Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the style guide for guidance about placeholder content. ↩

github-actions · 2026-04-09T14:02:40Z

✅ Deploy Preview will be available once build job completes!

Name	Link
😎 Deploy Preview	https://frontdoor-test-docs.nginx.com/previews/docs/1843/

fabriziofiorucci · 2026-04-09T15:22:50Z

Migrate NGINX Agent running in containers - I presume this refers to the case where I have a pod running NGINX and the Agent, and the Agent's config file is mounted through a ConfigMap. Am I correct here? In case I am, it might be worth mentioning this in the MD file

JTorreG · 2026-04-14T17:40:07Z

+---
+title: Migrate NGINX Agent v2 to v3 
+weight: 600
+toc: true
+nd-docs: DOCS-1227
+nd-content-type: how-to
+nd-product: NAGENT
+---


Please check the new template for how-to guides
https://github.com/nginx/documentation/blob/main/templates/how-to/guide-how-to.md

Add in a link to full list of v3 env vars

…dd migration/; remove deprecated upgrade-v2-v3.md

kkyle-f5 · 2026-04-16T13:32:04Z

@@ -0,0 +1,64 @@
+---
+title: Migrate NGINX Agent v2 to v3 with Docker Compose


Suggested change

title: Migrate NGINX Agent v2 to v3 with Docker Compose

title: Migrate with Docker Compose

Title was redundant. Suggest we shorten.

kkyle-f5 · 2026-04-16T15:10:22Z

+Do not run NGINX Agent v2 and v3 concurrently in the same container or on the same host.
+{{< /call-out >}}
+
+## Steps


Suggested change

## Steps

## Migrate

kkyle-f5 · 2026-04-16T15:11:03Z

@@ -0,0 +1,64 @@
+---
+title: Migrate NGINX Agent v2 to v3 in a Docker container


Suggested change

title: Migrate NGINX Agent v2 to v3 in a Docker container

title: Migrate in a Docker container

kkyle-f5 · 2026-04-16T15:11:59Z

+---
+
+## Before you begin
+


Suggested change

- Ensure you have:

- Registry access for agent v3 images.

- NGINX_LICENSE_JWT and the NGINX Agent command auth token (data plane key).

kkyle-f5 · 2026-04-16T15:12:25Z

+Do not run NGINX Agent v2 and v3 concurrently in the same container or on the same host.
+{{< /call-out >}}
+
+## Steps


Suggested change

## Steps

## Migrate

kkyle-f5 · 2026-04-16T15:18:47Z

+
+## Before you begin
+
+- Registry access for agent v3 images.


Move under "Ensure you have:"

Use the full product name: NGINX Agent

kkyle-f5 · 2026-04-16T15:18:57Z

+## Before you begin
+
+- Registry access for agent v3 images.
+- NGINX_LICENSE_JWT and the NGINX Agent command auth token (data plane key).


Move under "Ensure you have:"

kkyle-f5 · 2026-04-16T15:21:36Z

@@ -0,0 +1,96 @@
+---
+title: Migrate NGINX Agent v2 to v3 on Kubernetes


Suggested change

title: Migrate NGINX Agent v2 to v3 on Kubernetes

title: Migrate on Kubernetes

kkyle-f5 · 2026-04-16T15:24:21Z

+---
+
+## Before you begin
+


Suggested change

- 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.

kkyle-f5 · 2026-04-16T15:24:59Z

+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


Suggested change

## Steps

## Migrate

kkyle-f5 · 2026-04-16T15:35:50Z

@@ -0,0 +1,63 @@
+---
+title: Migrate NGINX Agent v2 to v3 on VMs (RPM/DEB)


Suggested change

title: Migrate NGINX Agent v2 to v3 on VMs (RPM/DEB)

title: Migrate on VMs (RPM/DEB)

kkyle-f5 · 2026-04-16T15:36:12Z

+Do not run NGINX Agent v2 and v3 concurrently on the same host.
+{{< /call-out >}}
+
+## Steps


Suggested change

## Steps

## Migrate

kkyle-f5 · 2026-04-16T15:36:57Z

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


Suggested change

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:

kkyle-f5 · 2026-04-16T15:38:58Z

+
+## Rollback
+
+- Reinstall the previous v2 package and restore your configuration backup if required.


Suggested change

- Reinstall the previous v2 package and restore your configuration backup if required.

- Reinstall the previous v2 package and, if required, restore your configuration backup.

kkyle-f5 · 2026-04-16T15:41:51Z

+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


Suggested change

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

kkyle-f5

I made a few suggestions.

Add v2 to v3 migration guide

3fcf9ac

nginx-seanmoloney requested a review from a team as a code owner April 9, 2026 14:00

nginx-seanmoloney marked this pull request as draft April 9, 2026 14:00

github-actions bot added documentation Improvements or additions to documentation product/nginx-one-console Issues related to NGINX One Console labels Apr 9, 2026

Improve instructions when running with a mounted file

1188708

nginx-seanmoloney marked this pull request as ready for review April 13, 2026 20:47

JTorreG reviewed Apr 14, 2026

View reviewed changes

nginx-seanmoloney marked this pull request as draft April 15, 2026 09:19

nginx-seanmoloney added 2 commits April 16, 2026 09:27

Refactor the update page

ab21ecc

Add in a link to full list of v3 env vars

docs(agent): migrate v2→v3 upgrade guide; update installation docs; a…

e6137ae

…dd migration/; remove deprecated upgrade-v2-v3.md

github-actions bot added the product/agent Issues related to NGINX Agent label Apr 16, 2026

nginx-seanmoloney marked this pull request as ready for review April 16, 2026 12:07

kkyle-f5 reviewed Apr 16, 2026

View reviewed changes

		@@ -0,0 +1,64 @@
		---
		title: Migrate NGINX Agent v2 to v3 with Docker Compose

	title: Migrate NGINX Agent v2 to v3 with Docker Compose
	title: Migrate with Docker Compose

		@@ -0,0 +1,64 @@
		---
		title: Migrate NGINX Agent v2 to v3 in a Docker container

	title: Migrate NGINX Agent v2 to v3 in a Docker container
	title: Migrate in a Docker container

		@@ -0,0 +1,96 @@
		---
		title: Migrate NGINX Agent v2 to v3 on Kubernetes

	title: Migrate NGINX Agent v2 to v3 on Kubernetes
	title: Migrate on Kubernetes

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

		@@ -0,0 +1,63 @@
		---
		title: Migrate NGINX Agent v2 to v3 on VMs (RPM/DEB)

	title: Migrate NGINX Agent v2 to v3 on VMs (RPM/DEB)
	title: Migrate on VMs (RPM/DEB)

	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:


		## Rollback

		- Reinstall the previous v2 package and restore your configuration backup if required.

	- Reinstall the previous v2 package and restore your configuration backup if required.
	- Reinstall the previous v2 package and, if required, restore your configuration backup.

	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

Conversation

nginx-seanmoloney commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Checklist

Footnotes

Uh oh!

github-actions bot commented Apr 9, 2026

✅ Deploy Preview will be available once build job completes!

Uh oh!

fabriziofiorucci commented Apr 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kkyle-f5 Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kkyle-f5 Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kkyle-f5 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nginx-seanmoloney commented Apr 9, 2026 •

edited

Loading

kkyle-f5 Apr 16, 2026 •

edited

Loading

kkyle-f5 Apr 16, 2026 •

edited

Loading