Open
Conversation
This reverts commit 23492e8.
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
Files changed:
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
jhlodin
requested changes
Feb 17, 2026
Contributor
jhlodin
left a comment
jhlodin
left a comment
There was a problem hiding this comment.
Large portions of the integration guide are documenting a third party product's marketing and workflows, when realistically a third party integration guide on our docs should be scoped to information relevant to CRDB and link out to their docs for any specifics.
Comment on lines
+8
to
+19
| [AuthZed](https://authzed.com/) is a platform focused exclusively on *authorization*. In contrast to authentication, which verifies a user's identity, authorization decides a user's access rights for resources once their identity is known. AuthZed centralizes, unifies, and scales this core security layer so developers don’t have to implement their own permission logic in every application. | ||
|
|
||
| SpiceDB is the core engine behind all AuthZed products. It is designed to be entirely agnostic to authentication solutions and identity providers. SpiceDB is a graph engine that centrally stores authorization data (relationships and permissions). Authorization requests (for example, checkPermission, lookupResources) are resolved via a dispatcher that traverses the permission graph. | ||
|
|
||
| <img src="{{ 'images/v26.1/authzed_design.png' | relative_url }}" alt="AuthZed architecture design" style="border:1px solid #eee;max-width:80%;margin:auto;display:block" /> | ||
|
|
||
| SpiceDB is available in multiple forms depending on deployment and support needs: | ||
|
|
||
| - [SpiceDB (Open Source)](https://authzed.com/spicedb): The foundational, community-driven version of the authorization engine, free to use and self-hosted under the Apache 2.0 license. | ||
| - [SpiceDB Enterprise](https://authzed.com/products/spicedb-enterprise): A self-managed enterprise edition that includes audit logging, fine-grained API control, FIPS-validated cryptography, and dedicated support. | ||
| - [AuthZed Dedicated](https://authzed.com/products/authzed-dedicated): A fully managed, single-tenant SaaS offering that provides all enterprise features along with global, regionally distributed deployments and integrated APIs for permission filtering. | ||
| - [AuthZed Cloud](https://authzed.com/products/authzed-cloud): A multi-tenant managed platform designed for teams that want to start quickly without operational overhead. |
Contributor
There was a problem hiding this comment.
We shouldn't be hosting a writeup of a third party's product offerings. This should be a simple intro paragraph describing what AuthZed is and its relationship with SpiceDB, and how CockroachDB is well-suited to host SpiceDB at scale
Contributor
There was a problem hiding this comment.
@jhlodin This is an integration section, which is by default involving other products integrating with CRDB. It is related to our ISV partnership program, and one of the main goals of having this in the integrate section of our documentation, is to have complete guides for people willing to work with CRDB as an underlying infrastructure for these 3rd party solutions.
Think about the user experience and how complex could be switching from our website to some references in the partners websites just to create a simple 5-min integration?!
Contributor
There was a problem hiding this comment.
Here is an example on how we configure egress endpoints in AWS or GCP: https://www.cockroachlabs.com/docs/cockroachcloud/egress-private-endpoints
It is too specific to cloud providers and not related to CRDB, but this config was necessary to showcase the integration.
Comment on lines
+23
to
+25
| ## Set up a joint CockroachDB/AuthZed environment | ||
|
|
||
| Imagine that you’re building a global content management application that uses SpiceDB, as the access control system backed by CockroachDB across multiple regions. This tutorial walks you through the manual setup of a joint CockroachDB/AuthZed environment. |
Contributor
There was a problem hiding this comment.
Rather than a separate section, this should be a single sentence at the end of the intro section.
| To complete this tutorial, you will need: | ||
|
|
||
| - A local copy of a [supported CockroachDB binary]({% link {{ page.version.version }}/install-cockroachdb.md %}). | ||
| - Network access from your SpiceDB runtime to port `26257`. |
Contributor
There was a problem hiding this comment.
Access to port 26257 on what? I'd assume on the CockroachDB infrastructure
Comment on lines
+40
to
+43
| #### Create a secure cluster locally | ||
| If you have the CockroachDB binary installed locally, you can manually deploy a multi-node, self-hosted CockroachDB cluster on your local machine. | ||
|
|
||
| Learn how to [deploy a CockroachDB cluster locally]({% link {{ page.version.version }}/secure-a-cluster.md %}). |
Contributor
There was a problem hiding this comment.
Should remove, or at least move to the bottom of these options. A local deployment is just a test deployment.
Comment on lines
+45
to
+48
| #### Create a CockroachDB Self-Hosted cluster on AWS | ||
| You can manually deploy a multi-node, self-hosted CockroachDB cluster on Amazon's AWS EC2 platform, using AWS's managed load-balancing service to distribute client traffic. | ||
|
|
||
| Learn how to [deploy a CockroachDB cluster on AWS]({% link {{ page.version.version }}/deploy-cockroachdb-on-aws.md %}). |
|
|
||
| ### Step 3. Install and configure SpiceDB | ||
|
|
||
| 1. Install the SpiceDB binary for your given system (supported systems include [macOS](https://authzed.com/docs/spicedb/getting-started/install/macos), [Docker](https://authzed.com/docs/spicedb/getting-started/install/docker), [Kubernetes](https://authzed.com/docs/spicedb/getting-started/install/kubernetes), [Ubuntu/Debian](https://authzed.com/docs/spicedb/getting-started/install/debian), [RHEL/CentOS](https://authzed.com/docs/spicedb/getting-started/install/rhel), and [Windows](https://authzed.com/docs/spicedb/getting-started/install/windows)). |
Contributor
There was a problem hiding this comment.
Should be a single link to SpiceDB's installation guides. No reason to list their supported systems here.
Contributor
There was a problem hiding this comment.
@jhlodin There is no single guide to install SpiceDB. The install is OS-Specific
Comment on lines
+105
to
+272
| ### Step 4. Install the AuthZed CLI | ||
|
|
||
| 1. To interact with SpiceDB through the zed (AuthZed) CLI, [install the latest binary releases of zed](https://authzed.com/docs/spicedb/getting-started/installing-zed). | ||
|
|
||
| 2. Once installed, connect to the SpiceDB instance exposed in the client with the following command. For local development, you can use the `--insecure` flag to connect over plaintext. Be sure to use the same `{preshared-key}` that you used in the preceding step. Replace the `{spicedb-ip}` placeholder with the IP of your SpiceDB instance: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| zed context set my_context {spicedb-ip}:50051 {preshared-key} --insecure | ||
| ~~~ | ||
|
|
||
| 3. Check that the command worked by running: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| zed version | ||
| ~~~ | ||
|
|
||
| If the output indicates that the server version is `unknown`, then your CLI was unable to connect. You may need to verify the values in previous steps, such as the `{preshared-key}`, the IP or the port that your SpiceDB instance is running on. | ||
|
|
||
| When successfully executed, `zed version` should output something similar to the following: | ||
|
|
||
| ~~~ | ||
| client: zed v0.31.1 | ||
| service: v1.45.4 | ||
| ~~~ | ||
|
|
||
| You can interact with SpiceDB using the AuthZed CLI, with the [HTTP API](https://authzed.com/docs/spicedb/api/http-api) or with the [gRPC API](https://buf.build/authzed/api/docs/main:authzed.api.v1). The remaining instructions will demonstrate how to use both the AuthZed CLI and the HTTP API to complete the integration. | ||
|
|
||
| ### Step 5. Define the authorization schema | ||
|
|
||
| The first step in developing an authorization relationship schema is defining one or more object types. For example, you could define the following object relationships: | ||
|
|
||
| <img src="{{ 'images/v26.1/authzed_schema.png' | relative_url }}" alt="AuthZed sample schema diagram" style="border:1px solid #eee;max-width:80%;margin:auto;display:block" /> | ||
|
|
||
| The main two items in this example are the `user` and `document` objects. The `user` can be a `viewer`, an `editor` or an `admin`. The definition gives the `remove` permission to the `admin` role only. To `edit` a file the user must be either an `editor` or an `admin`. The permission to `view` a document is set for the `viewer`, `editor` and `admin` roles. | ||
|
|
||
| #### Use the AuthZed CLI | ||
|
|
||
| 1. Define the schema by writing the following file: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ | ||
| definition user {} | ||
|
|
||
| definition document { | ||
| relation editor: user | ||
| relation viewer: user | ||
| relation admin: user | ||
|
|
||
| permission view = viewer + editor + admin | ||
| permission edit = editor + admin | ||
| permission remove = admin | ||
| } | ||
| ~~~ | ||
|
|
||
| Save this file as `schema.zed`. | ||
|
|
||
| 1. Apply the schema to SpiceDB, pointing to the saved `schema.zed` file. | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| zed schema write ./schema.zed | ||
| ~~~ | ||
|
|
||
| 1. To verify that this has worked, run the following command, which should print the applied schema: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| zed schema read | ||
| ~~~ | ||
|
|
||
| #### Use the HTTP API | ||
|
|
||
| Embed the schema definition within a [`WriteSchemaRequest`](https://authzed.com/docs/spicedb/api/http-api#/Schema/SchemaService_WriteSchema) body, making sure to replace the `{spicedb-ip}` placeholder with the IP of your SpiceDB instance, and the `{preshared-key}` placeholder with value defined in [Step 3](#step-3-install-and-configure-spicedb): | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --location 'http://{spicedb-ip}:8443/v1/schema/write' \ | ||
| --header 'Content-Type: application/json' \ | ||
| --header 'Accept: application/json' \ | ||
| --header 'Authorization: Bearer {preshared-key}' \ | ||
| --data '{ | ||
| "schema": "definition user {} \n definition document { \n relation editor: user \n relation viewer: user \n relation admin: user \n permission view = viewer + editor + admin \n permission edit = editor + admin \n permission remove = admin \n}" | ||
| }' | ||
| ~~~ | ||
|
|
||
| If successful, that request will return a response which includes a token: | ||
|
|
||
| ~~~ | ||
| {"writtenAt":{"token":"GhUKEzE3NTgxMjkyOTM0MDE2MDYxNDA="}} | ||
| ~~~ | ||
|
|
||
| ### Step 6. Define authorization relationships | ||
|
|
||
| In SpiceDB, relationships are represented as tuples. Each tuple contains a _resource_, a _relation_ and a _subject_. In this example, the resource is the name of a `document`, the relation is either `admin`, `viewer` or `editor`, and the subject is the name of a `user`. | ||
|
|
||
| In this scenario, make user `alice` an `admin` for `doc1`. This means that she can `view`, `edit`, and `remove` the document. Then make user `bob` a `viewer` for `doc1`. This means he can `view` the document. | ||
|
|
||
| #### Use the AuthZed CLI | ||
|
|
||
| Define a new relationship for a `document` called `doc1`. Use the following command to make `alice` an `admin` for `doc1`: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| zed relationship touch document:doc1 admin user:alice | ||
| ~~~ | ||
|
|
||
| Define a new relationship for `doc1`. Use the following command to make `bob` a `viewer` for `doc1`: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| zed relationship touch document:doc1 viewer user:bob | ||
| ~~~ | ||
|
|
||
| #### Use the HTTP API | ||
|
|
||
| Define the relationships in a [`WriteRelationshipsRequest`](https://authzed.com/docs/spicedb/api/http-api#/Permissions/PermissionsService_WriteRelationships) body, making sure to replace the `{spicedb-ip}` placeholder with the IP of your SpiceDB instance, and the `{preshared-key}` placeholder with value defined in [Step 3](#step-3-install-and-configure-spicedb): | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --location 'http://{spicedb-ip}:8443/v1/relationships/write' \ | ||
| --header 'Content-Type: application/json' \ | ||
| --header 'Accept: application/json' \ | ||
| --header 'Authorization: Bearer {preshared-key}' \ | ||
| --data '{ | ||
| "updates": [ | ||
| { | ||
| "operation": "OPERATION_TOUCH", | ||
| "relationship": { | ||
| "resource": { | ||
| "objectType": "document", | ||
| "objectId": "doc1" | ||
| }, | ||
| "relation": "admin", | ||
| "subject": { | ||
| "object": { | ||
| "objectType": "user", | ||
| "objectId": "alice" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| { | ||
| "operation": "OPERATION_TOUCH", | ||
| "relationship": { | ||
| "resource": { | ||
| "objectType": "document", | ||
| "objectId": "doc1" | ||
| }, | ||
| "relation": "viewer", | ||
| "subject": { | ||
| "object": { | ||
| "objectType": "user", | ||
| "objectId": "bob" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ] | ||
| }' | ||
| ~~~ | ||
|
|
||
| If successful, that request will return a response which includes a token: | ||
|
|
||
| ~~~ | ||
| {"writtenAt":{"token":"GhUKEzE3NTgxMjk3MDg2NTc4MDQ5ODk="}} | ||
| ~~~ |
Contributor
There was a problem hiding this comment.
All of this content is specific to AuthZed/SpiceDB and has nothing to do with the underlying CockroachDB infrastructure. This should all be replaced with a link to AuthZed documentation so we aren't documenting a third party product.
Contributor
There was a problem hiding this comment.
@jhlodin This is an integration section, which is by default involving other products integrating with CRDB. It is related to our ISV partnership program, and one of the main goals of having this in the integrate section of our documentation, is to have complete guides for people willing to work with CRDB as an underlying infrastructure for these 3rd party solutions.
Think about the user experience and how complex could be switching from our website to some references in the partners websites just to create a simple 5-min integration?!
Contributor
There was a problem hiding this comment.
Here is an example on how we configure egress endpoints in AWS or GCP: https://www.cockroachlabs.com/docs/cockroachcloud/egress-private-endpoints
It is too specific to cloud providers and not related to CRDB, but this config was necessary to showcase the integration.
Comment on lines
+278
to
+352
| ### Check user permissions | ||
|
|
||
| Verify that AuthZed has captured the authorization data that you have defined. | ||
|
|
||
| #### Use the AuthZed CLI | ||
|
|
||
| To check that our schema is working correctly, issue `check` requests. As `bob` is only a `viewer` for `doc1`, you can expect him to have the `view` permission but not the `edit` or `remove` permissions: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| zed permission check document:doc1 view user:bob | ||
| # true | ||
| ~~~ | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| zed permission check document:doc1 edit user:bob | ||
| # false | ||
| ~~~ | ||
|
|
||
| Because `alice` is an `admin`, she has all permissions: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| zed permission check document:doc1 view user:alice | ||
| # true | ||
| ~~~ | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| zed permission check document:doc1 remove user:alice | ||
| # true | ||
| ~~~ | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| zed permission check document:doc1 edit user:alice | ||
| # true | ||
| ~~~ | ||
|
|
||
| #### Use the HTTP API | ||
|
|
||
| Define the permission that you want to check within a [`CheckPermissionRequest`](https://authzed.com/docs/spicedb/api/http-api#/Permissions/PermissionsService_CheckPermission) body. This check includes a `user`, a `resource`, and an `action`. Make sure to replace the `{spicedb-ip}` placeholder with the IP of your SpiceDB instance, and the `{preshared-key}` placeholder with value defined in [Step 3](#step-3-install-and-configure-spicedb): | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --location 'http://{spicedb-ip}:8443/v1/permissions/check' \ | ||
| --header 'Content-Type: application/json' \ | ||
| --header 'Accept: application/json' \ | ||
| --header 'Authorization: Bearer {preshared-key}' \ | ||
| --data '{ | ||
| "consistency": { | ||
| "minimizeLatency": true | ||
| }, | ||
| "resource": { | ||
| "objectType": "document", | ||
| "objectId": "doc1" | ||
| }, | ||
| "permission": "view", | ||
| "subject": { | ||
| "object": { | ||
| "objectType": "user", | ||
| "objectId": "bob" | ||
| } | ||
| } | ||
| }' | ||
| ~~~ | ||
|
|
||
| If successful, that request will return a response which includes a token. That token will include a `permissionship` item, that explains whether the given `user` has permission to perform the given `action` on the given `resource`: | ||
|
|
||
| ~~~ | ||
| {"checkedAt":{"token":"GhUKEzE3NTgxMjk5NTAwMDAwMDAwMDA="}, "permissionship":"PERMISSIONSHIP_NO_PERMISSION"} | ||
| ~~~ | ||
|
|
||
| Send another `CheckPermissionRequest` for each permission that you want to check. |
Contributor
There was a problem hiding this comment.
This should all be a link to AuthZed documentation about how to read permissions. None of this is specific to CRDB
amine-crl
reviewed
Feb 17, 2026
| namespace | object_id | relation | userset_namespace | userset_object_id | timestamp | expires_at | ||
| ------------+-----------+----------+-------------------+-------------------+----------------------------+------------- | ||
| document | doc1 | admin | user | alice | 2026-01-06 18:28:21.12613 | NULL | ||
| document | doc1 | viewer | user | bob | 2026-01-06 18:28:23.226998 | NULL |
Contributor
There was a problem hiding this comment.
@bsanchez-the-roach add a space in the second row for column timestamp
amine-crl
reviewed
Feb 17, 2026
Contributor
amine-crl
left a comment
amine-crl
left a comment
There was a problem hiding this comment.
added comments to the doc review
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Re-do of PR 22589, which was prematurely merged before getting a doc review.