Skip to content

docs: uncomment hidden upgrade documentation #746

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jhaayushkumar wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: uncomment hidden upgrade documentation #746

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions assets/docs/pages/operations/upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
You can use this guide to upgrade the {{< reuse "/docs/snippets/kgateway.md" >}} control plane and data plane components, or to apply changes to the components' configuration settings.

<!-- TODO upgrade guide when we have a minor version

@kristin-kronstain-brown kristin-kronstain-brown May 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't seem to be as simple as just uncommenting. The commented out information seems to need some more attention.

Issue 1: "## Step 2: Upgrade the CLI" is wrong in two ways

  1. docs/snippets/cli-name.md resolves to glooctl, which is Solo.io's proprietary CLI, not kgateway's. kgateway's CLI is kgwctl.

  2. kgwctl has no upgrade subcommand. Its documented commands are: analyze, check, completion, describe, get, help. There is no mechanism to upgrade kgateway via the CLI. The upgrade is Helm-only. The entire "## Step 2: Upgrade the CLI" section should be removed, not published.

Issue 2: "## Step 3: Upgrade kgateway" is an empty heading

The comment boundary (-->) was placed immediately before the Step 3 heading with no body content under it. After the uncomment, Step 3 renders as a heading with nothing under it, followed immediately by ## Prepare to upgrade {#prepare}. This is a dead-end section.

Issue 3: Duplicate "prepare" sections

The newly revealed "## Step 1: Prepare to upgrade" (checking dependencies, setting $NEW_VERSION) and the pre-existing "## Prepare to upgrade {#prepare}" serve the same purpose and now both appear in the same page, back to back.

Issue 4: export NEW_VERSION=... is set twice

Step 1 (step 3) sets it, and "## Upgrade {#upgrade-steps}" step 1 sets it again. A user reading end-to-end hits the same variable assignment in two different sections.

## Considerations
Consider the following rules before you plan your kgateway upgrade.

Expand Down Expand Up @@ -57,8 +56,6 @@ During the upgrade, pods that run the new version of the control plane and proxi

## Step 3: Upgrade kgateway

-->


## Prepare to upgrade {#prepare}

Expand Down