Repository navigation
docs: custom roles - #2158
docs: custom roles#2158
Conversation
johanandren
left a comment
There was a problem hiding this comment.
Looks good, but maybe best keep as draft until all features are in released CLI
🤖 Review
Blocking
- The tables load from dev.
rbac-tables.jshardcodesapi.kalix.dev, but production isapi.kalix.io. That host returns 404 for/resources/rbac/until lightbend/kalix#17184 ships. Use the production host, or generate the tables at build time (see 6). - Merge after the CLI release.
cli-3.0.79has norole-bindings,rolesor--custom-role. If the docs publish first, these commands fail for users, including commands that work today on the CI/CD, workload identity and OIDC pages. team-a-deployershould fail validation.projects/team-a-devis not a UUID, andResourcePattern.parserequires one throughProjectId. The CLI does not translate names to ids. Use a UUID in the example, and say how to find a project id.
Should fix
- Wrong example output.
organization-role-bindings.adocshows the columnsUSERNAME EMAIL NAME. The CLI printsROLE BINDING ID ROLE PRINCIPAL MFA ENABLED. The example also conflicts with the statement that the list includes groups and services. llms.txtis stale. Lines 175 and 179 point to the deleted.html.mdpages, and page aliases do not cover those URLs. The new security and RBAC pages are missing.- The tables are invisible outside a browser. The
.html.mdoutput and search indexing see only the placeholder row, and that row omitsroles/project/viewer. Consider a generated partial, as ingenerate_instance_types_table.sh. Ifreference/rbacshould ship inakka-docs-md.zip, add it to the rsync includes indocs2markdown.sh. - Role links usually do not scroll to their target. Links from
permissions.htmlgo toroles.html#role-..., but the row exists only after the fetch finishes. Scroll to the hash after rendering, or drop this if you generate the tables. - The relevance rule is undocumented. A rule scoped to projects or regions can only grant permissions of that kind. For example,
resources: ["projects/*"]withpermissions: ["*"]is rejected. Also explain that a blank Granted on cell means an organization permission that can not be scoped (33 of 115 rows). - Workload identity options are missing. The organization page names workload identity as a principal but does not show
--workload-identity-subjector--workload-identity-claim. The CI/CD and workload identity pages still send readers to the binding pages for the full set of options. - The
akka_roles.adocedit will be lost. The page is generated, andcmd/akka/role.gostill has the old URL. Fix it in the CLI too. After the CLI release, regenerate the CLI docs and point the links labelledakka organizations role-bindings addat the real page. - Aliases point to the overview page. Point
manage-usersatorganization-role-bindingsandmanage-project-accessatproject-role-bindings, so old links land on matching content.
Nits
== Command namesis development history, which theCLAUDE.mdwriting style excludes. If it stays for users of older CLIs, keep it short.- Rules need at least one of
permissionsorroles. The docs do not say so. rbac/permissions.adocgives the form<type>.<resource>.<operation>, butbilling.account.contact.updatehas four segments. It also says you bind a permission, but you bind roles.rbac-tables.jshas dead code: theclassNameparameter ofcell, andremoveAttribute('data-search').- The new
rbac/*pages and the moved OIDC page lack some:page-*:metadata thatdocs/AGENTS.mdexpects. - The new pages use "can not", while other operations pages use "cannot".
Questions
- Did you choose runtime loading to keep the tables current? If so, are the costs in 1, 6 and 7 acceptable?
delete --cascade-role-bindingsmentions invitations for a custom role, butinvitations createonly takes--role. Can an invitation carry a custom role?
e69a35e to
bef0800
Compare
|
Response to review feedback:
Nits:
Re cascading to deleting invitations - yes it's not possible to create an invitation that binds to a custom role, but nevertheless if one did exist, the cascading delete would delete them, so the docs are correct in my opinion. That's a feature gap that needs to be addressed elsewhere. |
bef0800 to
74efac1
Compare
|
Optimize docs build is failing. |
|
Doc build should be fixed now |
74efac1 to
fcfcf5b
Compare
|
Rebased to have the latest CLI docs in scope. |
|
Cool, there's one issue - right now still pulling roles/permissions from dev, because the routes aren't deployed to prod. |
See lightbend/kalix#16688 This documents custom roles. It completely rewrites all existing user access documentation for projects and organizations, unifying them into one place.
fcfcf5b to
4374b97
Compare
|
Ok, this is now ready to merge, docs build points to api.kalix.io. @johanandren just waiting for review approval. |
See https://github.com/lightbend/kalix/issues/16688
This documents custom roles. It completely rewrites all existing user access documentation for projects and organizations, unifying them into one place.