docs: refresh permission key form and drop removed app.admin.users config - #1901
Conversation
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe documentation updates revise custom permission management, replace email-based admin promotion with service account bootstrapping, and document ChangesCustom permission documentation
Admin bootstrap configuration
Declarative reconciliation kinds
Estimated code review effort: 3 (Moderate) | ~20 minutes Merge Risk: 🟡 Moderate · up to The updated documentation still omits required admin.bootstrap validation and contains two smaller inaccuracies about custom permissions and MetaSchema resets, which could mislead users into invalid configuration or incorrect reconciliation expectations. Merge should wait until these documentation contracts are corrected or explicitly accepted. 🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
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. Comment |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Coverage Report for CI Build 32702111414Warning Build has drifted: This PR's base is out of sync with its target branch, so coverage data may include unrelated changes. Coverage increased (+0.08%) to 48.886%Details
Uncovered ChangesNo uncovered changes found. Coverage RegressionsNo coverage regressions found. Coverage Stats
💛 - Coveralls |
![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
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 9b037ce0-5807-4494-a740-f682a67928d2
📒 Files selected for processing (7)
docs/content/docs/authz/permission.mdxdocs/content/docs/authz/policy.mdxdocs/content/docs/basics.mdxdocs/content/docs/configurations.mdxdocs/content/docs/reference/cli.mdxdocs/content/docs/reference/configurations.mdxdocs/rfcs/0001-declarative-reconcile.md
Included review availability: Your plan provides up to 2 included reviews per hour; 0 remain after this review.
| can be configured in the [config.yaml](https://github.com/raystack/frontier/blob/7fca56ef567791bf4ea1280aa3f9b4ae997b1bf5/config/sample.config.yaml#L29) | ||
| file. Same is also exposed in the [Frontier API](../apis/admin-service-create-permission.api.mdx) to create | ||
| custom permissions on a project resource. | ||
| hardcoded in the schema, but Frontier allows custom permission set on Project resources. Custom permissions are managed through the [reconcile flow](../reconcile.md) (a `kind: Permission` desired-state file) or the [CreatePermission admin API](../apis/admin-service-create-permission). Creating one merges it into the SpiceDB schema, so the permission is ready to use in roles right away. The older way of declaring them in the server config file has been removed. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the documented scope of custom permissions.
This sentence limits custom permissions to Project resources. docs/content/docs/authz/permission.mdx documents potato.cart.*, and internal/reconcile/permission_reconciler_test.go reconciles compute.order.get. Replace the Project-specific wording with a scope-neutral statement.
Proposed wording
- hardcoded in the schema, but Frontier allows custom permission set on Project resources.
+ hardcoded in the schema, and Frontier also supports custom permissions.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| hardcoded in the schema, but Frontier allows custom permission set on Project resources. Custom permissions are managed through the [reconcile flow](../reconcile.md) (a `kind: Permission` desired-state file) or the [CreatePermission admin API](../apis/admin-service-create-permission). Creating one merges it into the SpiceDB schema, so the permission is ready to use in roles right away. The older way of declaring them in the server config file has been removed. | |
| hardcoded in the schema, and Frontier also supports custom permissions. Custom permissions are managed through the [reconcile flow](../reconcile.md) (a `kind: Permission` desired-state file) or the [CreatePermission admin API](../apis/admin-service-create-permission). Creating one merges it into the SpiceDB schema, so the permission is ready to use in roles right away. The older way of declaring them in the server config file has been removed. |
| # bootstrap seeds a superuser service account from config. Automation such as | ||
| # the GitOps reconcile flow logs in as it, so there is always a superuser | ||
| # without needing an existing one. Log in with: | ||
| # Authorization: Basic base64(client_id:client_secret). | ||
| bootstrap: | ||
| client_id: "" | ||
| client_secret: "" |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Document the complete admin.bootstrap contract.
The bootstrap implementation disables the feature only when both fields are empty. Otherwise, it requires both fields and validates client_id as a UUID. The documentation omits these constraints, and the reference table marks the fields independently optional.
docs/content/docs/basics.mdx#L53-L59: document the UUID and paired-field requirements.docs/content/docs/configurations.mdx#L150-L158: document the UUID and paired-field requirements.docs/content/docs/reference/configurations.mdx#L123-L131: document the UUID and paired-field requirements.docs/content/docs/reference/configurations.mdx#L277-L278: mark the fields as jointly required when bootstrap is enabled.
📍 Affects 3 files
docs/content/docs/basics.mdx#L53-L59(this comment)docs/content/docs/configurations.mdx#L150-L158docs/content/docs/reference/configurations.mdx#L123-L131docs/content/docs/reference/configurations.mdx#L277-L278
| plans and the products they bundle), and `MetaSchema` (metadata validation | ||
| schemas, where a schema left out resets to its shipped default). |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Clarify which MetaSchema omission resets the schema.
The phrase “a schema left out” suggests that omitting the schema field from an entry resets it. internal/reconcile/metaschema.go, Lines 104-126, rejects such an entry because schema is required. The reset applies when the built-in MetaSchema entry is omitted entirely, as documented in docs/rfcs/0001-declarative-reconcile.md, Lines 235-239.
Rewrite this as “a built-in MetaSchema entry left out resets to its shipped default.”
🧰 Tools
🪛 LanguageTool
[style] ~256-~256: To strengthen your wording, consider replacing the phrasal verb “leave out”.
Context: ...data validation schemas, where a schema left out resets to its shipped default). Deletin...
(OMIT_EXCLUDE)
3 participants
What
Refresh the docs that fell behind recent changes to permissions and the boot config. Two themes, one commit each.
Permission key form and reconcile kinds
authz/permission.mdx: the "Custom Permissions" section taught the oldname+namespacecreate model, which is no longer accepted. Rewrote it around thekey(service.resource.verb), replaced the name/namespace sample table with akeytable, swapped the link to the removed resource-config testdata for akind: Permissiondesired-state example, and reframed the slug note (dots become underscores).authz/policy.mdx: removed the description of the boot-time custom-permission loader and itsconfig.yamlrule-set link. Custom permissions are now created through reconcile or the admin API.reference/cli.mdx: theexportandreconcile"supported kinds" lists showed only 5 kinds. AddedMetaSchema,BillingProduct, andBillingPlan, and noted that a billing product or plan cannot be deleted through the API. This now matches the CLI help incmd/reconcile.go.rfcs/0001-declarative-reconcile.md: the summary sentence listed 5 kinds; added the other three. Added MetaSchema to the value node in the diagram. Removed "Billing plans as a kind" from Future work since it shipped.Removed app.admin.users config
The server no longer reads
app.admin.users(superuser promotion from a config list is gone; the bootstrap service account replaced it). Updated the sample config and the config reference to useadmin.bootstrap(client_id / client_secret) instead:configurations.mdxandreference/configurations.mdx: replaced theadmin.usersblock with theadmin.bootstrapblock, updated the config-reference table row, and dropped a stale "resource config cache refreshed" line from the sample startup log.basics.mdx: same block replacement, and the field summary line.Docs only. No code change.