DOC-1459 Document new cluster scope default for Redpanda Operator 25.2 #1271
Conversation
Co-authored-by: Chris Seto <[email protected]> Co-authored-by: Michele Cyran <[email protected]>
Co-authored-by: Michele Cyran <[email protected]>
Co-authored-by: Paulo Borges <[email protected]> Co-authored-by: Joyce Fee <[email protected]> Co-authored-by: Paulo Borges <[email protected]>
Co-authored-by: Michele Cyran <[email protected]>
…t-kafka-javascript (#1205) Co-authored-by: Joyce Fee <[email protected]>
Co-authored-by: Jake Cahill <[email protected]>
Co-authored-by: Michele Cyran <[email protected]>
Co-authored-by: Jake Cahill <[email protected]>
Co-authored-by: Joyce Fee <[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 incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis PR removes the 25.2 beta Kubernetes deployment page and its nav entry, consolidates content into production docs, and updates guidance to reflect Redpanda Operator defaulting to cluster scope in v25.2. It adds page aliases, introduces cluster- vs namespace-scoped deployment instructions, and expands multi-cluster deployment examples (Operator and Helm). It updates release notes with migration/RBAC guidance, refactors operator deployment/upgrade partials, adjusts the Kubernetes compatibility matrix for 25.2, and revises related docs (migration, rack awareness, troubleshoot) to align with the new scope and RBAC model. Sequence Diagram(s)sequenceDiagram
autonumber
actor U as User
participant H as Helm (repo/charts)
participant K as Kubernetes API
participant O as Redpanda Operator
participant CR as Redpanda CR (namespace-scoped)
participant RP as Redpanda Pods
rect rgba(220,240,255,0.4)
note right of U: Choose Operator scope (v25.2+ defaults to Cluster scope)
U->>H: helm repo add/update
U->>H: helm install redpanda-operator<br/>--version 25.2.0<br/>--set crds.enabled=true<br/>[+ optional namespace-scope flag]
H->>K: Install CRDs & Operator Deployment
K-->>U: Operator rollout status
end
rect rgba(235,255,235,0.4)
U->>K: kubectl apply -f redpanda-cluster.yaml
note over CR: metadata.namespace=<cluster-namespace>
K->>O: Emit events for Redpanda CR
O->>K: Create StatefulSet/Services/Secrets
K->>RP: Schedule Pods in target namespace
U-->>K: kubectl get redpanda/pods --namespace <cluster-namespace>
end
rect rgba(255,245,220,0.5)
note over O: Multi-cluster: ensure unique external ports per cluster and distinct namespaces
end
sequenceDiagram
autonumber
actor U as User
participant H as Helm (repo/charts)
participant K as Kubernetes API
participant O as Redpanda Operator (Upgrade)
rect rgba(240,240,255,0.5)
U->>H: helm get values redpanda-operator -n <ns> > values.yaml
note right of U: Backup overrides
U->>H: helm repo add/update redpanda
U->>H: helm upgrade redpanda-operator redpanda/operator<br/>--version 25.2.0<br/>--set crds.enabled=true<br/>-f values.yaml
H->>K: Apply chart upgrade & CRD updates
K-->>U: kubectl rollout status deployment/redpanda-controller-operator
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Assessment against linked issues
Assessment against linked issues: Out-of-scope changes
Possibly related PRs
Suggested reviewers
✨ Finishing Touches🧪 Generate 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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
modules/upgrade/pages/k-compatibility.adoc (1)
48-53: Table row is misaligned (missing the Operator cell); renders incorrectly.The 25.1.x row has only 5 cells after the row head, shifting “3.12+” into the Operator column. Fix by adding the missing Operator version or merging this intent into the 25.1 block below.
Suggested fix (option A: keep the row and add Operator value):
-|25.1.x -|25.2-beta1, 25.1.x -|25.2-beta1, 25.1.x -|3.12+ -d|1.28.x - 1.33.x{fn-k8s-compatibility} +|25.1.x +|25.2-beta1, 25.1.x +|25.2-beta1, 25.1.x +|25.1.x +|3.12+ +d|1.28.x - 1.33.x{fn-k8s-compatibility}Option B: drop this row entirely and fold any “25.2-beta1” compatibility into the first line under the
.3+|25.1.xblock to avoid duplication.modules/upgrade/pages/k-upgrade-operator.adoc (1)
21-31: Upgrade command omits restored overrides; likely to break deployments.You back up values in the prior step but don’t reuse them here. Include
--reuse-valuesor pass the backup file with-fto ensure parity post-upgrade.Suggested fix:
-helm upgrade redpanda-controller redpanda/operator \ +helm upgrade redpanda-controller redpanda/operator \ --namespace <namespace> \ - --version <operator-version> \ - --set crds.enabled=true + --version <operator-version> \ + --set crds.enabled=true \ + --reuse-values +# Or, if you prefer explicit files: +# -f redpanda-operator-values-backup.yamlAlso, if users rely on namespace-scope, remind them to preserve
additionalCmdFlagsduring upgrade.
🧹 Nitpick comments (15)
modules/troubleshoot/partials/debug-bundle/generate-rpk.adoc (4)
51-51: Confirm removal of Operator Helm flag note; add a short clarifier for v25.2You removed the note about
--set rbac.createRPKBundleCRs=true. If Operator v25.2+ no longer requires this and RBAC is handled via the Redpanda cluster’srbac.enabled, add a one‑line clarifier so upgrades aren’t confusing.@@ kubectl apply -f redpanda-cluster.yaml --namespace <namespace> +NOTE: With Redpanda Operator v25.2+, you don’t need the Operator Helm flag `rbac.createRPKBundleCRs`; enable RBAC for the Redpanda cluster as shown above.
71-73: Use a namespace placeholder consistentlyEarlier you use
<namespace>, but here it’s hardcoded toredpanda. Align for consistency.-helm upgrade --install redpanda redpanda/redpanda --namespace redpanda --create-namespace \ +helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \ --values serviceaccount.yaml --reuse-values
91-92: ServiceAccount name may not bedefaultAbove you create a ServiceAccount (likely named
redpanda). Bindingredpanda:defaultmay be wrong. Suggest placeholder or align with the created SA.-kubectl create clusterrolebinding redpanda --clusterrole=view --serviceaccount=redpanda:default +kubectl create clusterrolebinding redpanda --clusterrole=view --serviceaccount=<namespace>:<serviceaccount-name> +# If following the values above, this is often: +# --serviceaccount=<namespace>:redpanda
24-25: Wording: not strictly “Create a ClusterRole”The YAML enables RBAC via chart/CR; it doesn’t directly define a ClusterRole. Small wording tweak improves accuracy.
-. Create a ClusterRole to allow Redpanda to collect information from the Kubernetes API: +. Grant RBAC permissions so Redpanda can read from the Kubernetes API:modules/deploy/pages/redpanda/kubernetes/k-deployment-overview.adoc (2)
41-45: Multi-tenancy row reads well; aligns with cluster-scope default.Nice clarity on single-operator, multi-namespace management. Consider adding an inline xref to the production deployment section that explains scope trade-offs for quick follow-through.
53-54: Good: call out cluster-scope default explicitly.This is crisp and accurate. Optionally add a short sentence pointing to instructions for opting into namespace scope to close the loop.
modules/deploy/partials/kubernetes/deploy-operator.adoc (2)
1-1: Scope oflatest-operator-versionattribute.Defining this attribute inside the partial limits its visibility to pages that include it. Other pages (for example, release notes) referencing
{latest-operator-version}may render incorrectly unless they also define it or inherit from a global attributes file. Consider moving it to a global attributes source (e.g., antora.yml or a shared attributes file).
21-36: Namespace-scope flag name needs confirmation.
additionalCmdFlags=["--namespace=<cluster-namespace>"]assumes the underlying controller uses--namespace. Some controllers use--watch-namespace. Please verify the exact flag for Operator v25.2 and update the example if needed. Also consider linking to the chart’s values reference foradditionalCmdFlags.modules/get-started/pages/release-notes/operator.adoc (2)
28-37: Migration guidance reads well; add one small clarification.Explicitly state that existing namespace-scoped Operator deployments keep working, but after upgrade you should decommission extras to avoid mixed scopes. This prevents readers inferring an immediate behavior change on their running Operators.
40-46: “ClusterRole always required” — confirm chart behavior.In namespace scope, ensure the Helm chart indeed creates ClusterRole/ClusterRoleBinding (and not only Role/RoleBinding) and that this is intentional for features like bundle collection. A short link to the chart RBAC templates would help.
modules/migrate/pages/kubernetes/helm-to-operator.adoc (2)
141-151: Namespace handling consistency.Here you apply the CR with
--namespace <namespace>while the CR example omitsmetadata.namespace. That’s fine. Consider adding a note that you can alternatively setmetadata.namespacein the CR and omit the CLI flag, to mirror the production deployment page.
81-89: RBAC check command: tighten the resource name.For cluster-scoped verification, consider using the full resource group:
customresourcedefinitions.apiextensions.k8s.io. Example:kubectl auth can-i create customresourcedefinitions.apiextensions.k8s.io --all-namespacesThis avoids ambiguity on clusters with strict RBAC auditing.
modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc (3)
32-38: Good warning; add cross-link for emphasis.Optionally link to the Operator release notes’ warning about mixed scopes to reinforce the guidance.
268-276: Multi-cluster Operator example: clarify which ports must be unique.Only externally exposed ports (NodePorts/LoadBalancers) need to be unique cluster-wide. Internal service/container ports like RPC typically don’t conflict unless using hostNetwork. Consider clarifying to reduce unnecessary RPC changes. Also, please verify the property names (
advertisedPorts, listeners schema) against the CRD/values.Also applies to: 281-319, 321-334
340-406: Multi-cluster Helm example mirrors Operator path well.Values overrides and uniqueness guidance look good. Minor: consider noting the default NodePort range (30000–32767) to help users pick valid ports.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (12)
modules/ROOT/nav.adoc(0 hunks)modules/deploy/pages/redpanda/kubernetes/k-25.2-beta.adoc(0 hunks)modules/deploy/pages/redpanda/kubernetes/k-deployment-overview.adoc(2 hunks)modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc(9 hunks)modules/deploy/partials/kubernetes/deploy-operator.adoc(2 hunks)modules/get-started/pages/release-notes/operator.adoc(2 hunks)modules/manage/pages/kubernetes/k-rack-awareness.adoc(0 hunks)modules/migrate/pages/kubernetes/helm-to-operator.adoc(2 hunks)modules/troubleshoot/partials/debug-bundle/generate-rpk.adoc(1 hunks)modules/troubleshoot/partials/errors-and-solutions.adoc(0 hunks)modules/upgrade/pages/k-compatibility.adoc(3 hunks)modules/upgrade/pages/k-upgrade-operator.adoc(1 hunks)
💤 Files with no reviewable changes (4)
- modules/ROOT/nav.adoc
- modules/manage/pages/kubernetes/k-rack-awareness.adoc
- modules/deploy/pages/redpanda/kubernetes/k-25.2-beta.adoc
- modules/troubleshoot/partials/errors-and-solutions.adoc
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-07-14T19:28:43.296Z
Learnt from: Feediver1
PR: redpanda-data/docs#1153
File: antora.yml:3-5
Timestamp: 2025-07-14T19:28:43.296Z
Learning: In Redpanda docs, during beta releases, the version metadata may intentionally show inconsistencies where the header displays the beta version (e.g., 25.2 Beta) while internal attributes like full-version, latest-redpanda-tag, operator-beta-tag still reference the stable version (e.g., 25.1). This is resolved during the GA merge process when all version references are synchronized.
Applied to files:
modules/upgrade/pages/k-compatibility.adocmodules/get-started/pages/release-notes/operator.adoc
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - redpanda-docs-preview
- GitHub Check: Header rules - redpanda-docs-preview
- GitHub Check: Pages changed - redpanda-docs-preview
🔇 Additional comments (13)
modules/upgrade/pages/k-compatibility.adoc (3)
16-16: Versioning scheme statement looks correct.Clear and consistent with the aligned versioning introduced in 25.1.1.
40-46: 25.2 row LGTM.Cell alignment and footnote usage are correct; ranges/readability are good.
131-138: Console v3 compatibility section consistent with release notes.“Not yet supported” under Operator matches the Operator RN note. Please confirm this remains accurate for the GA you’re shipping with this PR.
modules/deploy/partials/kubernetes/deploy-operator.adoc (1)
12-19: Install snippet and footnotes look good.Pinning and CRD installation flags are correct and the explanatory notes are helpful.
modules/get-started/pages/release-notes/operator.adoc (1)
12-12: Console v3 availability note: verify currency.The statement is clear. Please re-check against the current Operator release to ensure it’s still accurate at publish time.
modules/migrate/pages/kubernetes/helm-to-operator.adoc (1)
91-94: Good include of operator deployment; matches 25.2 behavior.Nice reuse of the partial to keep instructions consistent.
modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc (5)
4-4: Alias for retired beta doc is good.Helps preserve external links.
21-22: Scope explanation is clear.Nice concise differentiation between cluster and namespace scope.
84-109: CR example with metadata.namespace is helpful.The bullet clarifying namespace requirements per scope is excellent.
117-118: Command updates are consistent with CR-based namespace selection.Dropping
--namespaceon apply and scoping subsequent queries by namespace look correct.Also applies to: 123-136, 143-146
410-410: Important note is valuable.Good placement to cap the multi-cluster section.
modules/upgrade/pages/k-upgrade-operator.adoc (2)
10-11: Good: defer to the central compatibility matrix.Prevents drift across pages.
42-51: Rollout verification is correct.Command and sample output are consistent with the deployment name used elsewhere.
Description
Previously approved in #1230 and reopened because the base branch was deleted
Resolves https://redpandadata.atlassian.net/browse/DOC-1459
Resolves https://redpandadata.atlassian.net/browse/DOC-1499
Review deadline: July 28
This pull request updates the documentation for deploying and managing Redpanda in Kubernetes, focusing on changes introduced in Redpanda Operator v25.2. Key updates include the transition to cluster-scoped deployments by default, improved multi-tenancy management, and adjustments to RBAC requirements.
Updates to Redpanda Operator Deployment and Management:
Cluster Scope as Default:
Multi-Tenancy Enhancements:
RBAC and Compatibility Adjustments:
Migration and Upgrade Considerations:
Migration from Namespace Scope:
Versioning and Compatibility:
These updates provide a more streamlined and scalable approach to managing Redpanda in Kubernetes, particularly for environments with multiple clusters.
Page previews
Checks