DOC-2123: Update Console ACL UI references for new atomic-ACL design#568
Conversation
Refresh Cloud-only Console references ahead of Console's new Security page. ACL/RBAC behavior single-sourced from the docs repo flows in automatically via tag::single-source[]; this commit covers the pages that are not single-sourced. - create-dedicated-cloud-cluster.adoc: rewrite the user/ACL walkthrough to match the new atomic ACL form (Principal, Resource type, Pattern type, Resource name, Operation, Permission, Host) instead of the old "click the user, add permissions" flow. - serverless.adoc: split the single "Security page" reference into Security > Users / Security > ACLs / Security > Roles. - cloud-authentication.adoc: same split for the impersonation permissions guidance (lines 128, 135). Inline // TODO DOC-2123 comments mark form labels that need final confirmation from Jan/Martin once the new Security page ships. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for rp-cloud 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:
📝 WalkthroughWalkthroughThe pull request updates documentation across three files to reflect changes in the Redpanda Cloud Security UI. Navigation paths are made more specific by directing users to discrete Security subpages—Security > Users for user creation, Security > ACLs for ACL configuration, and Security > Roles for role assignment—rather than referencing a generic Security page. Additionally, ACL setup instructions are rewritten to include explicit field-by-field configuration steps. A TODO marker is added to validate ACL form label names upon release of the new Security page. Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![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
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@modules/get-started/pages/cluster-types/create-dedicated-cloud-cluster.adoc`:
- Line 61: Remove the placeholder TODO marker "// TODO DOC-2123" and replace it
with the final, verified ACL field labels (or remove the comment entirely) once
you confirm the exact UI wording; specifically update the ACL labels to match
the UI values for Resource Type, Pattern Type, Resource Name, Operation,
Permission, and Host in the create-dedicated-cloud-cluster.adoc content, and
ensure no TODO markers remain before merge.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: c92a7210-48b6-414c-9426-ee14325b4e06
📒 Files selected for processing (3)
modules/get-started/pages/cluster-types/create-dedicated-cloud-cluster.adocmodules/get-started/pages/cluster-types/serverless.adocmodules/security/pages/cloud-authentication.adoc
| ``` | ||
|
|
||
| . Click the name of your user, and add the following permissions to the ACL (access control list): | ||
| // TODO DOC-2123: confirm final ACL form labels (Resource Type, Pattern Type, Resource Name, Operation, Permission, Host) once the new Security page ships. |
There was a problem hiding this comment.
Resolve TODO before merge to avoid label drift in GA docs.
Leaving // TODO DOC-2123 here means ACL field labels may ship unverified; this conflicts with the PR’s stated merge condition to resolve all TODO markers.
Based on learnings: “In Redpanda Cloud documentation, field names and labels should match exactly what appears in the UI, even if the terminology might seem technically inconsistent.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@modules/get-started/pages/cluster-types/create-dedicated-cloud-cluster.adoc`
at line 61, Remove the placeholder TODO marker "// TODO DOC-2123" and replace it
with the final, verified ACL field labels (or remove the comment entirely) once
you confirm the exact UI wording; specifically update the ACL labels to match
the UI values for Resource Type, Pattern Type, Resource Name, Operation,
Permission, and Host in the create-dedicated-cloud-cluster.adoc content, and
ensure no TODO markers remain before merge.
Announce Console's redesigned Security page (atomic ACL list, role detail pages with inherited ACLs, user detail pages, regex filter) in the cloud-docs What's New. The blurb sits behind the same merge gate as the rest of the PR so it only goes live with Console GA. Inline TODO for Jan/Martin to confirm whether the customer-facing "editing an ACL no longer causes a permission gap" benefit can be stated publicly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…alone Previous commits referenced a standalone Security > ACLs page that does not exist in the shipped Console build (per Jan's recorded demo). The new layout has three tabs only — Users, Roles, Permissions — and ACLs are managed from a principal's detail page. - create-dedicated-cloud-cluster.adoc: rewrite the user/ACL walkthrough to follow the real flow: create the user, click "Go to user details" from the success dialog, then "+ Add ACL" under the user's ACLs section. Field labels match the Add ACL modal (Resource Type, Pattern Type, Resource Name, Operation, Permission, Host). - serverless.adoc, cloud-authentication.adoc: drop the "Security > ACLs" path; route users through Users/Roles detail pages instead. - whats-new-cloud.adoc: rewrite the May 2026 entry to describe the three-tab layout (Users / Roles / Permissions), per-principal ACL management on the detail page, and the three available actions (+ Add ACL, Allow all operations, Delete selected for bulk delete). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The third Security page tab is Permissions — a unified cluster-wide view of every principal's ACLs (direct + inherited), with role inheritance visualized as "VIA ROLE: <role-name>" groupings when you expand a row. Add this and the deny-spot indicator to the What's New blurb. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Preview-only playbook change so the cloud-docs Netlify preview pulls single-sourced acl.adoc / rbac-dp.adoc / gbac-dp.adoc content from docs PR #1689 instead of docs main. This lets reviewers see the single-sourced rewrites in cloud-docs context before either PR merges. REVERT (set documentation main branch back to first position) before merge. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Replace 2 em dashes with parentheses and split sentences. - Tighten passive "ACLs are managed per principal" lead-in. - Align "Allow all operations" caveat phrasing with acl.adoc. - Reword regex example "for example" comma comma into a cleaner semicolon construction. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
@micheleRP This one has been sitting for at least a month. Can you provide a status update? Thx |
|
@Feediver1 Status update: the Console dependency this PR documents has now shipped upstream, so we're close to being able to verify and merge.
Remaining blocker: the Cloud-side flag defaults to off behind a controlled LaunchDarkly rollout, so the new Security page isn't live for Cloud users yet. @jvorcak @weeco could you let me know when the new Security page is ready for docs? |
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
Docs standards review
Files reviewed: 4 .adoc files + 1 Antora playbook config
Overall: Companion to docs#1689 — content is solid and structurally aligned with the sibling PR, but three pre-merge blockers: the temporary playbook override needs reverting, two files have merge conflicts against current main, and the PR has had no human review in 5+ weeks. CI's check-branches correctly catches the playbook override.
What this PR does
Refreshes the Cloud-only pages that reference Console's redesigned Security page. ACL/RBAC procedural content single-sources from the docs repo (covered by sibling PR docs#1689); this PR handles the four Cloud-only files:
create-dedicated-cloud-cluster.adoc: rewrites the user/ACL walkthrough to follow the real shipped flow (create user → Go to user details → + Add ACL under user's ACLs section). Field labels match the Add ACL modal.serverless.adoc: drops the wrong "Security > ACLs" path; routes users through Users/Roles detail pages.cloud-authentication.adoc: same path correction for impersonation guidance.whats-new-cloud.adoc: adds a May 2026 entry describing the three-tab layout (Users/Roles/Permissions), per-principal ACL management, and the three detail-page actions.
Jira ticket alignment
Ticket: DOC-2123 — Update Console ACL UI references for new atomic-ACL design.
Status: Addressed. Same six-commit iterative refinement arc as docs#1689 — initial assumptions (Security > ACLs standalone page) corrected in commit 3 (actual layout: Users/Roles/Permissions tabs with per-principal ACLs), refined further in commit 4 (Permissions tab + VIA ROLE inheritance), em-dash style cleanup in commit 6. One // TODO DOC-2123 remains.
Critical issues
-
local-antora-playbook.yml:17–22still pointsdocumentationbranches atDOC-2123-console-acl-ui-refreshinstead ofmain. CIcheck-branchescatches this and fails. Same blocker as docs#1689.- Fix: Revert to
branches: [main, v/*, shared, site-search]before merge. Remove the TEMP comment block.
- Fix: Revert to
-
Merge conflicts in two files.
mergeable: CONFLICTING/mergeStateStatus: DIRTY. Last update was 2026-06-01, and main has moved substantially in the past three days. Specifically:whats-new-cloud.adoc— main already has== May 2026populated with three entries (Redpanda SQL, Centralized egress, Schema Registry Authorization) plus a new== June 2026section above it. This PR adds its own== May 2026header, which will produce a duplicate-header conflict.- Fix: Demote the PR's
== May 2026to an===subsection (=== Redpanda Console: redesigned Security page) and merge it INTO main's existing== May 2026block. Don't create a second== May 2026.
- Fix: Demote the PR's
cloud-authentication.adoc— main has substantially expanded the impersonation section: Kafka API and Schema Registry impersonation are now enabled independently, predefined Admin/Writer/Reader roles are documented, Schema Registry Authorization integration is described. The PR's two-line path corrections are anchored to prose that no longer exists in that form.- Fix: Re-apply the Security-page-path correction onto main's current impersonation prose. The fix is conceptually the same — replace
Securitywith the per-principal detail-page flow — but the surrounding sentences have changed.
- Fix: Re-apply the Security-page-path correction onto main's current impersonation prose. The fix is conceptually the same — replace
-
No human review. Companion PR docs#1689 has
@jvorcak's (Console eng) approval, which validates the UI accuracy. This PR has only CodeRabbit (which itself hasn't re-reviewed since 2026-04-30 and its only actionable finding is now stale). Cloud-side reviewer should look — Mali or Martin per the PR's context section.
Suggestions
-
modules/get-started/pages/whats-new-cloud.adoc:22— one unresolved// TODO DOC-2123:// TODO DOC-2123: confirm with Jan/Martin whether to call out the per-ACL edit improvement (no permission gap during edits) as a customer-facing benefit.This is one of the open questions in the PR description (item 4 in the docs#1689 description). Either resolve with Jan/Martin and add the line, or remove the TODO and ship without the benefit statement. Don't ship the TODO marker.
-
CodeRabbit's only inline comment is stale. It points at
create-dedicated-cloud-cluster.adoc:61and flags "leaving// TODO DOC-2123here means ACL field labels may ship unverified" — but that TODO was removed in commit 3 when the walkthrough was rewritten. The current file at that line is the**Resource Type**: Topicbullet. Marking the thread resolved on GitHub clears the noise. -
PR description includes the cloud-docs preview for
acl.adoc/rbac_dp.adoc/gbac_dp.adoc, but those pages are single-sourced from docs#1689 and only render correctly because of the temp playbook override. Once the override is reverted, those preview links go back to showing docs/main content. Worth noting in the PR description so the post-merge expectation is set: the cloud-docs-only files in this PR get verified directly; the single-sourced files get verified via docs#1689's preview.
Impact on other files
- docs#1689 (companion PR) must land together with this. The two are functionally a single change split across two repos. Docs#1689 is currently blocked on Jeffail's stale
CHANGES_REQUESTEDfrom March — that needs to clear before either lands. - Single-sourced partials from docs:
acl.adoc,rbac-dp.adoc,gbac-dp.adocare picked up fromredpanda-data/documentationviatag::single-source[]. Verified the references in this PR's prose match the field labels in docs#1689's partials (Resource Type, Pattern Type, Resource Name, Operation, Permission, Host). - No nav.adoc change needed — all files are existing entries.
- No xref breakage — additive changes only.
CodeRabbit findings worth considering
None new. The only actionable CodeRabbit comment (the stale TODO finding) refers to content that has since been removed. CodeRabbit hasn't re-reviewed since the iterative refinement commits.
What works well
- ACL form field labels are consistent across this PR and docs#1689:
- Both use Resource Type, Pattern Type, Resource Name, Operation, Permission, Host
- Both use + Add ACL, Allow all operations, Delete selected as the three actions
- Both use the "Use this for testing only; it is too broad for production." caveat phrasing on Allow all operations
- Iterative refinement arc mirrors docs#1689 — same commit-3 pivot from "standalone Security > ACLs page" to "per-principal ACLs on detail page" once Jan's demo clarified the actual UX. The commit messages clearly document each pivot.
- Cluster-creation walkthrough flows naturally now: create user → confirmation dialog → Go to user details → add ACL on detail page. Matches what a new customer would actually click through.
- May 2026 entry is well-structured for the cloud audience — leads with the three-tab layout, explains the per-principal model, and surfaces the Permissions tab's cluster-wide inheritance view as the most operationally useful feature.
- Voice and tone consistent — active voice, second person, em dashes cleaned up in commit 6.
- Single-source coverage is correctly scoped: this PR touches only the Cloud-only files; the partials (acl.adoc, rbac partials, gbac partials) flow in from docs#1689 via
tag::single-source[]. No duplication of effort.
Process note
This PR has been open since 2026-04-30 (5+ weeks) with zero human reviews. The companion PR (docs#1689) at least has Jan's approval validating UI accuracy. The cloud-docs companion needs an equivalent cloud-side reviewer — probably Mali or Martin per the PR's context section. Once that's in place and the merge conflicts + temp playbook are resolved, both PRs should land in the same merge window.
Recommended order of operations to land both PRs together
- Resolve this PR's merge conflicts (rebase or merge main; carefully merge May 2026 entries on whats-new-cloud, re-apply path correction on cloud-authentication).
- Resolve the TODO in whats-new-cloud.adoc:22 (ping Jan/Martin, then either add the benefit statement or remove the TODO).
- Re-request review from a cloud-side reviewer.
- Clear docs#1689's stale
CHANGES_REQUESTED(re-request from Jeffail or admin-dismiss). - Revert both playbook overrides (this PR's
local-antora-playbook.ymlAND docs#1689'slocal-antora-playbook.yml). - Merge in the same window so single-sourced content stays in sync.
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
See the critical fixes and suggestions.
…ui-refresh # Conflicts: # modules/get-started/pages/whats-new-cloud.adoc # modules/security/pages/cloud-authentication.adoc
Point the documentation source back at main now that the DOC-2123 work is ready to merge. Clears the check-branches CI failure. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2 participants
Summary
Refresh Cloud-only Console references ahead of Console's redesigned Security page. The shipped layout (per Jan's recorded demo) is Users / Roles / Permissions — three tabs, no standalone ACLs page. ACLs are managed per principal from the user or role detail page. ACL/RBAC procedural content single-sourced from the docs repo flows in automatically via
tag::single-source[]; this PR covers only the Cloud pages that are not single-sourced. Companion PR: redpanda-data/docs#1689.create-dedicated-cloud-cluster.adoc: rewrite the user/ACL walkthrough to follow the real flow — create the user, click Go to user details from the success dialog, then+ Add ACLunder the user's ACLs section. Field labels match the Add ACL modal (Resource Type, Pattern Type, Resource Name, Operation, Permission, Host).serverless.adoc,cloud-authentication.adoc: drop the wrong "Security > ACLs" path; route users through Users/Roles detail pages instead.whats-new-cloud.adoc: add a May 2026 entry describing the three-tab layout, per-principal ACL management, and the three actions on a principal's ACLs section (+ Add ACL,Allow all operations,Delete selectedfor bulk delete).Inline
// TODO DOC-2123comment flags one customer-benefit phrasing for Jan/Martin to confirm.Context
See the docs-repo PR description for the full open-questions list to Jan/Martin.
Preview pages
acl.adocrewrite (Manage ACLs section)rbac-*partialsgbac-*partialsTest plan
npm run build && npm run servepasses locallysecurity/authorization/// TODO DOC-2123comment before mergelocal-antora-playbook.yml— set theredpanda-data/documentationbranches back to[main, v/*, shared, site-search](currently points atDOC-2123-console-acl-ui-refreshfor cross-PR preview)🤖 Generated with Claude Code