Add Kubernetes secure bootstrap documentation#1668
Conversation
✅ 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 ⚙️ 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:
📝 WalkthroughWalkthroughThis pull request adds documentation for the bootstrap superuser feature in Redpanda's Kubernetes deployments with authentication enabled. Two documentation files are updated: one adds a "Secure bootstrap" subsection with a YAML configuration example showing the Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
Add documentation for auth.sasl.bootstrapUser configuration to enable secure by default cluster deployments with authentication enforced from the first startup. Changes: - Add secure bootstrap section to k-production-deployment.adoc showing quick example configuration - Add comprehensive bootstrap superuser section to authentication.adoc partial with when to use, configuration steps, verification, usage examples, and security best practices - Include note about secretRef requirement discovered during testing Tested on kind cluster with both default and custom bootstrap user configurations. Verified bootstrap user creation, ACL management, and new user functionality. Closes: DOC-242
JakeSCahill
force-pushed
the
doc-242-k8s-secure-bootstrap
branch
from
a370b00 to
e8d3d9f
Compare
|
@david-yu @andrewstucki This PR cannot be merged without an SME approval. |
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
Docs standards review
Files reviewed: 2 .adoc files (1 page + 1 partial)
Net diff: 217+/0- across 2 files.
What this PR does
Adds Kubernetes documentation for the auth.sasl.bootstrapUser configuration that creates a superuser at cluster formation. Closes DOC-242 — the content gap where bare-metal docs covered bootstrap config but Kubernetes docs didn't. Touches:
modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc(26+/0-): adds a short "Bootstrap user with custom credentials" section under the existing SASL configuration with a quick-example YAML and a link to the deeper partial section.modules/manage/partials/authentication.adoc(191+/0-): adds a comprehensive[[bootstrap]] === Bootstrap superuser at cluster formationsection inside the existingifdef::env-kubernetes[]block, covering when-to-use, configure-via-Operator-or-Helm, verify, use, and security best practices.
The partial is single-sourced from modules/manage/pages/security/authentication.adoc (bare metal) and modules/manage/pages/kubernetes/security/authentication/k-authentication.adoc (Kubernetes). The new section is properly gated to env-kubernetes only, so the bare-metal rendering won't see it.
Jira ticket alignment
Ticket: DOC-242 — content gap on Kubernetes bootstrap user docs.
Status: Addressed. Covers Operator AND Helm chart paths, includes the secretRef / users: [] gotcha discovered during testing, and tests claimed against kind clusters with both SCRAM-SHA-256 and SCRAM-SHA-512.
Critical issues
None.
Suggestions
-
name: "kubernetes-controller" # Optional, defaults to "kubernetes-controller"is potentially confusing. Showing the example value equal to the default value doesn't illustrate the customization path. Either:- (a) Show a real custom name (e.g.,
name: "admin-bootstrap") so readers see what customization looks like, or - (b) Omit the
name:field in the example and note "When omitted, defaults tokubernetes-controller."
The current example reads like "set this field to its default value" which most readers will translate to "this field is required and has no useful customization." That undersells the feature.
- (a) Show a real custom name (e.g.,
-
Inconsistent code-block syntax between the two changed files:
k-production-deployment.adocuses[source,yaml]- The partial uses
[,yaml,lines=10-16](shorthand + line-highlighting)
Pick one style for the PR's new content.
-
secretRefvssecretKeyRefdistinction. Both appear in the same YAML block:secretRef: redpanda-superusers ... bootstrapUser: secretKeyRef: name: "bootstrap-user-secret"
These are different mechanisms but visually similar names. A one-line note inline (or in a NOTE block) clarifying that
secretRefis the SASL-users secret whilesecretKeyRefis the bootstrap user's password reference would save readers from confusion. -
redpanda-superuserssecret name — is this a Helm-chart convention (the chart looks for a secret by that specific name) or just a placeholder? If conventional, worth saying "The secret nameredpanda-superusersis the default name expected by the Helm chart"; if arbitrary, worth using a placeholder like<superusers-secret-name>to avoid implying it's required. -
Security best practices NOTE block uses bullets with hyphens (
- Use strong...). That's valid AsciiDoc but uncommon in this repo's NOTE blocks — most use*for unordered lists. Cosmetic; one-character change for consistency. -
The "Combine with bootstrap configuration" section cross-links to
xref:deploy:redpanda/manual/production/production-deployment.adoc#configure-a-bootstrap-file. Verified the target heading exists on the bare-metal page. The xref will work — but the linked content is bare-metal-specific (.bootstrap.yamlfile approach), so readers click expecting K8s guidance and land on a manual page. Either:- (a) Add a note in the K8s section about how the
.bootstrap.yamlconcept maps to K8s (Operator config? ConfigMap?), or - (b) Reframe the link as "For the bare-metal equivalent of this configuration, see…" so readers know what they're clicking into.
- (a) Add a note in the K8s section about how the
Impact on other files
- Partial is consumed by two pages: bare-metal
authentication.adocand K8sk-authentication.adoc. The env-gating ensures the new section only shows in K8s rendering. ✓ Verified. k-production-deployment.adocconsumers: referenced fromk-production-workflow.adoc,k-production-readiness.adoc,k-tune-workers.adoc, etc. No cross-references TO the new section need updating.- Bare-metal
production-deployment.adochas the relatedConfigure a bootstrap fileandBootstrap a user accountsections that this PR's K8s equivalent parallels. Worth confirming with@david-yu/@andrewstuckithat the K8s flow matches the bare-metal flow semantically. - No What's New entry — this is filling a content gap, not announcing a new feature. Probably fine.
CodeRabbit findings
None — CodeRabbit didn't post on this PR.
What works well
- Pothole coverage: the NOTE about
secretRefrequirement when using emptyusers: []is exactly the kind of testing-discovered gotcha that saves customers from a confusing failure mode. Including it inline rather than as a separate "Troubleshooting" page is the right structural choice. - Operator AND Helm coverage via the nested tabs structure — neither audience is treated as second-class.
--valuesand--setHelm variants both shown — readers can copy/paste from the form they prefer.- Verification step is concrete (
rpk security user listwith the bootstrap creds, expected output shown). Lets readers confirm success. - Security best practices NOTE at the end caps the section with sensible guardrails.
- Cross-link from
k-production-deployment.adocto the deeper partial section is well-placed, so the production-deployment page stays scannable while the depth lives in the auth partial. [[bootstrap]]anchor is correctly placed inside the env-kubernetes block, so the bare-metal rendering of the same partial won't expose a confusing K8s-only anchor.
Process note
This PR has been sitting for ~7 weeks without SME review. The technical content here is meaningful (it documents a "secure by default" capability relevant to every K8s production deployment) — letting it languish has a real customer cost.
2 participants
Summary
Adds documentation for the
auth.sasl.bootstrapUserconfiguration that enables "secure by default" Kubernetes cluster deployments with authentication enforced from the first startup.Changes
secretRefrequirement when using emptyuserslistTesting
Tested on kind clusters with:
kubernetes-controller) with SCRAM-SHA-256admin-bootstrap) with SCRAM-SHA-512Related
Closes: https://redpandadata.atlassian.net/browse/DOC-242
This addresses the content gap where bare metal docs covered bootstrap configuration but Kubernetes docs did not, despite the operator/Helm charts supporting the feature.