Add NodePool CRD docs and Kubernetes lifecycle management nav

[david-yu]

Summary

• Add NodePool CRD (v1alpha2) concept page under Manage > Kubernetes
• Add blue/green migration how-to using NodePool CRD under Upgrade
• Rename existing manual migration page (k-upgrade-kubernetes.adoc → k-migrate-node-pools-manually.adoc) with aliases for old URLs
• Add Cluster Maintenance landing page grouping Node Pools, PVCUnbinder, Decommission Brokers, Recovery Mode, and Rolling Restart
• Add NodePool CRD (beta) entry to Operator v26.1.x release notes
• Restructure nav.adoc accordingly

JIRA: DOC-2097

Preview pages

• Node Pools (new)
• Migrate Node Pools (Experimental) (new)
• Migrate Node Pools Manually (renamed)
• Cluster Maintenance (new)
• What's New in the Redpanda Operator (updated)
• Scale (updated - NodePool xref)
• Decommission Brokers (updated - NodePool xref)
• Manage Topics (updated includes)
• Manage Schemas (updated includes)
• Schema Registry ACLs (minor edit)

Test plan

• Verify all new pages render correctly in Antora preview
• Verify old URLs (/upgrade/k-upgrade-kubernetes/, /manage/kubernetes/k-upgrade-kubernetes/) redirect via page aliases
• Verify nav structure shows Node Pools, Cluster Maintenance section, and both migration pages
• Verify Mermaid flowchart renders on the Migrate Node Pools page
• Verify xrefs across all new pages resolve correctly
• Verify NodePool CRD (beta) entry appears in Operator release notes

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	c9598c3
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/69deada86afb590008e3e521
😎 Deploy Preview	https://deploy-preview-1667--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 incremental reviews are disabled on this repository.

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: 8fddc269-99af-44e2-b4de-cbca4a52ca9e

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

📝 Walkthrough

Walkthrough

This pull request reorganizes Kubernetes documentation and adds test coverage for CRD features. The navigation structure is updated to add a new top-level node pools entry and consolidate lifecycle operations (decommissioning, recovery mode, rolling restart) under a shared index page. Two new comprehensive documentation pages are added: one introducing the NodePool CRD feature and another describing the automated blue/green migration workflow. The upgrade section now includes dedicated pages for both automated and manual node pool migration strategies. Test coverage is expanded with new BDD scenarios in feature files for Schema and Topic CRDs, and existing documentation is refactored to reference these feature examples instead of embedding inline YAML manifests. Metadata and navigation aliases are updated to support the restructured documentation paths.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• docs (k8s): Move inline YAML examples to feature files for schema and topic controllers #1650: Directly applies the same pattern of refactoring inline YAML examples from documentation pages (k-schema-controller.adoc, k-manage-topics.adoc) into tagged feature file examples
• docs (k8s): Add CRD source file references to CRD index page #1634: Modifies NodePool CRD documentation and references in source file indices related to the new NodePool documentation page
• docs (k8s): Add Cloud Topics for Kubernetes #1631: Updates Kubernetes documentation navigation structure and adds pages under modules/manage/pages/kubernetes, following similar organizational changes

Suggested reviewers

• micheleRP
• JakeSCahill

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: adding NodePool CRD documentation and restructuring Kubernetes lifecycle management navigation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The pull request provides a clear, well-structured description with JIRA reference, preview links, and test plan.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}

[coderabbitai]

🧹 Nitpick comments (5)

modules/manage/pages/kubernetes/lifecycle/index.adoc (1)

14-26: Standardize xrefs to auto-title style.

These links hard-code display text; switch to xref:...[] to keep titles source-of-truth and reduce drift after page-title updates.

♻️ Proposed cleanup

-See xref:manage:kubernetes/k-decommission-brokers.adoc[Decommission Brokers].
+See xref:manage:kubernetes/k-decommission-brokers.adoc[].

-See xref:manage:kubernetes/tiered-storage/k-recovery-mode.adoc[Recovery Mode].
+See xref:manage:kubernetes/tiered-storage/k-recovery-mode.adoc[].

-See xref:manage:kubernetes/k-rolling-restart.adoc[Rolling Restart].
+See xref:manage:kubernetes/k-rolling-restart.adoc[].

Based on learnings: AsciiDoc linking should prefer xref:...[] so link text is pulled from target page titles automatically.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/manage/pages/kubernetes/lifecycle/index.adoc` around lines 14 - 26,
Update the three hard-coded xref links so their display text is pulled from the
target page titles by switching from explicit labels to auto-title form: replace
xref:manage:kubernetes/k-decommission-brokers.adoc[Decommission Brokers],
xref:manage:kubernetes/tiered-storage/k-recovery-mode.adoc[Recovery Mode], and
xref:manage:kubernetes/k-rolling-restart.adoc[Rolling Restart] with
xref:manage:kubernetes/k-decommission-brokers.adoc[],
xref:manage:kubernetes/tiered-storage/k-recovery-mode.adoc[], and
xref:manage:kubernetes/k-rolling-restart.adoc[] respectively so the pages
(Recovery mode, Rolling restart) always derive their link text from the target
page titles.

modules/upgrade/pages/k-migrate-node-pools-manually.adoc (1)

10-10: Use auto-title xref for consistency.

Prefer xref:upgrade:k-migrate-node-pools.adoc[] here instead of hard-coded link text.

Based on learnings: AsciiDoc linking should prefer xref:...[] to render target titles automatically.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/upgrade/pages/k-migrate-node-pools-manually.adoc` at line 10, Replace
the hard-coded link text in
modules/upgrade/pages/k-migrate-node-pools-manually.adoc that currently uses
xref:upgrade:k-migrate-node-pools.adoc[NodePool CRD] with the auto-title form
xref:upgrade:k-migrate-node-pools.adoc[] so the target title is rendered
automatically; update the single NOTE line containing the link to use
xref:upgrade:k-migrate-node-pools.adoc[] (preserving surrounding punctuation) to
ensure consistent AsciiDoc linking across the docs.

modules/upgrade/pages/k-migrate-node-pools.adoc (1)

61-61: Align xref style with repo convention.

Use xref:...[] for these internal links to avoid duplicated/possibly stale link text.

Based on learnings: AsciiDoc linking should prefer empty-bracket xrefs so titles come from the referenced page.

Also applies to: 65-67, 266-269

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/upgrade/pages/k-migrate-node-pools.adoc` at line 61, Replace explicit
link text in AsciiDoc xrefs with the repo-conventional empty-bracket form: find
occurrences like xref:manage:kubernetes/k-node-pools.adoc[Node Pools] (and the
similar links at the other reported occurrences) and change them to
xref:manage:kubernetes/k-node-pools.adoc[] so the target page title is used
automatically; update every instance noted (lines near the current instance plus
the other groups reported) and verify the rendered titles remain correct.

modules/manage/pages/kubernetes/k-node-pools.adoc (1)

33-33: Consider converting these xrefs to empty-bracket form.

This page has several hard-coded xref labels; switching to xref:...[] will keep links aligned automatically if target page titles change.

Based on learnings: AsciiDoc linking should prefer xref:...[] instead of hard-coded link text.

Also applies to: 61-61, 65-67, 142-145, 149-151

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/manage/pages/kubernetes/k-node-pools.adoc` at line 33, Replace
hard-coded xref link text with empty-bracket xrefs so links auto-update when
targets change: update occurrences like
xref:upgrade:k-migrate-node-pools.adoc[Migrate Node Pools] to
xref:upgrade:k-migrate-node-pools.adoc[] and do the same for the other xref
instances referenced in this file (the links at the ranges mentioned), ensuring
you keep the same xref targets (e.g., k-migrate-node-pools.adoc) but remove the
explicit bracketed label.

modules/manage/examples/kubernetes/topic-crds.feature (1)

30-79: Add explicit assertions for Topic config reconciliation.

These scenarios prove topic creation works, but they don’t directly verify that additionalConfig was applied (write.caching and cleanup.policy). Add config-level checks so the tests fail if reconciliation regresses.

Suggested test-strengthening diff

   Scenario: Manage topic with write caching
@@
     And topic "chat-room" is successfully synced
+    And topic "chat-room" in cluster "basic" has config "write.caching" set to "true"
     Then I should be able to produce and consume from "chat-room" in cluster "basic"

   Scenario: Manage topic with cleanup policy
@@
     And topic "delete-policy-topic" is successfully synced
+    And topic "delete-policy-topic" in cluster "basic" has config "cleanup.policy" set to "delete"
     Then I should be able to produce and consume from "delete-policy-topic" in cluster "basic"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/manage/examples/kubernetes/topic-crds.feature` around lines 30 - 79,
Add explicit assertions after the "And topic ... is successfully synced" step to
fetch the Topic CR for "chat-room" and "delete-policy-topic" and assert that
.spec.additionalConfig contains the expected keys and values (write.caching:
"true" for Topic named chat-room; cleanup.policy: "delete" for
delete-policy-topic). Locate the reconciliation verification logic used by the
step "topic ... is successfully synced" (or the step definition that queries the
Topic CR) and extend it to explicitly check .spec.additionalConfig entries for
the unique keys write.caching and cleanup.policy so the scenario fails if those
config values are not applied.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@modules/manage/examples/kubernetes/topic-crds.feature`:
- Around line 30-79: Add explicit assertions after the "And topic ... is
successfully synced" step to fetch the Topic CR for "chat-room" and
"delete-policy-topic" and assert that .spec.additionalConfig contains the
expected keys and values (write.caching: "true" for Topic named chat-room;
cleanup.policy: "delete" for delete-policy-topic). Locate the reconciliation
verification logic used by the step "topic ... is successfully synced" (or the
step definition that queries the Topic CR) and extend it to explicitly check
.spec.additionalConfig entries for the unique keys write.caching and
cleanup.policy so the scenario fails if those config values are not applied.

In `@modules/manage/pages/kubernetes/k-node-pools.adoc`:
- Line 33: Replace hard-coded xref link text with empty-bracket xrefs so links
auto-update when targets change: update occurrences like
xref:upgrade:k-migrate-node-pools.adoc[Migrate Node Pools] to
xref:upgrade:k-migrate-node-pools.adoc[] and do the same for the other xref
instances referenced in this file (the links at the ranges mentioned), ensuring
you keep the same xref targets (e.g., k-migrate-node-pools.adoc) but remove the
explicit bracketed label.

In `@modules/manage/pages/kubernetes/lifecycle/index.adoc`:
- Around line 14-26: Update the three hard-coded xref links so their display
text is pulled from the target page titles by switching from explicit labels to
auto-title form: replace
xref:manage:kubernetes/k-decommission-brokers.adoc[Decommission Brokers],
xref:manage:kubernetes/tiered-storage/k-recovery-mode.adoc[Recovery Mode], and
xref:manage:kubernetes/k-rolling-restart.adoc[Rolling Restart] with
xref:manage:kubernetes/k-decommission-brokers.adoc[],
xref:manage:kubernetes/tiered-storage/k-recovery-mode.adoc[], and
xref:manage:kubernetes/k-rolling-restart.adoc[] respectively so the pages
(Recovery mode, Rolling restart) always derive their link text from the target
page titles.

In `@modules/upgrade/pages/k-migrate-node-pools-manually.adoc`:
- Line 10: Replace the hard-coded link text in
modules/upgrade/pages/k-migrate-node-pools-manually.adoc that currently uses
xref:upgrade:k-migrate-node-pools.adoc[NodePool CRD] with the auto-title form
xref:upgrade:k-migrate-node-pools.adoc[] so the target title is rendered
automatically; update the single NOTE line containing the link to use
xref:upgrade:k-migrate-node-pools.adoc[] (preserving surrounding punctuation) to
ensure consistent AsciiDoc linking across the docs.

In `@modules/upgrade/pages/k-migrate-node-pools.adoc`:
- Line 61: Replace explicit link text in AsciiDoc xrefs with the
repo-conventional empty-bracket form: find occurrences like
xref:manage:kubernetes/k-node-pools.adoc[Node Pools] (and the similar links at
the other reported occurrences) and change them to
xref:manage:kubernetes/k-node-pools.adoc[] so the target page title is used
automatically; update every instance noted (lines near the current instance plus
the other groups reported) and verify the rendered titles remain correct.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fff41847-0d75-4113-b21b-047525a0b0cf

📥 Commits

Reviewing files that changed from the base of the PR and between 1d14295 and 8198aea.

📒 Files selected for processing (10)

• modules/ROOT/nav.adoc
• modules/manage/examples/kubernetes/schema-crds.feature
• modules/manage/examples/kubernetes/topic-crds.feature
• modules/manage/pages/kubernetes/k-manage-topics.adoc
• modules/manage/pages/kubernetes/k-node-pools.adoc
• modules/manage/pages/kubernetes/k-schema-controller.adoc
• modules/manage/pages/kubernetes/lifecycle/index.adoc
• modules/manage/pages/kubernetes/security/authentication/k-schema-registry-acls.adoc
• modules/upgrade/pages/k-migrate-node-pools-manually.adoc
• modules/upgrade/pages/k-migrate-node-pools.adoc

[micheleRP]

Impact on other files

Files NOT in this PR that may need updates:

• modules/deploy/partials/requirements.adoc:84: Contains xref:upgrade:k-upgrade-kubernetes.adoc[How to manually manage node upgrades] referencing the old filename. This will resolve via the page-aliases redirect, but should be updated to xref:upgrade:k-migrate-node-pools-manually.adoc[...] for clarity and to avoid relying on a redirect for internal content.

• Operator release notes (modules/get-started/pages/release-notes/operator.adoc): The Operator release notes page documents v26.1.x features but has no mention of the NodePool CRD. As a significant new (experimental) feature, it should have an entry under the v26.1.x section.

• Scale page (modules/manage/pages/kubernetes/k-scale-redpanda.adoc): The scaling page discusses vertical scaling and moving brokers to new worker nodes — exactly what NodePools facilitate. A cross-reference to the new Node Pools page would help users discover the feature.

• Decommission page (modules/manage/pages/kubernetes/k-decommission-brokers.adoc): The decommission page's "Suggested reading" section could benefit from a link to the NodePool CRD page, since NodePool-based migration automates decommissioning.

[david-yu]

Thanks I'll address those comments @micheleRP

[micheleRP]

Suggestion: Lost line highlighting in code examples

File: modules/manage/pages/kubernetes/k-manage-topics.adoc

The old inline code blocks used [,yaml,lines=9] and [,yaml,lines=8-9] to highlight the key config lines (write.caching and cleanup.policy). The new include:: versions dropped this highlighting.

This is a tradeoff — the DRY approach of sourcing from test feature files is a clear win for maintainability. If line highlighting is important for reader clarity, it could be re-added, but the line numbers would need to stay in sync with the included content.

No action needed if the DRY benefit outweighs the highlighting.

[david-yu]

Suggestion: Lost line highlighting in code examples

File: modules/manage/pages/kubernetes/k-manage-topics.adoc

The old inline code blocks used [,yaml,lines=9] and [,yaml,lines=8-9] to highlight the key config lines (write.caching and cleanup.policy). The new include:: versions dropped this highlighting.

This is a tradeoff — the DRY approach of sourcing from test feature files is a clear win for maintainability. If line highlighting is important for reader clarity, it could be re-added, but the line numbers would need to stay in sync with the included content.

No action needed if the DRY benefit outweighs the highlighting.

I don't think any action is needed on those examples.

[micheleRP]

PR Review: Add NodePool CRD docs and Kubernetes lifecycle management nav (#1667)

Files reviewed: 9 files (5 new/renamed .adoc files, 4 modified)
Overall assessment: Well-structured PR with comprehensive NodePool CRD documentation and sensible nav reorganization. Two issues need attention before merge: the lifecycle landing page renders duplicate content, and the mermaid diagram renders small due to a CSS conflict in the UI bundle.

What this PR does

Adds two new pages documenting the NodePool CRD (beta): a concept page explaining what NodePools are and how to enable them, and a how-to for blue/green migration using NodePools. Renames the existing manual migration page (k-upgrade-kubernetes.adoc → k-migrate-node-pools-manually.adoc) with proper aliases. Creates a new "Cluster Maintenance" landing page and restructures the Kubernetes nav. Updates operator release notes with the NodePool CRD beta entry.

Jira ticket alignment

Ticket: DOC-2097 — Add NodePool CRD documentation and restructure Kubernetes lifecycle management
Status: PR fully addresses the ticket requirements. All pages, nav changes, and release notes listed in the ticket are present.

Critical issues (must fix)

1. [lifecycle/index.adoc] Duplicate content on the Cluster Maintenance landing page. The page has :page-layout: index (which auto-generates navigation cards from nav children) AND manual H2 sections describing each child page. This renders the same information twice — once as article sections, then again as auto-generated cards below. Remove the H2 sections and keep just the intro paragraph, matching the pattern used by other index pages like shadowing/index.adoc.

Suggestions (should consider)

1. [k-migrate-node-pools.adoc: "How it works" diagram] The mermaid flowchart renders small/squished because the site CSS applies aspect-ratio: 16/9 to all .doc .imageblock svg elements, which forces the tall vertical flowchart TB diagram into a wide shape. Two options:

   • Quick fix for this PR: Change flowchart TB to flowchart LR so the diagram flows horizontally and fits the 16:9 constraint naturally.
   • Long-term fix: The docs-ui repo needs .mermaid > svg { aspect-ratio: auto !important; } added to mermaid.css — note that Add click-to-zoom feature for Mermaid diagrams docs-ui#374 does not currently include this fix.

2. [k-decommission-brokers.adoc:673] The added xref description is slightly misleading — NodePools are about migration, not decommissioning.

   • Current: Automate broker decommissioning through NodePool-based blue/green migrations.
   • Suggested: Manage groups of brokers independently for blue/green migrations and vertical scaling.

3. [k-scale-redpanda.adoc:139] Same wording issue in the Suggested Reading entry.

   • Current: Automate broker decommissioning through NodePool-based blue/green migrations.
   • Suggested: Manage groups of brokers independently for blue/green migrations and vertical scaling.

Impact on other files

No missing updates detected:

• Nav entries present for all new pages
• Operator release notes updated
• requirements.adoc partial updated with new filename
• Page aliases cover all three old URL patterns
• Scale and Decommission Brokers pages have contextual xrefs

CodeRabbit findings worth considering

CodeRabbit suggested switching hard-coded xref display text to auto-title style on the lifecycle landing page. Moot if the H2 sections are removed per critical issue #1.

What works well

• Clean blue/green migration walkthrough with collapsible expected outputs and anchor-linked sections from the diagram
• Good use of :page-beta: true and CAUTION admonitions for experimental status
• "Migrate an existing cluster to NodePools" and "Remove NodePools" sections provide complete adoption and rollback paths
• Pre-migration considerations (cost, data volume, replication factor) are practical
• Page aliases are comprehensive — no broken URLs from the rename
• Nav fix: corrects the Recovery Mode xref from the wrong path (kubernetes/k-recovery-mode.adoc) to the actual location (kubernetes/tiered-storage/k-recovery-mode.adoc)

[micheleRP]

thanks @david-yu!