Skip to main content

SpiceDB

SpiceDB is a database for managing permissions and relationships. It is designed to be used in a microservices architecture, where it can help manage complex access control scenarios. It is built on the principles of the Google Zanzibar paper, which describes a system for managing permissions at scale. SpiceDB is open-source and can be deployed in various environments, including Kubernetes. It is used by the Istari Digital Platform to manage permissions in our Zero Trust and Zero Knowledge system and must be setup before installing the Istari Digital Platform.

SpiceDB Cluster Secret​

The secret is used to store sensitive information related to the SpiceDB cluster. The secret should be created in the Kubernetes cluster where the SpiceDB cluster will be deployed.

Secret Manifest

The manifest for the secret should look like the following:

spicedb-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: spicedb
stringData:
  datastore_uri: "postgres://spicedb:<password>@<host>:5432/spicedb"
  preshared_key: "<preshared_key>"

Replace the following placeholders with your values:

  • <password>: The password for the SpiceDB database. password is obtained from the AWS or Azure PostgreSQL Install step
  • <host>: The hostname of the SpiceDB database. Hostname is obtained from the AWS or Azure PostgreSQL Install step
  • <preshared_key>: The preshared key used by applications to authenticate with the SpiceDB cluster.

Create the Secret

Apply the secret to your Kubernetes cluster using the following command:

kubectl apply -f spicedb-secret.yaml

SpiceDB Installation​

You should be using the SpiceDB Operator, which automatically handles SpiceDB upgrades. Note that this will install a CRD (Custom Resource Definition).

SpiceDB Operator​

Production Kubernetes users should be relying on a stable release of the SpiceDB Operator. The Operator enforces best practices and orchestrates SpiceDB updates without downtime. It will also manage version upgrades without manual user interaction. The SpiceDB Operator is a Kubernetes operator that automates the deployment and management of SpiceDB clusters. It simplifies the process of running SpiceDB in a Kubernetes environment, ensuring that the database is properly configured and maintained. The SpiceDB Operator handles tasks such as scaling, upgrades, and monitoring, making it easier to manage SpiceDB in production environments.

The installation comes in two parts: Operator installation and SpiceDB cluster installation. The operator is responsible for managing the SpiceDB cluster, while the cluster installation involves creating the necessary resources and configurations for SpiceDB to run.

SpiceDB Operator installation​

To install the SpiceDB operator, follow these steps:

  1. Create the file spicedb-operator-values.yaml with the following content:
spicedb-operator-values.yaml
image:
  repository: ghcr.io/authzed/spicedb-operator
  tag: v1.18.0
  # # If using images from a private repo, also uncomment the
  # # following lines & replace '<image_pull_secret>' with the name of the Kubernetes secret used to pull images
  # imagePullSecrets:
  # - name: <image_pull_secret>
  1. Install the SpiceDB Operator using Helm:
helm repo add spicedb https://bushelpowered.github.io/spicedb-operator-chart/
helm repo update
helm upgrade --install spicedb-operator spicedb/spicedb-operator --version 2.0.0 -f spicedb-operator-values.yaml
tip

For further configuration, refer to the SpiceDB Operator documentation.

SpiceDB Cluster installation​

Once the SpiceDB Operator is installed, you can create a SpiceDB cluster by applying custom resource definitions (CRDs) to your Kubernetes cluster. The SpiceDB Operator will take care of deploying and managing the SpiceDB cluster for you.

SpiceDB Cluster Definition​
spicedb-cluster.yaml
apiVersion: authzed.com/v1alpha1
kind: SpiceDBCluster
metadata:
  name: spicedb
spec:
  secretName: spicedb
  config:
    replicas: 3
    datastoreEngine: postgres
    logLevel: info
  patches:
  - kind: Job
    patch:
      spec:
        template:
          metadata:
            labels:
              # This label will have no impact if Istio isn't installed.
              # We disable Istio here because the spicedb-migrate pod sometimes has trouble shutting down
              # when it is enabled, and traffic from this pod is egress to RDS, not intra-cluster.
              sidecar.istio.io/inject: "false"
  # # If using images from a private repo, also uncomment this ServiceAccount section and
  # # replace '<image_pull_secret>' with the name of the Kubernetes secret used to pull images
  # - kind: ServiceAccount   
  #   patch:
  #     metadata:
  #       labels:                         
  #     # This is necessary when pulling images from a private registry
  #     imagePullSecrets:
  #     - name: <image_pull_secret>  # Replace with your image secret

Advanced SpiceDB Cluster Definition

The SpiceDB cluster definition can be customized further by adding additional configuration options. Best approach is to use patches part of the CRD. The following is an example of a SpiceDB cluster definition with additional configuration options:

spicedb-cluster-advanced.yaml
apiVersion: authzed.com/v1alpha1
kind: SpiceDBCluster
metadata:
  name: spicedb
spec:
  secretName: spicedb
  config:
    replicas: 3
    datastoreEngine: postgres
    logFormat: json
    logLevel: warn  # Allowed values: "trace", "debug", "info", "warn", "error"
  patches:
  - kind: Deployment
    patch:
      metadata:
        labels:
          app: spicedb
          app.kubernetes.io/component: spicedb
          app.kubernetes.io/instance: spicedb
          app.kubernetes.io/managed-by: spicedb-operator
          app.kubernetes.io/name: spicedb
      spec:
        template:
          metadata:
            labels:
              app: spicedb
              app.kubernetes.io/component: spicedb
              app.kubernetes.io/instance: spicedb
              app.kubernetes.io/managed-by: spicedb-operator
              app.kubernetes.io/name: spicedb
          spec:
            containers:
            - name: spicedb
              # Avoid dialing out for a release check since this requires internet access and
              # SpiceDB Operator version support lags behind the latest SpiceDB release
              args: ["--skip-release-check=true"]
  - kind: Job
    patch:
      metadata:
        labels:
          app: spicedb-migrate
          app.kubernetes.io/component: spicedb-migrate
          app.kubernetes.io/instance: spicedb-migrate
          app.kubernetes.io/managed-by: spicedb-operator
          app.kubernetes.io/name: spicedb
      spec:
        template:
          metadata:
            labels:
              app: spicedb-migrate
              app.kubernetes.io/component: spicedb-migrate
              app.kubernetes.io/instance: spicedb-migrate
              app.kubernetes.io/managed-by: spicedb-operator
              app.kubernetes.io/name: spicedb
              # This label will have no impact if Istio isn't installed.
              # We disable Istio here because the spicedb-migrate pod sometimes has trouble shutting down
              # when it is enabled, and traffic from this pod is egress to RDS, not intra-cluster.
              sidecar.istio.io/inject: "false"
          spec:
            containers:
            - name: migrate
              args: ["--skip-release-check=true"]

The above example shows how to customize the SpiceDB cluster definition with additional configuration options. The patches section allows you to modify the deployment of the SpiceDB cluster, including labels and annotations. For more information on the available configuration options, refer to the SpiceDB documentation.

TLS​

If you do not want to use TLS with SpiceDB — since e.g. the service mesh already enforces TLS on all connections — then add this additional environment variable to your fileservice2-env Kubernetes secrets:

FILE_SERVICE_AUTHZED_NO_TLS: "true"

If you do want to use TLS with SpiceDB then you will need to create a DNS record for SpiceDB and an endpoint that can be used to terminate TLS for it.