docs: defer upgrade finalization (DOC-2013) - #1818
Conversation
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 <[email protected]>
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Co-Authored-By: Claude Fable 5 <[email protected]>
Co-authored-by: Joyce Fee <[email protected]>
…ix in rolling-upgrade TIP Co-Authored-By: Claude Fable 5 <[email protected]>
Co-Authored-By: Claude Fable 5 <[email protected]>
Co-Authored-By: Claude Fable 5 <[email protected]>
| * *Brokers advertise the new release version during the soak.* The Admin API, health reports, `rpk redpanda admin brokers list`, and the Redpanda Console broker view all show the new release string while unfinalized; only the logical version and feature activation are held back. The one wire-visible exception: Kafka API keys gated behind held features are absent from `ApiVersions` responses until finalization. | ||
| * *`features_auto_finalization` is independent of `features_auto_enable`.* Auto-finalization controls when the cluster version advances; `features_auto_enable` is an older, unrelated property that controls whether individual features activate on their own after the version has advanced. Leave `features_auto_enable` alone. | ||
|
|
||
| == Deferred finalization in Kubernetes |
There was a problem hiding this comment.
Merged with this confirmation outstanding, per the docs DRI: the Kubernetes caveat (Operator/Helm treat an upgrade as complete at pod rollout, with no finalization awareness) is TOI-sourced and not merge-critical. @andrewstucki if any part of that behavior is wrong, flag it here and we'll fast-follow a correction before or shortly after the 26.2 promotion.
Includes the merge of current beta (the What's New page was reset for 26.2 after this branch was cut). The Shadowing-topology xref resolves once DOC-2217 (#1819) merges into this branch. Co-Authored-By: Claude Fable 5 <[email protected]>
|
@copilot resolve the merge conflicts in this pull request |
Resolved. The only conflict was in |
- Replace rpk redpanda admin brokers list (deprecated in 26.2, swept in #1832) with rpk cluster info -b --detailed in the Limitations bullet. - Move the Shadowing-topology sentence and xref out of the What's New entry: the target page ships in #1819, so this PR is now self-contained and can merge independently. #1819 re-adds the sentence alongside its page. Co-Authored-By: Claude Fable 5 <[email protected]>
… New entry Moved here from #1818 (per review): the shadowing upgrade page ships in this PR, so the sentence and xref belong with it. Includes the merge of the updated base branch. Co-Authored-By: Claude Fable 5 <[email protected]>
|
Both critical findings from the review are fixed in
The pending inline suggestions from the earlier self-review pass are all already applied by commits 3–5 (one deliberately improved: the downgrade-floor wording kept its main verb) — they can be marked resolved. 🤖 Generated with Claude Code |
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
PR Review (docs-team-standards final pass)
Files reviewed: 4 (new deferred-finalization.adoc page, nav entry, rolling-upgrade TIP, What's New entry)
Overall assessment: Comprehensive, TOI-sourced feature page that cross-checks cleanly against the Admin API v2 reference work (api-docs#76). Both critical findings from this review have already been fixed on the branch; what follows is the disposition record plus the points that remain open.
Jira ticket alignment
DOC-2013: fully addressed — concept, Linux/rpk procedure, rollback, gated-features table, Admin API v2 usage, license behavior, limitations, troubleshooting, all sourced from the engineering TOI, with the Kubernetes procedure correctly delegated to #1816's territory.
Critical findings — both fixed (commit 878a7f37)
- Deprecated command in a new 26.2 page: the Limitations bullet cited
rpk redpanda admin brokers list, which 26.2 itself deprecates and hides (redpanda#30332; prose sweep in #1832). Nowrpk cluster info -b --detailed. - Merge-order hazard eliminated: the What's New entry xref'd
manage:disaster-recovery/shadowing/upgrade.adoc, which ships only in #1819. The Shadowing sentence and xref moved to #1819 (commitbcfbf370there), so this PR is self-contained and merges independently in either order.
Editorial suggestions — all applied and verified
All 15 inline suggestions from the earlier editing pass are in the current content, verified programmatically: 14 verbatim, and the downgrade-floor sentence deliberately keeps the grammatical form (the suggestion text had dropped the sentence's main verb). Threads are resolved.
Remaining open points (not blockers to note, one to chase)
- Open SME confirmation: the unresolved thread from @dotnwat pings @andrewstucki on the "Deferred finalization in Kubernetes" caveat (Operator/Helm consider an upgrade complete at pod rollout; no finalization awareness). That thread is deliberately left open — it is the one technical claim on the page still awaiting SME confirmation, and it should be answered before or shortly after merge.
- rpk regen dependency (informational): the
rpk cluster upgradecommands correctly appear in code font with no xrefs — their reference pages don't exist onbetayet. When the 26.2 rpk regen lands, add the xrefs (same coordination as DOC-2121). - Downstream impact: #1828 needs a
betare-merge before it lands — beta's What's New grew four entries since it branched, so its insert-before-Kafka context is stale. One-line resolution.
Verified (load-bearing checks)
features_auto_finalizationexists in beta's generated cluster-properties partial — the Prerequisites xref anchor resolves.- Admin API semantics match api-docs#76 exactly:
FAILED_PRECONDITIONwhen auto-finalization is enabled, async accept-then-poll contract,GetUpgradeStatusfield set — the two PRs tell one consistent story, in the same "feature-release upgrade" vocabulary. - The copilot-swe-agent beta merge resolved the What's New conflict correctly: zero conflict markers on the head file, both entries preserved, sensible ordering in beta's now-crowded page.
What works well
- The troubleshooting section's design-principle framing ("the failure mode is always you must ask again, never it finalized when it shouldn't have") is the kind of mental model that prevents support tickets.
- The gated-features table turns an internal feature-flag list into user-visible symptoms with exact error strings — directly greppable by users who hit them.
- The one-shot/async finalize semantics, leadership-change caveats, and the
Incompatible downgrade detectedguard-rail explanation are unusually honest about sharp edges.
🤖 Generated with Claude Code
Co-authored-by: Claude Fable 5 <[email protected]>
kbatuigas
left a comment
kbatuigas
left a comment
There was a problem hiding this comment.
Left a some comments/suggestions inline, and I'll leave another finding from the Claude review here:
[deferred-finalization.adoc — throughout] Prose uses a v prefix (v26.2, v26.1). Confirm against house style — terminology examples use "Redpanda 26.2" / "26.2" without the prefix. CLI output (v26.2.1) legitimately keeps it.
I'll approve so I'm not blocking but please take a look at comments!
|
|
||
| The design principle throughout is that the cluster never advances without an explicit request: the failure mode is always "you must ask again," never "it finalized when it shouldn't have." | ||
|
|
||
| Finalize appears to do nothing:: |
There was a problem hiding this comment.
I don't think we use these types of lists in our docs, I believe our convention for Troubleshooting sections has become
== Troubleshooting
=== Symptom (for example === Finalize appears to do nothing))
|
|
||
| == Troubleshooting | ||
|
|
||
| The design principle throughout is that the cluster never advances without an explicit request: the failure mode is always "you must ask again," never "it finalized when it shouldn't have." |
There was a problem hiding this comment.
Quotation marks used for phrases ("you must ask again," never "it finalized when it shouldn't have.", "finalization pending"). Style guide: avoid quotation marks — reword or italicize.
| + | ||
| This is a runtime change to a cluster configuration property; no restart is required. The property must be set to `false` before the last broker rolls to the new binary. Setting it after the upgrade has already finalized has no effect. | ||
|
|
||
| . Perform the xref:upgrade:rolling-upgrade.adoc#perform-a-rolling-upgrade[rolling upgrade] as usual, one broker at a time. Nothing about the roll changes. |
There was a problem hiding this comment.
What does "the roll" refer to? Not sure I see how the sentence helps with understanding
| | Configuring Schema Registry API-mode sync on a shadow link fails with a `FAILED_PRECONDITION` error: "Schema Registry API sync mode cannot be configured until the upgrade is finalized." The pre-existing topic-mode Schema Registry sync is unaffected. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc[]. | ||
|
|
||
| | Extended Iceberg mode configurations | ||
| | The extended Iceberg mode topic configurations introduced in v26.2 are rejected until you finalize. |
There was a problem hiding this comment.
If we want to add the link to the updated doc, this is the new section for the "extended Iceberg mode" https://github.com/redpanda-data/docs/blob/beta/modules/manage/pages/iceberg/specify-iceberg-schema.adoc?plain=1#L124 (I think the xref would be xref:manage:iceberg/specify-iceberg-schema.adoc#configure-key-value-and-header-translation, but please verify before commit
| | The extended Iceberg mode topic configurations introduced in v26.2 are rejected until you finalize. | ||
| |=== | ||
|
|
||
| Two additional v26.2 feature gates are internal-only and have no user-visible difference while unfinalized. |
There was a problem hiding this comment.
What does internal only mean? If these are not user-visible, do we still need this sentence?
| [[roll-back-to-the-previous-release]] | ||
| == Roll back to the previous release | ||
|
|
||
| While `rpk cluster upgrade status` reports `ready to finalize` (or while the roll is still in progress), you can roll back: reinstall the previous release's binaries and perform a rolling restart, following your normal upgrade procedure in reverse. No cluster command is needed. Just don't finalize. |
There was a problem hiding this comment.
| While `rpk cluster upgrade status` reports `ready to finalize` (or while the roll is still in progress), you can roll back: reinstall the previous release's binaries and perform a rolling restart, following your normal upgrade procedure in reverse. No cluster command is needed. Just don't finalize. | |
| While `rpk cluster upgrade status` reports `ready to finalize` (or while the roll is still in progress), you can roll back: reinstall the previous release's binaries and perform a rolling restart, following your normal upgrade procedure in reverse. No cluster command is needed. The rollback path stays open as long as you don't finalize. |
Just a rephrasing suggestion; your call
|
|
||
| == Limitations | ||
|
|
||
| Before starting, familiarize yourself with the limitations of the deferred finalization feature: |
There was a problem hiding this comment.
Does "before starting" mean, before starting the whole process? Should this section be moved up/earlier in this doc?
| * *Not available in Redpanda Cloud.* Cloud manages its own upgrade lifecycle, and `rpk` refuses to run the upgrade commands against cloud clusters. | ||
| * *You cannot skip finalization and keep upgrading.* Redpanda supports upgrades from exactly one feature release back, so an unfinalized v26.2 cluster must finalize before you can begin an upgrade to v26.3. Staying unfinalized indefinitely blocks future upgrades. | ||
| * *In multi-hop upgrades, only the newest hop is held.* The property value persists across hops, but intermediate hops finalize automatically. For example, in a v25.3 to v26.1 to v26.2 upgrade path, the v25.3 to v26.1 hop auto-finalizes (v26.1 has the property definition but not the deferral logic), and only the v26.1 to v26.2 hop holds. You cannot roll back to v25.3 after reaching v26.1. | ||
| * *No dedicated metric or alert.* There is no metric for "finalization pending." Monitor with `rpk cluster upgrade status --format json` or the `GetUpgradeStatus` RPC. |
There was a problem hiding this comment.
If this section is moved up, it might be helpful for GetUpgradeStatus RPC to link to the "Use the Admin API" section
|
|
||
| Before starting, familiarize yourself with the limitations of the deferred finalization feature: | ||
|
|
||
| * *Not available in Redpanda Cloud.* Cloud manages its own upgrade lifecycle, and `rpk` refuses to run the upgrade commands against cloud clusters. |
There was a problem hiding this comment.
| * *Not available in Redpanda Cloud.* Cloud manages its own upgrade lifecycle, and `rpk` refuses to run the upgrade commands against cloud clusters. | |
| * *Not available in Redpanda Cloud.* Cloud manages its own upgrade lifecycle, and the `rpk cluster upgrade` commands return an error against cloud clusters. |
| * *In multi-hop upgrades, only the newest hop is held.* The property value persists across hops, but intermediate hops finalize automatically. For example, in a v25.3 to v26.1 to v26.2 upgrade path, the v25.3 to v26.1 hop auto-finalizes (v26.1 has the property definition but not the deferral logic), and only the v26.1 to v26.2 hop holds. You cannot roll back to v25.3 after reaching v26.1. | ||
| * *No dedicated metric or alert.* There is no metric for "finalization pending." Monitor with `rpk cluster upgrade status --format json` or the `GetUpgradeStatus` RPC. | ||
| * *Brokers advertise the new release version during the soak.* The Admin API, health reports, `rpk cluster info -b --detailed`, and the Redpanda Console broker view all show the new release string while unfinalized; only the logical version and feature activation are held back. The one wire-visible exception: Kafka API keys gated behind held features are absent from `ApiVersions` responses until finalization. | ||
| * *`features_auto_finalization` is independent of `features_auto_enable`.* Auto-finalization controls when the cluster version advances; `features_auto_enable` is an older, unrelated property that controls whether individual features activate on their own after the version has advanced. Leave `features_auto_enable` alone. |
There was a problem hiding this comment.
| * *`features_auto_finalization` is independent of `features_auto_enable`.* Auto-finalization controls when the cluster version advances; `features_auto_enable` is an older, unrelated property that controls whether individual features activate on their own after the version has advanced. Leave `features_auto_enable` alone. | |
| * *`features_auto_finalization` is independent of `features_auto_enable`.* Auto-finalization controls when the cluster version advances; `features_auto_enable` is an older, unrelated property that controls whether individual features activate on their own after the version has advanced. Deferred finalization requires no change to `features_auto_enable`. |
Resolves https://redpandadata.atlassian.net/browse/DOC-2013
Adds documentation for deferred upgrade finalization (unfinalized major-version upgrades), new in 26.2.
Changes
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 v2FeaturesServiceusage (GetUpgradeStatus/FinalizeUpgradewith response fields and error semantics), license behavior, limitations, and a troubleshooting section covering the async/one-shot finalize semantics, leadership-change caveats, and theIncompatible downgrade detectedguard.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)
cc: @JakeSCahill
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 tok-rolling-upgrade.adocat page level.#1819 (DOC-2217) is stacked on this PR: it adds the shadowing-upgrade page, which xrefs
deferred-finalization.adocthroughout, and its base is this branch. Merging this PR retargets #1819 tobetaautomatically.Suggested merge order: #1816 → this PR → #1819. After #1816 merges, the Kubernetes xref here can be tightened to the
#defer-upgrade-finalizationanchor (happy to do that in this PR if #1816 lands first).Review notes
rpk cluster upgrade status|finalizeare mentioned in code font without xrefs: the reference pages arrive with the 26.2 rpk regen.tiered_v2storage mode is not yet documented on beta, so that gated-features row has no link.upgrade_override_checksbypass 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