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

Thanks @JTorreG , yes I have followed the best practices on the linked template.

Add in a link to full list of v3 env vars

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

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

I made a few suggestions.

…er-compose.md Feedback from PR Co-authored-by: kkyle-f5 <k.kyle@f5.com>

…er-standalone.md Feedback from PR Co-authored-by: kkyle-f5 <k.kyle@f5.com>

…rnetes.md Feedback from PR Co-authored-by: kkyle-f5 <k.kyle@f5.com>

Feeback from PR Co-authored-by: kkyle-f5 <k.kyle@f5.com>

…rnetes.md Feedback from PR Co-authored-by: kkyle-f5 <k.kyle@f5.com>

Feedback from PR Co-authored-by: kkyle-f5 <k.kyle@f5.com>

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