DOC-1202 Console/Cloud schema subject ACLs #1334
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 You can disable this status message by setting the 📝 WalkthroughWalkthroughThis PR updates documentation structure and content for authorization and ACLs. It renames navigation labels, reorders Authorization sub-items, and significantly rewrites ACL and RBAC docs. ACL docs now include Schema Registry resources (registry, subject) and expanded operations, plus rpk workflows and scenarios. RBAC docs are reorganized with modular partials (create/edit/assign/unassign/list/describe), expanded scope to cover Schema Registry ACLs, and added best practices and workflows. Some env-cloud conditional content is added/removed, including gating a line in cluster-properties.adoc about schema_registry_enable_authorization. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Assessment against linked issues
Assessment against linked issues: Out-of-scope changes
Possibly related PRs
Suggested reviewers
✨ Finishing Touches🧪 Generate unit tests
🪧 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: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
modules/manage/pages/security/authorization/acl.adoc (3)
540-586: Include Schema Registry resource flags in the create ACL flags table.To make Schema Registry coverage actionable, add the
--registry-subjectand--registry-globalflags to the “Create ACLs” flag table, aligned with how topic/group/transactional-id are documented.| --topic | Topic to grant ACLs for (repeatable). | --transactional-id | Transactional IDs to grant ACLs for (repeatable). + +| --registry-subject +| Schema Registry subject to grant ACLs for (repeatable). + +| --registry-global +| Grants ACLs for global Schema Registry operations (no name required).
637-681: Mirror Schema Registry flags in the list/delete flags table.List/delete should support the same resource flags as create. Add the flags so users can filter/manage Schema Registry ACLs.
| --topic | Topic to list/remove ACLs for. (repeatable) | --transactional-id | Transactional IDs to list/remove ACLs for. (repeatable) + +| --registry-subject +| Schema Registry subject(s) to list/remove ACLs for. (repeatable) + +| --registry-global +| Match ACLs for global Schema Registry operations.
16-19: Fix broken xref target for cloud-gated ACL docThe referenced path
security/authorization/rbac/rbac_dp.adocdoes not exist; the Role-Based Access Control page lives atsecurity/authorization/rbac.adoc. Update the xref accordingly.• File: modules/manage/pages/security/authorization/acl.adoc
Line 17- xref:security:authorization/rbac/rbac_dp.adoc[role-based access control] + xref:security:authorization/rbac.adoc[role-based access control]
♻️ Duplicate comments (2)
modules/reference/pages/properties/cluster-properties.adoc (1)
5684-5686: Cloud readers still need an explicit note about authentication_methodYou gated the authentication note for non-Cloud only, which avoids confusing Cloud users. However, it leaves Cloud builds without guidance about who configures Schema Registry authentication. Add a Cloud-only sentence clarifying that Cloud manages it (or where to configure it in Cloud), which also addresses the earlier reviewer concern.
Proposed snippet:
ifndef::env-cloud[] Requires authentication to be enabled using the xref:reference:properties/broker-properties.adoc#schema_registry_auth_method[`authentication_method`] property in the `schema_registry_api` broker configuration. endif::[] +ifdef::env-cloud[] +In Redpanda Cloud, Schema Registry authentication is managed by the platform; you do not configure the broker-level `authentication_method`. +endif::[]modules/manage/pages/security/authorization/acl.adoc (1)
122-122: Prior request addressed: added link to Schema Registry authorization.This cross-reference satisfies the earlier reviewer suggestion to link to Schema Registry AuthZ examples.
🧹 Nitpick comments (19)
modules/manage/partials/rbac-list-role.adoc (1)
3-3: Consistent step formatting with other RBAC partialsOther RBAC partials use ordered steps (". ") starting with “From Security…”. Consider making this a single ordered step for visual consistency across pages.
Apply this diff:
-To view all existing roles: - -From *Security* on the left navigation menu, select the *Roles* tab. +To view all existing roles: + +. From *Security* on the left navigation menu, select the *Roles* tab.modules/manage/partials/rbac-assign-role.adoc (2)
11-11: Minor wording tighten-up in Principals stepSlightly improves flow and emphasizes the UI label.
Apply this diff:
-. Below the list of permissions, find the Principals section. You can add any number of users/principals to the role at a time. After you have listed all new users/principals, click *Update*. +. Below the list of permissions, find the *Principals* section. You can add any number of users/principals to the role. After listing all new users/principals, click *Update*.
19-21: Align UI label phrasingUse a consistent pattern for UI controls (“the field”) across RBAC docs.
Apply this diff:
-. Using the Assign Roles input field, select the roles you want to add to this user. +. In the *Assign roles* field, select the roles you want to add to this user.modules/manage/partials/rbac-create-role.adoc (2)
7-7: Refine phrasing for origin hostAvoids ending with a preposition and reads more clearly.
Apply this diff:
-. Provide a name for the role and an optional origin host for users to connect from. +. Provide a name for the role and, optionally, an origin host from which users can connect.
11-11: Consistent “Optional” stylingThis matches the optional step styling used elsewhere; consider using sentence case for the UI label “users/principals” across all RBAC partials for uniformity (you already do in other files).
No change required if this is the repo standard.
modules/manage/partials/rbac-unassign-role.adoc (2)
3-13: Promote option label to a subsection and mark the UI “x” as a literal control; keep steps contiguous.
- Use a subsection for scanability and ToC linking.
- Render the “x” remove control as a literal (
x) instead of italics for clarity.- Consider removing blank lines between list items so Asciidoctor treats them as one ordered list.
-Option 1: Edit the role +=== Option 1: Edit the role @@ -. Below the list of permissions, find the Principals section. Click *x* beside the name of any principals you want to remove from the role. +. Below the list of permissions, find the Principals section. Click `x` beside the name of any principals you want to remove from the role.To verify list rendering and spacing, please check the Netlify preview of this page to ensure the ordered steps aren’t split by blank lines.
15-23: Mirror formatting from Option 1; tighten wording and mark the UI “x” as a literal.
- Make the option a subsection for consistency.
- Prefer concise wording that avoids terminal prepositions.
- Use
xas a literal control.-Option 2: Edit the user +=== Option 2: Edit the user @@ -. Click *x* beside the name of any roles you want to remove this user from. +. Click `x` beside the name of any roles to remove from this user.modules/manage/pages/security/authorization/index.adoc (1)
1-5: Title and index layout look good; consider aligning nav label and adding quick links.
- “Configure Authorization” + page-layout index is clear. Ensure the nav label (“Authorization” in nav.adoc) intentionally differs from the page title for brevity.
- Optional: add quick links to RBAC and ACL pages to reduce pogo-sticking.
Example snippet to add after the intro paragraph:
See also: * xref:security/authorization/rbac.adoc[Role-Based Access Control (RBAC)] * xref:security/authorization/acl.adoc[Access Control Lists (ACLs)]Please confirm the Antora build renders this page as the section index (with the expected child links) given
:page-layout: index.modules/manage/pages/security/authorization/rbac.adoc (1)
15-15: Verify include path and prerequisites after gating changes.You’re now including modular content via
manage:partial$rbac-dp.adoc. Since the “Suggested reading” block was removed from this wrapper, ensurerbac-dp.adoc(or the included partials) still surface any critical prerequisites or cross-links (for example, authentication setup) so readers don’t lose context.If helpful, I can scan
rbac-dp.adocand sibling partials to confirm headings hierarchy, duplicate H1/H2 levels, and cloud gating consistency.modules/ROOT/nav.adoc (1)
167-170: Confirm xref targets exist and labels intentionally differ from page titles.
The updated xrefs point to:
manage:security/authentication.adocmanage:security/authorization/index.adocmanage:security/authorization/rbac.adocmanage:security/authorization/acl.adoc
Please verify these exact targets resolve (files and implicit IDs) after the restructuring.Label choice: keeping nav label “Authorization” while the page title is “Configure Authorization” is fine; just confirm it’s intentional.
To verify locally, run a link check or build the docs site and click through the Manage → Security section to ensure no broken nav items.
modules/manage/partials/rbac-delete-role.adoc (1)
3-11: Add an explicit caution before destructive action; ensure list renders as a single ordered sequence.
- Insert a CAUTION block before the first “Delete” step to set expectations about impact and irreversibility.
- Consider removing blank lines between list items so the steps remain one ordered list across all renderers.
. Click the role you want to delete. This shows all currently assigned permissions (ACLs) and principals (users). . Click *Delete*. +. [CAUTION] +-- +Deleting a role cannot be undone. This action removes the role and its assignments from any principals. Users are not deleted. +-- + . {ui} displays a prompt asking you to confirm deletion of the role. The prompt differs based on whether there are principals assigned to the role or not. If there are principals assigned to the role, you must type the role name in the input field when prompted before you can continue. . Click *Delete*.Please preview the page to confirm the admonition renders correctly and that step numbering is continuous.
modules/manage/partials/rbac-edit-role.adoc (3)
5-5: Fix mismatch in intent: “assign” vs “edit”.This step is within an “edit the ACLs for an existing role” flow, but says “assign to one or more principals.” Recommend changing “assign” to “edit” to avoid confusion with the role assignment flow.
-. Find the role you want to assign to one or more principals and then click on the role name. +. Find the role you want to edit and then click the role name.
11-11: Clarify phrasing: “add or remove existing ACLs”.“Add or remove existing ACLs” is self-contradictory. Suggest: “add new ACLs or remove existing ACLs.”
-. You can add or remove existing ACLs for the role. As when creating a new role, you can create or modify ACLs for topics, consumer groups, transactional IDs, Schema Registry subjects, and Schema Registry operations. +. You can add new ACLs or remove existing ACLs for the role. As when creating a new role, you can create or modify ACLs for topics, consumer groups, transactional IDs, Schema Registry subjects, and Schema Registry operations.
3-3: Minor UX alignment: “tab” vs “section”.If the left-nav uses “Roles” as a page/section rather than a tab, consider dropping “tab” for consistency with other pages.
-. From *Security* on the left navigation menu, select the *Roles* tab. +. From *Security* in the left navigation, select *Roles*.modules/manage/pages/security/authorization/acl.adoc (2)
10-12: Clean up grammar and commas in intro block.Minor readability nits: remove the comma after “then” and tighten phrasing.
-After you enable authorization, by default, only superusers have access to the resources. Redpanda recommends creating other users to effectively use Redpanda and then, create ACLs for them. +After you enable authorization, only superusers have access to resources by default. Redpanda recommends creating additional users and then creating ACLs for them.Also consider “more flexible way” → “more flexible way” is fine; no change needed.
119-121: Use explicit flag names with leading dashes.These should reference the actual rpk flags with leading double-dashes for consistency and clarity.
-* `subject`: Controls ACL access for specific Schema Registry subjects. Specify using the flag `registry-subject`. -* `registry`: Controls whether or not to grant ACL access to global, or top-level Schema Registry operations. Specify using the flag `registry-global`. +* `subject`: Controls ACL access for specific Schema Registry subjects. Specify using the flag `--registry-subject`. +* `registry`: Controls whether to grant ACL access to global (top-level) Schema Registry operations. Specify using the flag `--registry-global`.modules/manage/partials/rbac-dp.adoc (3)
102-110: Upgrade note is useful; add link to migration guidance if available.Assigning existing users to a default
Userrole with no ACLs is a safe default. If you have a migration guide for moving from pure ACLs to RBAC, consider linking it here.
454-454: Typo: “actives roles” → “active roles”.-To view a list of all actives roles, run: +To view a list of all active roles, run:
523-535: Ensure a single, canonicalrpk security aclxref pathWe’ve confirmed that the ACL topic is authored in modules/reference/pages/rpk/rpk-security/rpk-security-acl.adoc (which declares page-aliases for both reference:rpk/rpk-acl.adoc and reference:rpk/rpk-acl/rpk-acl.adoc). However, across the product docs the xref is sometimes written as:
xref:reference:rpk/rpk-security/rpk-security-acl.adocxref:reference:rpk/rpk-acl.adocxref:reference:rpk/rpk-acl/rpk-acl.adocTo avoid confusion—and make future moves of the source file transparent—please pick one canonical path and use it everywhere. For example, if you prefer the “full” location, update all occurrences to:
xref:reference:rpk/rpk-security/rpk-security-acl.adoc[`rpk security acl`]Or, if you prefer the short alias, use:
xref:reference:rpk/rpk-acl.adoc[`rpk security acl`]Locations to update:
- modules/upgrade/pages/deprecated/index.adoc: line 149
- modules/manage/pages/security/authentication.adoc: line 15
- modules/manage/pages/security/authorization/acl.adoc: lines 416, 483
- modules/manage/pages/kubernetes/security/authentication/k-authentication.adoc: line 27
- modules/manage/partials/rbac-dp.adoc: lines 525–526
- modules/manage/partials/authentication.adoc: line 434
Once you’ve chosen and applied the canonical path throughout, this comment can be resolved.
📜 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 (13)
modules/ROOT/nav.adoc(1 hunks)modules/manage/pages/security/authorization/acl.adoc(6 hunks)modules/manage/pages/security/authorization/index.adoc(1 hunks)modules/manage/pages/security/authorization/rbac.adoc(1 hunks)modules/manage/partials/rbac-assign-role.adoc(1 hunks)modules/manage/partials/rbac-create-role.adoc(1 hunks)modules/manage/partials/rbac-delete-role.adoc(1 hunks)modules/manage/partials/rbac-describe-role.adoc(1 hunks)modules/manage/partials/rbac-dp.adoc(4 hunks)modules/manage/partials/rbac-edit-role.adoc(1 hunks)modules/manage/partials/rbac-list-role.adoc(1 hunks)modules/manage/partials/rbac-unassign-role.adoc(1 hunks)modules/reference/pages/properties/cluster-properties.adoc(1 hunks)
🔇 Additional comments (14)
modules/reference/pages/properties/cluster-properties.adoc (1)
5682-5683: Good: clarifies the authorization model shift for Schema RegistryThe clarification that enabling this property switches to ACL-based authorization is precise and helps set expectations.
modules/manage/partials/rbac-describe-role.adoc (1)
3-5: LGTM: streamlined navigation and actionCollapsing navigation into a concise first step and making the action (“click the role name”) explicit improves scannability.
modules/manage/partials/rbac-assign-role.adoc (1)
3-3: Promote option headings to sentence caseMatch style used elsewhere (“Edit the role”, “Edit the user”) which you already use. No change needed if this is the standard; calling it out for consistency awareness.
modules/manage/partials/rbac-create-role.adoc (2)
3-5: LGTM: standardized navigation and explicit create actionClear, action-first phrasing matches the rest of the RBAC partials.
9-9: Nice: expanded ACL scope includes Schema Registry subjects and operationsThis aligns the create flow with the new ACL taxonomy and reduces ambiguity for readers.
modules/manage/partials/rbac-edit-role.adoc (1)
9-9: Verify whether “origin host” is editable at the role level in the UI.Origin host restrictions are typically part of individual ACL entries (host column), not a role-global property. If the UI allows setting a default host restriction per role, keep this. Otherwise, consider removing or reframing to “update host restrictions on specific ACLs.”
Would you confirm in the Console whether the role edit screen exposes a role-level origin host field? If not, we should adjust the wording to “update host restrictions on ACLs within the role.”
modules/manage/pages/security/authorization/acl.adoc (4)
572-574: Validate--name-patternflag (possible duplication with--resource-pattern-type).Docs list both
--name-patternand--resource-pattern-typefor matching resource names. If--name-patternis deprecated or an alias, we should either remove it here or mark it as an alias to avoid confusion.Please confirm via rpk help whether
--name-patternis a valid, user-facing flag. If not, remove it from the docs to prevent ambiguity.
221-363: Good depth: client request to ACL mapping is highly useful.The collapsible “Show operations” section is comprehensive, including Schema Registry endpoints. This will save users a lot of trial-and-error.
36-38: UI vs CLI entry points are clear.Calling out the ACLs tab for users vs Roles tab for roles reduces confusion and aligns with the RBAC reorg.
523-531: Suggested reading cross-links look correct for non-cloud builds.The manage-path ACL and Authentication references are appropriate and consistent with the rest of the doc set.
modules/manage/partials/rbac-dp.adoc (4)
27-28: Nice clarity: Roles vs ACLs entry points in the UI.Explicitly distinguishing Roles (role principals) vs ACLs (user principals) helps users pick the right workflow.
31-54: Solid end-to-end RBAC example.The
DataAnalystsworkflow is easy to follow and demonstrates prefixed patterns, role grants, assignment, and verification.
175-199: RBAC best practices are concise and actionable.Good guidance on role design and operational hygiene.
439-443: Good reuse of partials for UI steps.Including the partial keeps the UI flow DRY across RBAC pages.
Description
This pull request refactors and improves the documentation for access control and RBAC, including new Console/Cloud UI ACL support for Schema Registry subjects and operations.
Resolves https://redpandadata.atlassian.net/browse/DOC-1202
Review deadline:
Page previews
ACLs in Cloud
RBAC in Cloud
ACLs in SM
RBAC in SM
Checks