add documentation for SpiceDB Dedicated Fine-Grained Access Management #104
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
6320851
to
85f012a
Compare
- support goes to the bottom, is probably not the first item folks entering Authzed/SpiceDB world want to see - given we are going to put additional top level product pages, add gRPC and REST as children of the SpiceDB section - rename API Reference in references section to gRPC API Reference, and add HTTP as well
this also adds a sidebar entry for SpiceDB Dedicated
85f012a
to
75c7940
Compare
sidebars.js
Outdated
| { | ||
| type: 'link', | ||
| label: 'gRPC API Reference', | ||
| href: 'https://buf.build/authzed/api/docs/main:authzed.api.v1', | ||
| }, | ||
| { | ||
| type: 'link', | ||
| label: 'REST API Reference', | ||
| href: 'https://www.postman.com/authzed/workspace/spicedb/overview', | ||
| }, | ||
| 'support', |
There was a problem hiding this comment.
These were all explicitly at the top due to their importance.
There was a problem hiding this comment.
I understood that. The main motivation to this change is that our docs are going to grow as we document APIs exclusive to SpiceDB Dedicated and SpiceDB Cloud. Folks will have to expand the SpiceDB menu to find them.
Admittedly I don't understand how this is going to affect the discoverability of these entries
docs/spicedb-dedicated/fgam.md
Outdated
| @@ -0,0 +1,141 @@ | |||
| # Fine-Grained Access Management | |||
|
|
|||
| With SpiceDB Fine Grained Access Management (FGAM) you can authorize access to your permission system using the familar RBAC (Role-Based Access Control) paradigm. The basic concepts are: | |||
There was a problem hiding this comment.
Try and keep one sentence per line. It'll make diffs and suggestions easier in the long term.
Let's avoid calling it "SpiceDB Fine Grained Access Management" and instead just refer to it as "Fine-Grained Access Management".
I took a stab at this opening few sentences to include a reference to IAM.
Fine Grained Access Management is an optional feature used to manage the access to permission systems deployed with SpiceDB Dedicated.
Those familiar with configuring IAM on any major cloud provider should feel comfortable with the basic concepts:
- Service Accounts represent workloads (e.g. an application calling the SpiceDB API)
- Roles grant access to APIs and subsets of relationships using [CEL expressions]
- Policies bind a Service Account to a Role
|
|
||
| Any of the public API types will be avaliable to the expression language, so you can traverse any type and their fields using language operators. For more details on CEL's language definition, please refer to [CEL's language specification](https://github.com/google/cel-spec/blob/81e07d7cf76e7fc89b177bd0fdee8ba6d6604bf5/doc/langdef.md). | ||
|
|
||
| ## Example: assign read-only role to service account |
There was a problem hiding this comment.
I think this section is the only one that should include screenshots.
There was a problem hiding this comment.
you mean instead of GIFs?
docs/spicedb-dedicated/fgam.md
Outdated
|
|
||
| ## Example: assign read-only role to service account | ||
|
|
||
| Let's illustrate how you can create a read-only role for your service. You should start by making sure your Permission System has Fine-Grained Access Management enabled. This can be done at permission system creation time, by enabling the corresponding option. |
There was a problem hiding this comment.
What do you do if already have a permission system?
There was a problem hiding this comment.
It's not supported yet.
3ed6df3
to
5fa6448
Compare
5fa6448
to
627366a
Compare
627366a
to
21aa6fc
Compare
The main goal of this PR is to add documentation for SpiceDB Dedicated's new Fine-Grained Access Management documentation. It does a bunch of changes to the sidebar structure too, to better start distinguishing Dedicated vs SpiceDB docs