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

info

The SpiceDB and SpiceDB Operator images are hosted in the Istari Artifactory private registry. The configurations below reference the docker-pull-secret created in the Docker Pull Secret step. Ensure this secret exists before installing SpiceDB.

• For the SpiceDB Operator Helm chart, the imagePullSecrets field in the values file handles image pulling.
• For the SpiceDB Cluster custom resource, a ServiceAccount patch is used to attach the pull secret to the service account that the SpiceDB pods run under.

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: istaridigital.jfrog.io/customer-docker/istaridigital.com/spicedb-operator-fips
  tag: v1.23.0
imagePullSecrets:
  - name: docker-pull-secret

2. 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.5.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:
    image: istaridigital.jfrog.io/customer-docker/istaridigital.com/spicedb-fips:v1.49.2
    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"
  - kind: Service
    patch:
      spec:
        ports:
        # This will have no impact if Istio isn't installed.
        # It instructs Istio to use GRPC with the SpiceDB dispatch port (50053)
        - name: dispatch
          port: 50053
          targetPort: 50053
          appProtocol: grpc
  - kind: ServiceAccount
    patch:
      imagePullSecrets:
      - name: docker-pull-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:
    image: istaridigital.jfrog.io/customer-docker/istaridigital.com/spicedb-fips:v1.49.2
    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: ["--dispatch-upstream-addr=spicedb:50053", "--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: ["--dispatch-upstream-addr=spicedb:50053", "--skip-release-check=true"]
  - kind: Service
    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:
        ports:
        # This will have no impact if Istio isn't installed.
        # It instructs Istio to use GRPC with the SpiceDB dispatch port (50053)
        - name: dispatch
          port: 50053
          targetPort: 50053
          appProtocol: grpc
  - kind: ServiceAccount
    patch:
      imagePullSecrets:
      - name: docker-pull-secret

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.