From 68da6f6d6cd5bcb81e5e62a4ddd3a009687127c0 Mon Sep 17 00:00:00 2001 From: Catherine Chambers Date: Mon, 24 Aug 2026 10:15:39 -0400 Subject: [PATCH 1/3] docs(deployments): clarify SpiceDB vCPUs vs datastore vCPUs Add a new Deployments concept page and cross-link it from the Cloud getting-started guide, with a callout distinguishing SpiceDB compute (configured per Deployment) from datastore compute, which scales independently. Co-Authored-By: Claude Sonnet 5 --- app/authzed/concepts/deployments/page.mdx | 51 ++++++++++++++++++++++ app/authzed/concepts/multi-region/page.mdx | 3 +- app/authzed/guides/cloud/page.mdx | 6 +++ 3 files changed, 59 insertions(+), 1 deletion(-) create mode 100644 app/authzed/concepts/deployments/page.mdx diff --git a/app/authzed/concepts/deployments/page.mdx b/app/authzed/concepts/deployments/page.mdx new file mode 100644 index 00000000..bb155d5c --- /dev/null +++ b/app/authzed/concepts/deployments/page.mdx @@ -0,0 +1,51 @@ +--- +title: "Deployments" +description: "A single, independently-scaled SpiceDB cluster that serves a Permission System from one region." +--- + +import { Callout } from "nextra/components"; + +# Deployments + +A Deployment is a single running SpiceDB cluster that serves a Permission System from one region. + +Every Permission System is made up of one or more Deployments, each sharing the same underlying [Datastore]. +In the simplest case, a Permission System has exactly one Deployment running in one region. +Adding more Deployments lets the same Permission System serve traffic from additional regions at once — see [Multi-Region Deployments]. + +[Datastore]: ../../spicedb/concepts/datastores +[Multi-Region Deployments]: ../multi-region + +## Deployments vs. Permission Systems + +A Permission System is the logical authorization system: its schema, its relationships, and the datastore that stores them. +A Deployment is the compute that actually serves requests for that Permission System from a specific region. + +This split is why a single Permission System can run in multiple regions without duplicating data: each Deployment is a separate SpiceDB cluster, but all of a Permission System's Deployments read from and write to the same datastore. + +## What you configure per Deployment + +When you add a Deployment to a Permission System, you choose: + +- **Name** — how the Deployment is identified in the Management Dashboard. +- **Region** — where the SpiceDB cluster runs. +- **vCPUs** — the amount of compute allocated to each replica. +- **Replicas** — how many SpiceDB instances serve the Deployment. More replicas increase availability and read throughput. + + + The vCPUs and replicas you configure here are for **SpiceDB's compute** — the layer that serves Check, LookupResources, and other API requests. + They are separate from the compute provisioned for your [Datastore], which scales independently based on data volume and read/write load. + +If requests are slow or timing out, check which side is the bottleneck before resizing: high SpiceDB CPU or request queuing points to under-provisioned Deployment vCPUs, while slow query latency at the datastore points to the datastore needing more resources instead. + + + +Each Deployment exposes its own endpoint. +There is no global endpoint that automatically routes requests to the nearest Deployment — your workloads should connect to the endpoint of the Deployment closest to them to minimize latency. + +## Workload isolation + +Deployments on AuthZed Dedicated and Cloud run on hardware dedicated to your organization, separate from the shared control plane services (such as the Management Dashboard and observability tooling). +See [Workload Isolation] for details. + +[Workload Isolation]: ../workload-isolation diff --git a/app/authzed/concepts/multi-region/page.mdx b/app/authzed/concepts/multi-region/page.mdx index 3df1ae0a..01c4795b 100644 --- a/app/authzed/concepts/multi-region/page.mdx +++ b/app/authzed/concepts/multi-region/page.mdx @@ -5,8 +5,9 @@ description: "A collection of SpiceDB deployments located in different regions w # Multi-Region Deployments -Multi-Region Deployments are a collection of SpiceDB deployments that can be located in various regions across the world, but that all share a single [Datastore]. +Multi-Region Deployments are a collection of [Deployments] that can be located in various regions across the world, but that all share a single [Datastore]. +[Deployments]: ../deployments [Datastore]: ../../spicedb/concepts/datastores ## Connecting to a region diff --git a/app/authzed/guides/cloud/page.mdx b/app/authzed/guides/cloud/page.mdx index b740984b..b9883563 100644 --- a/app/authzed/guides/cloud/page.mdx +++ b/app/authzed/guides/cloud/page.mdx @@ -30,6 +30,12 @@ Sign in to [AuthZed Cloud](https://app.authzed.cloud) and click on the **+Create - Choose the number of vCPUs for your deployment. The recommendation is to start with 2 vCPUs and then monitor the Metrics and change it based on your workload. - Choose the number of replicas to deploy SpiceDB with primarily read workloads. The recommendation is 3 but will depend on your latency requirements. + + These vCPUs provision **SpiceDB's compute**, not your datastore's. See [What you configure per + Deployment](/authzed/concepts/deployments#what-you-configure-per-deployment) for how the two scale + independently. + + ## Configuring Access Before using the Permissions System, let's configure access to it. From 0acca8b43d639909a855a72cefe008c92e629b9d Mon Sep 17 00:00:00 2001 From: Catherine Chambers Date: Mon, 24 Aug 2026 10:15:56 -0400 Subject: [PATCH 2/3] chore: regenerate changed-pages manifest Co-Authored-By: Claude Sonnet 5 --- lib/changed-pages.json | 39 +++------------------------------------ 1 file changed, 3 insertions(+), 36 deletions(-) diff --git a/lib/changed-pages.json b/lib/changed-pages.json index 28a924b4..161367dc 100644 --- a/lib/changed-pages.json +++ b/lib/changed-pages.json @@ -1,44 +1,11 @@ { - "/materialize/api/client-sdks": { - "status": "updated" - }, - "/materialize/api/download-permission-sets": { - "status": "new" - }, - "/materialize/api/lookup-permission-sets": { - "status": "updated" - }, - "/materialize/api/watch-permission-sets": { - "status": "updated" - }, - "/materialize/concepts/hydration": { - "status": "new" - }, - "/materialize/concepts/managing-client-state": { - "status": "updated" - }, - "/materialize/concepts/permission-set-lifecycle": { - "status": "updated" - }, - "/materialize/concepts/permission-sets": { - "status": "updated" - }, - "/materialize/concepts/snapshots": { - "status": "updated" - }, - "/materialize/concepts/watched-permissions": { + "/authzed/concepts/deployments": { "status": "new" }, - "/materialize/getting-started/limitations": { - "status": "updated" - }, - "/materialize/getting-started/overview": { - "status": "updated" - }, - "/materialize/guides/recommended-architecture": { + "/authzed/concepts/multi-region": { "status": "updated" }, - "/materialize/guides/relational-database": { + "/authzed/guides/cloud": { "status": "updated" } } From 00c86cb8939995cdbd4231e483df7761bc7daaf5 Mon Sep 17 00:00:00 2001 From: Catherine Chambers Date: Mon, 24 Aug 2026 11:26:08 -0400 Subject: [PATCH 3/3] fix(docs): repair broken relative links between deployments/workload-isolation/multi-region Links between sibling pages under app/authzed/concepts/ used an extra ../, which resolves one directory too high in the browser (e.g. /authzed/workload-isolation instead of /authzed/concepts/workload-isolation). Co-Authored-By: Claude Sonnet 5 --- app/authzed/concepts/deployments/page.mdx | 4 ++-- app/authzed/concepts/multi-region/page.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/app/authzed/concepts/deployments/page.mdx b/app/authzed/concepts/deployments/page.mdx index bb155d5c..9eb1a8de 100644 --- a/app/authzed/concepts/deployments/page.mdx +++ b/app/authzed/concepts/deployments/page.mdx @@ -14,7 +14,7 @@ In the simplest case, a Permission System has exactly one Deployment running in Adding more Deployments lets the same Permission System serve traffic from additional regions at once — see [Multi-Region Deployments]. [Datastore]: ../../spicedb/concepts/datastores -[Multi-Region Deployments]: ../multi-region +[Multi-Region Deployments]: multi-region ## Deployments vs. Permission Systems @@ -48,4 +48,4 @@ There is no global endpoint that automatically routes requests to the nearest De Deployments on AuthZed Dedicated and Cloud run on hardware dedicated to your organization, separate from the shared control plane services (such as the Management Dashboard and observability tooling). See [Workload Isolation] for details. -[Workload Isolation]: ../workload-isolation +[Workload Isolation]: workload-isolation diff --git a/app/authzed/concepts/multi-region/page.mdx b/app/authzed/concepts/multi-region/page.mdx index 01c4795b..3f59fb1d 100644 --- a/app/authzed/concepts/multi-region/page.mdx +++ b/app/authzed/concepts/multi-region/page.mdx @@ -7,7 +7,7 @@ description: "A collection of SpiceDB deployments located in different regions w Multi-Region Deployments are a collection of [Deployments] that can be located in various regions across the world, but that all share a single [Datastore]. -[Deployments]: ../deployments +[Deployments]: deployments [Datastore]: ../../spicedb/concepts/datastores ## Connecting to a region