Skip to content

docs: custom roles - #2158

Merged
johanandren merged 1 commit into
mainfrom
jroper/custom-roles-docs
Nov 4, 2026
Merged

johanandren merged 1 commit into
mainfrom
jroper/custom-roles-docs

Conversation

@jroper

@jroper jroper commented Oct 30, 2026

Copy link
Copy Markdown
Contributor

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.

@github-actions github-actions Bot added the documentation documentation related label Oct 30, 2026

@johanandren johanandren left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, but maybe best keep as draft until all features are in released CLI

🤖 Review

Blocking

  1. The tables load from dev. rbac-tables.js hardcodes api.kalix.dev, but production is api.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).
  2. Merge after the CLI release. cli-3.0.79 has no role-bindings, roles or --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.
  3. team-a-deployer should fail validation. projects/team-a-dev is not a UUID, and ResourcePattern.parse requires one through ProjectId. The CLI does not translate names to ids. Use a UUID in the example, and say how to find a project id.

Should fix

  1. Wrong example output. organization-role-bindings.adoc shows the columns USERNAME EMAIL NAME. The CLI prints ROLE BINDING ID ROLE PRINCIPAL MFA ENABLED. The example also conflicts with the statement that the list includes groups and services.
  2. llms.txt is stale. Lines 175 and 179 point to the deleted .html.md pages, and page aliases do not cover those URLs. The new security and RBAC pages are missing.
  3. The tables are invisible outside a browser. The .html.md output and search indexing see only the placeholder row, and that row omits roles/project/viewer. Consider a generated partial, as in generate_instance_types_table.sh. If reference/rbac should ship in akka-docs-md.zip, add it to the rsync includes in docs2markdown.sh.
  4. Role links usually do not scroll to their target. Links from permissions.html go to roles.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.
  5. The relevance rule is undocumented. A rule scoped to projects or regions can only grant permissions of that kind. For example, resources: ["projects/*"] with permissions: ["*"] is rejected. Also explain that a blank Granted on cell means an organization permission that can not be scoped (33 of 115 rows).
  6. Workload identity options are missing. The organization page names workload identity as a principal but does not show --workload-identity-subject or --workload-identity-claim. The CI/CD and workload identity pages still send readers to the binding pages for the full set of options.
  7. The akka_roles.adoc edit will be lost. The page is generated, and cmd/akka/role.go still has the old URL. Fix it in the CLI too. After the CLI release, regenerate the CLI docs and point the links labelled akka organizations role-bindings add at the real page.
  8. Aliases point to the overview page. Point manage-users at organization-role-bindings and manage-project-access at project-role-bindings, so old links land on matching content.

Nits

  • == Command names is development history, which the CLAUDE.md writing style excludes. If it stays for users of older CLIs, keep it short.
  • Rules need at least one of permissions or roles. The docs do not say so.
  • rbac/permissions.adoc gives the form <type>.<resource>.<operation>, but billing.account.contact.update has four segments. It also says you bind a permission, but you bind roles.
  • rbac-tables.js has dead code: the className parameter of cell, and removeAttribute('data-search').
  • The new rbac/* pages and the moved OIDC page lack some :page-*: metadata that docs/AGENTS.md expects.
  • 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-bindings mentions invitations for a custom role, but invitations create only takes --role. Can an invitation carry a custom role?

@jroper
jroper marked this pull request as draft November 2, 2026 02:15
@jroper
jroper force-pushed the jroper/custom-roles-docs branch from e69a35e to bef0800 Compare November 2, 2026 04:58
@jroper

jroper commented Nov 2, 2026

Copy link
Copy Markdown
Contributor Author

Response to review feedback:

  1. Updated to generate tables at build time. Still loads from dev. Will update to prod once prod is serving these files.
  2. Converted PR to draft
  3. Updated to UUIDs
  4. Updated example output, and included different principal types
  5. Updated llms.txt
  6. Switched to generating asciidoc tables at build time. Filter functionality won't work in formats other than HTML.
  7. Fixed by virtue of generating tables at build time.
  8. Documented relevance rule.
  9. Added docs for workload identity options.
  10. Created https://github.com/akka/cli/pull/243
  11. Updated aliases as suggested.

Nits:

  • Removed == Command names section.
  • Documented that at least one of permissions or roles is needed.
  • Updated metadata in docs

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.

@jroper
jroper force-pushed the jroper/custom-roles-docs branch from bef0800 to 74efac1 Compare November 2, 2026 05:08
@jroper

jroper commented Nov 2, 2026

Copy link
Copy Markdown
Contributor Author

Optimize docs build is failing.

@johanandren

Copy link
Copy Markdown
Contributor

Doc build should be fixed now

@ennru
ennru force-pushed the jroper/custom-roles-docs branch from 74efac1 to fcfcf5b Compare November 3, 2026 08:26
@ennru

ennru commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Rebased to have the latest CLI docs in scope.

@jroper

jroper commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

Cool, there's one issue - right now still pulling roles/permissions from dev, because the routes aren't deployed to prod.

@jroper
jroper marked this pull request as ready for review November 3, 2026 10:52
@jroper
jroper requested a review from johanandren November 3, 2026 10:53
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.
@jroper
jroper force-pushed the jroper/custom-roles-docs branch from fcfcf5b to 4374b97 Compare November 4, 2026 06:31
@jroper

jroper commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

Ok, this is now ready to merge, docs build points to api.kalix.io. @johanandren just waiting for review approval.

@johanandren
johanandren merged commit 5df08d0 into main Nov 4, 2026
64 of 65 checks passed
@johanandren
johanandren deleted the jroper/custom-roles-docs branch November 4, 2026 08:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants