nginx / nginx/documentation

Create official migration guide from NGINX Open Source to NGINX Plus in product documentation

Open
#591 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

customer-success documentation enhancement onboarding P3 - Normal (TTR: 1 month) product/nginx-plus
Dominant language
HTML
Stars
94
Forks
174
Avg merge
1d 10h
Merged PRs (30d)
66

Description

Description

There is currently no official documentation in the product docs for migrating from NGINX Open Source (NOSS) to NGINX Plus (N+), even though this is:

  • A common customer use case
  • A high-priority business objective (NGINX Plus is our primary revenue driver)

There is a support KB article that addresses the topic:
https://my.f5.com/manage/s/article/K000139565

However, it is outdated and minimal:

  • It targets NGINX Plus R22. The current version is R34.
  • Significant changes were introduced in R33 related to JWT-based telemetry reporting, which are not covered.
  • There’s no guidance on post-migration steps, such as how to get value from the Plus API or other advanced features.

This gap puts customers at risk of:

  • Incomplete or broken migrations
  • Delayed time to value
  • Overlooking NGINX Plus-only features
  • Increased support requests

Goals / What needs to be documented

  1. A clear, step-by-step migration guide for moving from NGINX Open Source to NGINX Plus
  2. Instructions for:
    • Backing up and moving configuration and logs
    • Aligning with the correct target version (R34+)
    • Accounting for JWT telemetry changes starting in R33
  3. A “What to do next” section to help users begin using core NGINX Plus features immediately (for example, enabling the NGINX Plus API for metrics)
  4. Notes on how NGINX Plus differs from NOSS in areas like licensing, telemetry, and monitoring

Acceptance criteria

  • Product documentation includes an up-to-date, officially supported migration guide from NOSS to NGINX Plus
  • Content includes context and caveats for versions R33 and newer (especially around telemetry)
  • Post-migration usage recommendations are included to accelerate time to value
  • Support KB (K000139565) is deprecated and redirects to the new official documentation
  • Documentation is searchable using common migration-related terms
  • Reviewed and validated by stakeholders across Docs, Product, Support, and Engineering

References

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing product documentation and the referenced support KB K000139565, then compare its R22 guidance with the R34 requirements and R33 JWT telemetry changes described here. Done means an officially supported, searchable migration guide covering configuration and logs, telemetry, licensing, Plus API next steps, and the KB deprecation redirect, with stakeholder validation.

Written by the indexing model from the issue text.

Assessment

Tech stack
nginx
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.