Provide a unified configuration guide for Kubernetes #1344
Conversation
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughThis PR removes the Kubernetes cluster property configuration page and consolidates its content into the Helm/CRD configuration page. The updated page adds explicit examples for setting cluster properties via config.cluster using both Helm values and Redpanda CRDs, introduces using Secrets/ConfigMaps for sensitive values, documents exporting broker configuration with rpk, expands Console configuration examples, and clarifies reinstall behavior (PVC cleanup). Headings and phrasing are adjusted to reflect both Helm and Operator workflows, and an alias is added to preserve routing from the removed page. Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant Tooling as Helm/Operator
participant K8s as Kubernetes API
participant RP as Redpanda
%% Set cluster properties via Helm values or CRD
rect rgba(227,242,253,0.6)
note over User,RP: Set cluster properties (config.cluster)
User->>Tooling: Provide YAML values / Redpanda CRD (config.cluster)
Tooling->>K8s: Apply/Upgrade (helm upgrade / kubectl apply)
K8s->>RP: Reconcile StatefulSet/CRD to Pods
RP-->>User: Cluster properties applied (may restart if required)
end
sequenceDiagram
autonumber
actor User
participant Tooling as Helm/Operator
participant K8s as Kubernetes API
participant RP as Redpanda
%% Use Secrets/ConfigMaps for sensitive/managed values
rect rgba(232,245,233,0.6)
note over User,RP: Reference Secret/ConfigMap in config.cluster
User->>K8s: Create Secret/ConfigMap (key/value)
User->>Tooling: YAML references (secretKeyRef/configMapKeyRef)
Tooling->>K8s: Apply/Upgrade
K8s->>RP: Mount/inject and reconcile configuration
RP-->>User: Configuration resolved from Secret/ConfigMap
end
sequenceDiagram
autonumber
actor User
participant Pod as Redpanda Pod
participant rpk as rpk CLI
%% Export configuration for diagnostics
User->>Pod: Exec into Pod
User->>rpk: rpk cluster config export
rpk-->>User: broker config file output
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Assessment against linked issues
Assessment against linked issues: Out-of-scope changes
Possibly related PRs
Suggested reviewers
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ 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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![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 (1)
modules/manage/pages/kubernetes/k-configure-helm-chart.adoc (1)
450-451: Fix Redpanda Console adminApi URLs (don’t use trailing dot in FQDN)The examples use
svc.cluster.local.(with a trailing dot). While absolute DNS names are valid, many URL parsers reject the trailing dot. Recommend removing the dot.Apply this diff in all occurrences:
-- - http://redpanda-0.redpanda.<namespace>.svc.cluster.local.:9644 +- - http://redpanda-0.redpanda.<namespace>.svc.cluster.local:9644-- - http://redpanda-0.redpanda.<namespace>.svc.cluster.local.:9644 +- - http://redpanda-0.redpanda.<namespace>.svc.cluster.local:9644- --set console.console.config.redpanda.adminApi.urls={"http://redpanda-0.redpanda.<namespace>.svc.cluster.local.:9644"} + --set console.console.config.redpanda.adminApi.urls={"http://redpanda-0.redpanda.<namespace>.svc.cluster.local:9644"}Also applies to: 475-476, 489-492
🧹 Nitpick comments (4)
modules/manage/pages/kubernetes/k-configure-helm-chart.adoc (4)
148-153: Tighten precedence wording for CLI flags vs YAML values“CLI flags take precedence over the values defined in the YAML values” is a bit imprecise. Flags override settings the process derives from its config files, regardless of how those config files were rendered (Helm values or Operator). Suggest phrasing this as flags overriding Redpanda’s runtime configuration, not “YAML values”.
Apply this diff to clarify:
-You can specify Redpanda CLI flags, such as `--smp`, `--memory`, or `--reserve-memory`, directly rather than having to find the appropriate stanza in the YAML values. - -When you specify CLI flags, those values take precedence over the values defined in the YAML values. +You can specify Redpanda CLI flags, such as `--smp`, `--memory`, or `--reserve-memory`, directly rather than locating the corresponding fields in your YAML. + +At runtime, Redpanda CLI flags take precedence over values loaded from configuration files (for example, those rendered from Helm values or a Redpanda custom resource).
213-230: Add concrete Operator and Helm examples for config.cluster (currently implied only)This new section is great, but it promises examples “for both approaches” without actually including Operator/Helm wrappers for config.cluster. Adding explicit, copy‑pasteable snippets will close the DOC-786 gap.
Apply this diff to embed concrete examples:
=== Set Redpanda cluster properties Cluster properties control the core behavior of your Redpanda cluster, such as topic auto-creation, log retention, and feature flags. You can set any cluster property using the `config.cluster` field in your Helm values or Redpanda custom resource. For a full list of available properties and their defaults, see xref:reference:cluster-properties.adoc[cluster configuration properties]. -.Example: Enable automatic topic creation +.Example: Enable automatic topic creation [,yaml] ---- config: cluster: auto_create_topics_enabled: true ---- -You can set multiple properties under `config.cluster` as needed. This method works for all cluster properties, including those for advanced features like Tiered Storage. - -To set cluster properties using the Operator or Helm, add the `config.cluster` block to your YAML file or use the `--set` flag. See the examples below for both approaches. +You can set multiple properties under `config.cluster` as needed. This method works for all cluster properties, including those for advanced features like Tiered Storage. + +[tabs] +====== +Operator:: ++ +-- +.redpanda-cluster.yaml +[,yaml] +---- +apiVersion: cluster.redpanda.com/v1alpha2 +kind: Redpanda +metadata: + name: redpanda +spec: + chartRef: {} + clusterSpec: + config: + cluster: + auto_create_topics_enabled: true + log_cleanup_policy: "compact" +---- + +```bash +kubectl apply -f redpanda-cluster.yaml --namespace <namespace> +``` +-- +Helm:: ++ +-- +[tabs] +==== +--values:: ++ +.cluster-properties.yaml +[,yaml] +---- +config: + cluster: + auto_create_topics_enabled: true + log_cleanup_policy: "compact" +---- ++ +```bash +helm upgrade --install redpanda redpanda/redpanda \ + --namespace <namespace> --create-namespace \ + --values cluster-properties.yaml --reuse-values +``` + +--set:: ++ +[,bash] +---- +helm upgrade --install redpanda redpanda/redpanda \ + --namespace <namespace> --create-namespace \ + --set config.cluster.auto_create_topics_enabled=true \ + --set config.cluster.log_cleanup_policy=compact +---- +==== +-- +======
517-529: PVC cleanup: verify selector and warn about irreversible data loss
- Label selector:
-l app=redpandamay not match the PVCs created by the chart/Operator (typically labels use app.kubernetes.io/*). Use a selector users are more likely to have, or show how to discover the correct labels.- Add a warning box about data loss.
Please confirm which labels are applied to PVCs by the current chart/Operator (for example,
app.kubernetes.io/instance=<release>and/orapp.kubernetes.io/name=redpanda) and adjust the example accordingly.Apply this diff:
. Delete the existing PVCs before reinstalling Redpanda: + [,bash] ---- -kubectl delete pvc -l app=redpanda --namespace <namespace> +# WARNING: This permanently deletes data. +# Discover PVC labels: +kubectl get pvc -n <namespace> --show-labels +# Delete PVCs for the release: +kubectl delete pvc -n <namespace> -l app.kubernetes.io/instance=redpanda ----
323-367: Ensure namespace placeholder consistency forkubectl cpThe
rpk cluster config export --filenameflag is officially supported in Redpanda CLI (v24.1 and later) and can be retained as-is. However, to keep placeholder usage consistent across examples, please update thekubectl cpcommand to use the<namespace>/<pod>notation.Affected file: modules/manage/pages/kubernetes/k-configure-helm-chart.adoc (lines 323–367)
Suggested diff:
. Copy the configuration file from the Pod to your host machine: -```bash -kubectl cp redpanda/redpanda-0:<path-to-file> configs/redpanda-0-configuration-file.yaml -``` +```bash +kubectl cp <namespace>/redpanda-0:<path-to-file> configs/redpanda-0-configuration-file.yaml +```
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
modules/manage/pages/kubernetes/k-cluster-property-configuration.adoc(0 hunks)modules/manage/pages/kubernetes/k-configure-helm-chart.adoc(5 hunks)
💤 Files with no reviewable changes (1)
- modules/manage/pages/kubernetes/k-cluster-property-configuration.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 (3)
modules/manage/pages/kubernetes/k-configure-helm-chart.adoc (3)
4-4: Alias addition looks correct and preserves redirectsAdding manage:kubernetes/k-cluster-property-configuration.adoc here matches the removed page and should maintain searchability/back-compat.
369-418: I've added scripts to verify:
- Where
clusterSpec.configandconfig.clusterare referenced in the Helm chart docs.- The directory contents for CLI commands under
modules/reference/rpk/rpk-cluster.- Any “reset” subcommands or behaviors in the CLI docs.
- The usage and synopsis for
rpk cluster config set.Once we have the output, we can confirm the correct property path and whether an explicit
reset/clearexists and refine the review comment accordingly.
231-320: extraClusterConfiguration: confirm availability in 25.1+, fix Helm indentation, and add a configMapKeyRef example
- Version gating: The
config.extraClusterConfigurationfield is supported starting in the Redpanda platform 25.1 Helm Chart (chart version 25.1.1+, previously v5.10.1) and the Redpanda Operator v2.4.1+. No additional feature flags or gates are required. (docs.redpanda.com)- Helm values file indentation: Ensure your
redpanda-config.yamlsnippet begins at column 0 to match standardvalues.yamlconventions.- Add a
configMapKeyRefexample for non-sensitive values.Apply these suggested diffs:
.`redpanda-config.yaml` [,yaml] ---- -config: - extraClusterConfiguration: - iceberg_rest_catalog_client_secret: - secretKeyRef: - name: iceberg-config - key: iceberg_rest_catalog_client_secret +config: + extraClusterConfiguration: + iceberg_rest_catalog_client_secret: + secretKeyRef: + name: iceberg-config + key: iceberg_rest_catalog_client_secret ----And immediately after the Secret example, insert:
+For non-sensitive values, use `configMapKeyRef`: + +[,yaml] +---- +config: + extraClusterConfiguration: + iceberg_rest_catalog_uri: + configMapKeyRef: + name: iceberg-config + key: iceberg_rest_catalog_uri +----
Description
Resolves https://redpandadata.atlassian.net/browse/DOC-786
This pull request consolidates documentation for configuring Redpanda cluster properties in Kubernetes. The previous dedicated page for configuring cluster properties (
k-cluster-property-configuration.adoc) has been removed, and its content has been merged into the main Helm chart configuration guide (k-configure-helm-chart.adoc). The updated documentation now provides a single, comprehensive source for configuring both cluster and Kubernetes-specific settings, with improved explanations and examples for setting cluster properties, using CLI flags, and exporting configuration files.Key changes:
Documentation consolidation and navigation:
k-cluster-property-configuration.adocpage and merged its content intok-configure-helm-chart.adocfor a unified configuration guide. Updated page aliases to ensure redirects and searchability. [1] [2]Cluster property configuration improvements:
k-configure-helm-chart.adocexplaining how to set Redpanda cluster properties using theconfig.clusterfield in Helm values or Redpanda custom resources, with examples for both Helm and Operator workflows.Configuration export instructions:
These changes make it easier for users to find and follow best practices for configuring Redpanda in Kubernetes, reducing duplication and improving clarity.
Page previews
Checks