SpiceDB Operator

A Kubernetes operator for managing SpiceDB clusters.

Features include:

• Creation, management, and scaling of SpiceDB clusters with a single Custom Resource
• Automated datastore migrations when upgrading SpiceDB versions

Have questions? Join our Discord.

Looking to contribute? See CONTRIBUTING.md.

Getting Started

In order to get started, you'll need a Kubernetes cluster. For local development, install your tool of choice. You can use whatever, so long as you're comfortable with it and it works on your platform. We recommend one of the following:

• Docker Desktop
• kind
• minikube

Next, you'll install a release of the operator:

kubectl apply --server-side -f https://github.com/authzed/spicedb-operator/releases/latest/download/bundle.yaml

Finally you can create your first cluster:

kubectl apply --server-side -f - <<EOF
apiVersion: authzed.com/v1alpha1
kind: SpiceDBCluster
metadata:
  name: dev
spec:
  config:
    datastoreEngine: memory
  secretName: dev-spicedb-config
---
apiVersion: v1
kind: Secret
metadata:
  name: dev-spicedb-config
stringData:
  preshared_key: "averysecretpresharedkey" 
EOF

Connecting To Your Cluster

If you haven't already, make sure you've installed zed.

Port forward the grpc endpoint:

kubectl port-forward deployment/dev-spicedb 50051:50051

Now you can use zed to interact with SpiceDB:

zed --insecure --endpoint=localhost:50051 --token=averysecretpresharedkey schema read

Where To Go From Here

• Check out the examples directory to see how to configure SpiceDBCluster for production, including datastore backends, TLS, and Ingress.
• Learn how to use SpiceDB via the docs and playground.
• Ask questions and join the community in discord.

Configuration

Datastore TLS Certificates

If your datastore requires TLS client certificates for authentication, you can configure SpiceDB to use them via the datastoreTLSSecretName configuration option.

When configured, the operator will mount the specified secret's contents at /spicedb-db-tls (read-only) in both the SpiceDB pods and migration jobs. You can then reference these certificate files in your datastore_uri connection string.

Example: PostgreSQL/CockroachDB with TLS

1. Create a Kubernetes secret containing your TLS certificates:

kubectl create secret generic my-db-tls \
  --from-file=ca.crt=/path/to/ca.crt \
  --from-file=tls.crt=/path/to/client.crt \
  --from-file=tls.key=/path/to/client.key

1. Configure your SpiceDBCluster to use the secret:

apiVersion: authzed.com/v1alpha1
kind: SpiceDBCluster
metadata:
  name: production
spec:
  config:
    datastoreEngine: cockroachdb
    datastoreTLSSecretName: my-db-tls
  secretName: production-spicedb-config
---
apiVersion: v1
kind: Secret
metadata:
  name: production-spicedb-config
stringData:
  datastore_uri: "postgresql://[email protected]:26257/spicedb?sslmode=verify-full&sslrootcert=/spicedb-db-tls/ca.crt&sslcert=/spicedb-db-tls/tls.crt&sslkey=/spicedb-db-tls/tls.key"
  preshared_key: "your-secret-key"

The certificates will be available at these paths inside the SpiceDB containers:

• /spicedb-db-tls/ca.crt - CA certificate
• /spicedb-db-tls/tls.crt - Client certificate
• /spicedb-db-tls/tls.key - Client private key

Note: The exact SSL parameter names depend on your datastore's connection driver. Consult your datastore's documentation for the correct connection string format.

Automatic and Suggested Updates

The SpiceDB operator now ships with a set of release channels for SpiceDB. Release channels allow the operator to walk through a safe series of updates, like the phased migration for postgres in SpiceDB v1.14.0

There are two ways you can choose to use update channels:

• automatic updates
• suggested updates

Which mode you choose depends on your tolerance for uncertainty. If possible, we recommend running a stage or canary instance with automatic updates enabled, and using suggested updates for production and production-like environments.

If no channel is selected, a default (stable) channel will be used for the selected datastore.

Available Update Channels:

Datastore	Channels
postgres	stable
cockroachdb	stable
mysql	stable
spanner	stable
memory	stable

Automatic Updates

If you do not specify a version that you want to run, the operator will always keep you up to date with the newest version in the channel.

If the operator or the update graph changes, the head of the channel may change and trigger an update.

apiVersion: authzed.com/v1alpha1
kind: SpiceDBCluster
metadata:
  name: dev
  namespace: default
spec:
  channel: stable 
  config:
    datastoreEngine: cockroachdb
status:
  version:
    name: v1.16.1
    channel: stable 

Suggested Updates

Even if you do not want automatic updates, you should choose an update channel - this ensures you do not miss important upgrade steps in phased migrations.

By specifying a version, the operator will install the specific version you have requested. If another version is already running, the operator will walk through the steps defined in the update channel, but will stop once it reaches version. No updates will be taken automatically, you must pick the next version to run and write it into the spec.version field. This keeps SpiceDB updates "on rails" while giving you full control over when and how to roll out updates.

Once you are at the specified version, the operator will inform you of available updates in the status of the SpiceDBCluster:

apiVersion: authzed.com/v1alpha1
kind: SpiceDBCluster
metadata:
  name: dev
spec:
  channel: stable 
  version: v1.14.0
  config:
    datastoreEngine: cockroachdb
status:
  version:
    name: v1.14.0
    channel: stable 
  availableVersions:
  - name: v1.14.1
    channel: stable
    description: direct update with no migrations

Note that it can also show you updates that are available in other channels, if you wish to switch back and forth (be careful! if you switch to another channel and update, there may not be a path to get back to the original channel!) Only the nearest-neighbor update will be shown for channels other than the current one.

Force Override

You can opt out of update channels entirely, and force spicedb-operator to install a specific image and manage it as a spicedb instance.

This is not recommended, but may be useful for development environments or to try prerelease versions of SpiceDB before they are in an update channel.

apiVersion: authzed.com/v1alpha1
kind: SpiceDBCluster
metadata:
  name: dev
spec:
  config:
    image: ghcr.io/authzed/spicedb:v1.11.0-prerelease

The Update Graph

Update channels are defined by an update graph, which the operator reads from the file passed to its --config flag. In the default deployment, this file is provided by the update-graph ConfigMap, which is generated from update-graph.yaml. The operator watches this file and picks up changes without a restart, and new releases of the operator ship with an updated graph that includes new SpiceDB versions.

Each channel in the graph lists the SpiceDB versions available for a datastore engine and the edges between versions that are known to be safe to update between, including any required migrations and phased rollouts. When updating a cluster, the operator walks these edges from the current version to the target version instead of jumping directly, so that required intermediate steps are not skipped.

The top-level imageName field in the graph defines the default image repository (ghcr.io/authzed/spicedb) that the tag or digest for each version is appended to; it is not a way to pin a specific version. To pull SpiceDB from a different registry (such as an internal mirror) while still following update channels, set .spec.baseImage on the SpiceDBCluster, or run the operator with the --base-image flag to change the default for all clusters, rather than editing the graph. Setting .spec.config.image to a specific tag or digest instead opts the cluster out of update channels entirely, as described in Force Override.

If more than one of these is set, the operator picks the image repository in this order: .spec.config.image, then .spec.baseImage, then the --base-image flag, then imageName from the update graph.