mgagliardo91 / spicedb-operator

Kubernetes controller for managing instances of SpiceDB

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 the operator:

kubectl apply --server-side -k github.com/authzed/spicedb-operator/config

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.

Updating SpiceDBClusters

The operator handles the rollout of SpiceDB upgrades, inluding coordinating migrations. By default, the operator will upgrade all SpiceDBClusters that it manages when the operator sees a new default image in the config (see default-operator-config.yaml for the current default images). This config can be updated manually, but it is also updated with each release of spicedb-operator and included in the operator image.

If you wish to opt out of automated updates, you can specify an image for the SpiceDBCluster in the config:

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

The spicedb-operator will happily attempt to run any image you specify, but if you specify an image that is not in the list of allowedImages, allowedTags, or allowedDigests, the status will warn you:

status:
  conditions:
  - lastTransitionTime: "2022-09-02T21:49:19Z"
    message: '["ubuntu" invalid: "ubuntu" is not in the configured list of allowed
      images"]'
    reason: WarningsPresent
    status: "True"
    type: ConfigurationWarning