--- slug: /install/control-plane/SpiceDB sidebar_position: 8 sidebar_label: SpiceDB --- # 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: ```yaml title="spicedb-secret.yaml" apiVersion: v1 kind: Secret metadata: name: spicedb stringData: datastore_uri: "postgres://spicedb:@:5432/spicedb" preshared_key: "" ``` **Replace the following placeholders with your values:** - ``: The password for the SpiceDB database. password is obtained from the [AWS](../control-plane/aws-installation/Database#create-istari-platform-databases-and-users) or [Azure](../control-plane/azure-installation/Database#create-istari-platform-databases-and-users) PostgreSQL Install step - ``: The hostname of the SpiceDB database. Hostname is obtained from the [AWS](../control-plane/aws-installation/Database#create-istari-platform-databases-and-users) or [Azure](../control-plane/azure-installation/Database#create-istari-platform-databases-and-users) PostgreSQL Install step - ``: 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: ```bash 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](https://github.com/authzed/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 Digital artifact registry (`istaridigital.jfrog.io`). Create `docker-pull-secret` using credentials from the [Istari Customer Portal](../02-customer-portal.md); see [Docker Pull Secret](./03-Docker-Pull-Secret.md). 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: ```yaml title="spicedb-operator-values.yaml" image: repository: istaridigital.jfrog.io/customer-docker/istaridigital.com/spicedb-operator-fips tag: v1.24.0 imagePullSecrets: - name: docker-pull-secret ``` 2. Install the SpiceDB Operator using Helm: ```bash helm repo add spicedb https://bushelpowered.github.io/spicedb-operator-chart/ helm repo update helm upgrade --install spicedb-operator spicedb/spicedb-operator --version 2.6.0 -f spicedb-operator-values.yaml ``` :::tip For further configuration, refer to the [SpiceDB Operator documentation](https://github.com/authzed/spicedb-operator#configuration). ::: #### 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 ```yaml title="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.51.1 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: ```yaml title="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.51.1 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](https://authzed.com/docs/spicedb/concepts/operator#passing-additional-configuration). ## 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](../control-plane/Istari-Platform#secrets): ```yaml 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.