Add docs for the Role resource in Kubernetes

[JakeSCahill]

Description

Resolves https://redpandadata.atlassian.net/browse/DOC-1512

Page previews

Checks

• New feature
• Content gap
• Support Follow-up
• Small fix (typos, links, copyedits, etc)

[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.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

This 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

Loading

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)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• auto-docs: Update CRD reference doc for release #1141: Also updates k-crd.adoc with Role/ACL-related definitions; overlaps with CRD surface changes here.
• Use doc-tools CLI for GitHub Actions #1138: Modifies tests/setup-tests/fetch-versions-and-rpk.json; related to this PR’s timeout adjustment in the same file.

Suggested reviewers

• chrisseto
• sago2k8

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes Check	⚠️ Warning	The PR also updates reference documentation for non-Role CRDs like TrustStore, Listener, and storage validation types and increases the timeout in an unrelated test spec. These modifications do not relate to the linked issue objectives of documenting declarative Role management. Including them in this PR reduces focus on the Role documentation changes.	Extract the unrelated CRD and test changes into separate pull requests or remove them from this PR so it remains focused on the Role resource documentation.
Description Check	⚠️ Warning	The description fills in the JIRA resolution and checks but omits the required Review deadline field and does not include any actual Netlify preview URLs, leaving the page previews section as a placeholder. This deviates from the repository’s description template which expects both a deadline and working preview links. Without these details the template structure is incomplete.	Please add a “Review deadline:” line under the Description header and replace the page preview placeholder with actual Netlify preview URLs for the updated documentation pages.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues Check	✅ Passed	The pull request adds a dedicated Kubernetes Role controller page under modules/manage/pages/kubernetes/security/authorization, updates the reference CRD documentation to include the new Role spec and status, and includes example BDD tests for Role CRDs. These changes align with the objective of documenting declarative management of Roles via the Operator. All primary coding-related requirements from DOC-1512 are implemented.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Title Check	✅ Passed	The title succinctly captures the main change of the pull request by indicating the addition of documentation for the Role resource in Kubernetes, accurately reflecting the extensive updates to CRD reference pages and example guides without extraneous detail. It is clear, specific, and concise, enabling team members to understand the primary purpose of the changes at a glance.

---

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.}

[JakeSCahill]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

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.

📥 Commits

Reviewing files that changed from the base of the PR and between 73f9543 and 5bb5c55.

📒 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

[chrisseto]

LGTM but I'd like @sago2k8 and/or @andrewstucki to also give a 👍 before merging.

[chrisseto]

Seeing our test cases used in documentation really helps me sleep better at night <3

[chrisseto]

@JakeSCahill heads up (And sorry for the late notice) we've renamed Role -> RedpandaRole to prevent conflicts with the builtin Role type. redpanda-data/redpanda-operator#1135

[sago2k8]

lgtm

[paulohtb6]

Should we backtick "User", "Role" and similar resources?

[JakeSCahill]

We don't: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/k-deployment-overview/#documentation-conventions