docs: defer upgrade finalization (DOC-2013) by Feediver1 · Pull Request #1818 · redpanda-data/docs

Feediver1 · 2026-07-22T14:04:22Z

Resolves https://redpandadata.atlassian.net/browse/DOC-2013

Adds documentation for deferred upgrade finalization (unfinalized major-version upgrades), new in 26.2.

Changes

New page modules/upgrade/pages/deferred-finalization.adoc: concept (binary vs. logical version, the three upgrade phases, finalization as the downgrade floor), Linux/rpk procedure (defer, verify the hold, soak, finalize), rollback procedure, the 26.2 gated-features table, Admin API v2 FeaturesService usage (GetUpgradeStatus/FinalizeUpgrade with response fields and error semantics), license behavior, limitations, and a troubleshooting section covering the async/one-shot finalize semantics, leadership-change caveats, and the Incompatible downgrade detected guard.
Nav: new entry after the two rolling-upgrade pages.
rolling-upgrade.adoc: a TIP after the limitations partial pointing to the new page.

All content is sourced from the engineering TOI: engineering/core/toi/v26.2/2026-07-17-unfinalized-upgrades.md.

Coordination with #1816 (DOC-2273, Kubernetes) and #1819 (DOC-2217, Shadowing)

Per the split agreed in #1816: this PR owns the concept page and Linux procedure and does not touch partials/rolling-upgrades/upgrade-limitations.adoc (that edit ships in #1816, phrased generically to serve both pages). The new page's Kubernetes section covers the operator-unaware caveat briefly and links to k-rolling-upgrade.adoc at page level.

#1819 (DOC-2217) is stacked on this PR: it adds the shadowing-upgrade page, which xrefs deferred-finalization.adoc throughout, and its base is this branch. Merging this PR retargets #1819 to beta automatically.

Suggested merge order: #1816 → this PR → #1819. After #1816 merges, the Kubernetes xref here can be tightened to the #defer-upgrade-finalization anchor (happy to do that in this PR if #1816 lands first).

Review notes

rpk cluster upgrade status|finalize are mentioned in code font without xrefs: the reference pages arrive with the 26.2 rpk regen.
The tiered_v2 storage mode is not yet documented on beta, so that gated-features row has no link.
The upgrade_override_checks bypass is deliberately omitted (TOI: support-directed emergencies only, never customer-advised); the troubleshooting entry says to contact support instead.

🤖 Generated with Claude Code

Preview pages

Defer Upgrade Finalization (new)
Upgrade Redpanda (updated)

New upgrade-module page covering the 26.2 deferred-finalization feature: concept, Linux/rpk procedure, rollback, gated-features table, Admin API v2 FeaturesService, license behavior, limitations, and troubleshooting. Adds a nav entry and a pointer TIP on the Linux rolling-upgrade page. Sourced from the engineering TOI (cupboard engineering/core/toi/v26.2/2026-07-17-unfinalized-upgrades.md). Coordinated with #1816, which owns the Kubernetes procedure and the shared upgrade-limitations partial. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

netlify · 2026-07-22T14:04:30Z

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	`a4ee5cd`
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a60df76f5b74a000852a0a9
😎 Deploy Preview	https://deploy-preview-1818--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

coderabbitai · 2026-07-22T14:04:30Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ad44d70c-08e9-41e0-be3c-c990d8a820bf

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch DOC-2013-deferred-finalization

_{Comment @coderabbitai help to get the list of available commands.}

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>

Feediver1 · 2026-07-22T15:08:38Z

+The v1 Admin API is unchanged and still useful: `GET /v1/features` reports `cluster_version`, `node_latest_version`, and each feature's state (`unavailable` while gated, `active` after finalization).
+
+== License behavior
+


As noted in Prerequisites, a valid Enterprise license is required to specify deferred finalization. The following behaviors occur if you attempt to use deferred finalization without a license.

Feediver1 · 2026-07-22T15:10:59Z

+* Finalizing is not license-checked: `rpk cluster upgrade finalize` works even if the license expired during the soak. The enforcement point is setting the property, nothing else.
+
+== Limitations
+


Before starting, familiarize yourself with the limitations of the deferred finalization feature:

…ix in rolling-upgrade TIP Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Feediver1 requested a review from a team as a code owner July 22, 2026 14:04