docs: deferred upgrade finalization on Kubernetes (DOC-2273)

[JakeSCahill]

Documents deferred ("unfinalized") upgrades for Kubernetes deployments (DOC-2273, eng epic ENG-1067; core feature per ENG-1029 and the TOI writeup).

Changes

• New Defer upgrade finalization section in upgrade:k-rolling-upgrade.adoc: set features_auto_finalization: false before the upgrade (26.1.9+/25.3.15+, Enterprise), roll as usual (no operator/chart changes needed), verify with rpk cluster upgrade status (real observed output), soak, then rpk cluster upgrade finalize (irreversible) — plus the three sharp caveats (config flip does not finalize; finalize requests are not persisted across controller leadership changes; one hop at a time).
• Roll back section extended: with deferred finalization you can roll back after all brokers are upgraded, until you finalize.
• Shared limitations partial (rolling-upgrades/upgrade-limitations.adoc): Rollbacks and Downgrades bullets gain the deferred-finalization exception, phrased generically because the partial also serves the Linux page (DOC-2013, Joyce).
• Troubleshooting: the Incompatible downgrade detected guard after finalization, why the roll halts at the first refused broker, and the validated recovery (set the image forward; deleting the crash-looping Pod does not help because the StatefulSet recreates it at the old revision).

Validation (kind v1.34.0, operator 26.2.1-beta.3, 3 brokers)

Full loop verified live: 26.1.13 with the flag set → roll to 26.2.1-rc4 → ready to finalize → image-tag rollback to 26.1.13 (cluster healthy on old binary) → re-upgrade → finalize → finalized on first poll → downgrade attempt refused with the guard signature, roll halted at broker 0 while the cluster stayed available → recovery by setting the image forward.

Coordination

• DOC-2013 (Joyce) owns the concept page and Linux procedure; the shared partial change here is written to serve both. The features_auto_finalization property reference already exists; the rpk cluster upgrade reference pages come with the 26.2 rpk regen.
• GA framing per release decision: no beta/RC mentions.

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	ae4c7e4
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a5fa732857d94000805d99a
😎 Deploy Preview	https://deploy-preview-1816--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]

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: 816d1553-5bbb-44f2-bc97-3422e4142f89

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-2273-unfinalized-upgrades

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[Feediver1]

Review: deferred upgrade finalization on Kubernetes (DOC-2273)

Overview

Adds a "Defer upgrade finalization" procedure to upgrade:k-rolling-upgrade.adoc (property flip → normal roll → verify ready to finalize → soak → manual finalize), extends the Roll back section with the unfinalized-rollback window, adds a troubleshooting entry for the post-finalization downgrade guard, and updates the shared limitations partial that serves both the Kubernetes and Linux pages. Targets beta (26.2).

Verified — this all checks out

• Coordination with DOC-2013 is clean. docs: defer upgrade finalization (DOC-2013) #1818 merged to beta, and its concept page's "Deferred finalization in Kubernetes" section points readers at k-rolling-upgrade.adoc for the procedure — this PR fills exactly that target. The content agrees on every point of overlap: operator/chart are finalization-unaware, the property is set through normal cluster config, finalize is manual, rollback is via image tag.
• Facts are consistent with the merged concept page: version floors (26.1.9 / 25.3.15), 26.2+ target, Enterprise license requirement, one-feature-release-at-a-time, and the finalize-then-restore-the-property ordering all match.
• No merge hazards. The PR is MERGEABLE; docs: defer upgrade finalization (DOC-2013) #1818 did not touch the limitations partial, so the Rollbacks/Downgrades edits apply cleanly with no double-documentation. The generic phrasing works for the Linux page too.
• All references resolve on beta: the in-page anchors (<<Perform a rolling upgrade>>, <<Roll back>>), the features_auto_finalization xref (documented via reference/partials/properties/cluster-properties.adoc, included into the target page), and the rpk cluster upgrade reference pages (already on beta, not waiting on the rpk regen as the PR body hedges).
• The reworded Downgrades bullet ("not supported after the upgrade is finalized") is a nice touch — it's accurate for auto-finalized upgrades as well, so the partial stays correct for readers who never defer.

One real suggestion: link back to the concept page

The new section never xrefs upgrade:deferred-finalization.adoc, even though the concept page links here and owns the material this section compresses: what's unavailable while unfinalized, license behavior, the Admin API alternative, and the full rollback discussion. One sentence in the section intro — e.g. "For how finalization works and what is unavailable while unfinalized, see xref:upgrade:deferred-finalization.adoc[]." — and optionally pointing the soak-test bullet ("configuration that depends on them reports that it cannot be configured…") at the concept page's gated-features anchor. Without it, the two pages are reciprocally invisible in one direction, and this section will drift as the concept page evolves.

Minor

• The Rollbacks and Downgrades bullets in the partial now state the same deferred-finalization exception twice in adjacent bullets. Defensible (readers scan one bullet, not both), but the Downgrades sentence could be trimmed to "…is not supported after the upgrade is finalized. See Rollbacks." if you want less repetition.

Risks

Low. Docs-only, validated live per the PR body (the troubleshooting recovery path — image forward, not pod deletion — is the kind of detail that only comes from having actually run it). The shared-partial edit is the only cross-page surface, and it's phrased to serve both consumers.

Verdict: accurate, well-validated, and correctly coordinated with the merged DOC-2013 work — good to merge once the concept-page xref is added.

🤖 Generated with Claude Code

[Feediver1]

Check out the suggestion