Add docs for the Role resource in Kubernetes #1378
Conversation
|
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 updates Kubernetes security docs to include authorization alongside authentication, adds a new page on managing Roles via the Redpanda Operator, and updates navigation labels accordingly. It introduces a BDD feature file with Kubernetes Role CRD examples and end-to-end scenarios, and substantially expands the CRD reference with new types (Role, ACL-related filters/specs, Listener, TrustStore, Pool* types) while removing NodePoolStatus. A test setup JSON increases a timeout for dependency installation. Linked issue DOC-1512 aligns with documenting declarative Role management. Sequence Diagram(s)sequenceDiagram
autonumber
actor User as User (kubectl/Helm)
participant K8s as Kubernetes API
participant Operator as Redpanda Operator
participant RP as Redpanda Cluster
rect rgba(230,245,255,0.7)
note over User,K8s: Create/Update Role CRD (principals + authorization)
User->>K8s: apply Role (spec.principals, spec.authorization.acls)
K8s-->>Operator: Role add/update event
end
rect rgba(240,255,240,0.7)
note over Operator,RP: Reconciliation
Operator->>RP: Ensure principals exist in cluster
Operator->>RP: Apply ACLs per Role authorization
Operator-->>K8s: Update Role.status (managedRole, managedAcls, conditions)
end
alt Success
RP-->>Operator: OK
Operator-->>User: kubectl get role/status reflects sync
else Error
RP-->>Operator: Error
Operator-->>K8s: conditions: Degraded/NotReady
Operator-->>User: kubectl describe role shows errors
end
sequenceDiagram
autonumber
actor User
participant K8s
participant Operator
participant RP
note over User: Delete Role CRD
User->>K8s: delete Role
K8s-->>Operator: Role delete event
alt Role managed principals + authorization
Operator->>RP: Optionally remove managed ACLs
Operator->>RP: No-op on principals (users remain)
else Authorization-only Role
Operator->>RP: Remove managed ACLs only
else Principals-only Role
Operator->>RP: No-op on ACLs
end
Operator-->>User: Deletion complete (status final)
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
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 review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (7)
modules/ROOT/nav.adoc(1 hunks)modules/manage/examples/kubernetes/role-crds.feature(1 hunks)modules/manage/pages/kubernetes/security/authentication/index.adoc(1 hunks)modules/manage/pages/kubernetes/security/authentication/k-user-controller.adoc(2 hunks)modules/manage/pages/kubernetes/security/authorization/k-role-controller.adoc(1 hunks)modules/reference/pages/k-crd.adoc(27 hunks)tests/setup-tests/fetch-versions-and-rpk.json(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-08-25T21:00:26.626Z
Learnt from: micheleRP
PR: redpanda-data/docs#1334
File: modules/manage/partials/rbac-dp.adoc:93-98
Timestamp: 2025-08-25T21:00:26.626Z
Learning: In cloud documentation (env-cloud), Security is at the top level navigation, so ACL references should use `security:authorization/rbac/acl.adoc`. In self-managed documentation, Security is nested under Manage, so ACL references use `manage:security/authorization/acl.adoc`. The different xref paths in conditional blocks reflect these different navigation structures.
Applied to files:
modules/ROOT/nav.adoc
There was a problem hiding this comment.
LGTM but I'd like @sago2k8 and/or @andrewstucki to also give a 👍 before merging.
modules/manage/pages/kubernetes/security/authorization/k-role-controller.adoc
Outdated
Show resolved
Hide resolved
|
|
||
| In Redpanda, roles work the same way: | ||
|
|
||
| * **Without roles**: You set up permissions individually for each user. If you have 10 developers who all need the same access to certain topics, you configure the same permissions 10 times. |
There was a problem hiding this comment.
If you'd like additional ammo:
When developers need new permission, you have to update all 10 developers.
| .`read-only-role.yaml` | ||
| [,yaml,indent=0] | ||
| ---- | ||
| include::manage:example$kubernetes/role-crds.feature[tags=manage-roles-with-authorization,indent=0] |
There was a problem hiding this comment.
Seeing our test cases used in documentation really helps me sleep better at night <3
JakeSCahill
changed the title
2 participants
Description
Resolves https://redpandadata.atlassian.net/browse/DOC-1512
Page previews
Checks