> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SpiceDB setup

> This guide covers the step-by-step installation and configuration of SpiceDB for FlowX deployments, including operator installation, database setup, and service integration.

## Overview

SpiceDB is a database for managing authorization policies. It is used to store and manage the authorization policies for the Authorization Service in FlowX's multi-tenant architecture.

<Info>
  **Scope: design-time permissions only.** SpiceDB backs build-time access checks in the FlowX Designer (who can edit which workspace, project, or resource). Runtime permissions — which end users can interact with which solution at execution time — use a separate, custom implementation that does not call SpiceDB. The two systems coexist and don't interact at runtime. See [Runtime authorization](./access-management/runtime-authorization) for the runtime model.
</Info>

<Info>
  For more information about SpiceDB, see the [SpiceDB documentation](https://authzed.com/docs/spicedb/getting-started/discovering-spicedb).
</Info>

## Prerequisites

<CardGroup cols={2}>
  <Card title="Infrastructure" icon="server">
    * Kubernetes cluster with admin access
    * PostgreSQL database server
    * Network connectivity between SpiceDB and FlowX services
  </Card>

  <Card title="FlowX Integration" icon="puzzle-piece">
    * FlowX platform components that integrate with SpiceDB
    * CAS client library configuration in all FlowX services
    * Proper secret management for authentication
  </Card>
</CardGroup>

## FlowX customizations

The FlowX platform includes several customizations to the standard SpiceDB deployment:

* **Namespace-restricted operator**: Uses Role and RoleBinding instead of ClusterRole and ClusterRoleBinding for enhanced security
* **Platform Health Monitoring**: Automatic health check configuration for FlowX platform monitoring (`/healthz` endpoint on port 8443)
* **Migration Job Optimization**: Configured retry limits (3 attempts) and timeouts (30 minutes) for schema migrations
* **Resource Optimization**: Production-ready resource requests and limits based on real-world usage
* **Service Annotations**: FlowX-specific service annotations for platform integration

<Warning>
  These customizations ensure SpiceDB operates securely within the FlowX platform architecture and integrates properly with platform monitoring and status systems.
</Warning>

## Installation steps

### Step 1: Install SpiceDB operator

<Info>
  The FlowX platform uses a customized SpiceDB operator that operates within a specific namespace, using Role and RoleBinding instead of ClusterRole and ClusterRoleBinding for enhanced security and isolation.
</Info>

Install the namespace-restricted SpiceDB operator using Helm:

```bash theme={"system"}
# Install the operator in the same namespace as FlowX
helm install spicedb-operator your-org/spicedb-operator \
  --namespace your-flowx-namespace \
  --create-namespace \
  --version <OPERATOR_VERSION>
```

<Info>
  The operator must be installed in the same namespace as FlowX because it operates with namespace-scoped permissions and cannot access other namespaces.
</Info>

**Example values.yaml for the operator:**

```yaml theme={"system"}
# SpiceDB Operator Configuration
replicaCount: 1

serviceAccount:
  create: true
  name: "spicedb-operator"

# Resource limits
resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi
```

<Warning>
  This operator is restricted to operate within a single namespace (the namespace where it is installed) and does not require cluster-wide permissions. The operator automatically watches the namespace where it is deployed.
</Warning>

Verify the operator is running:

```bash theme={"system"}
kubectl get pods -l app.kubernetes.io/name=spicedb-operator -n your-flowx-namespace
```

<Info>
  The operator pod will have a name in the format: `spicedb-operator-<hash>-<hash>` (e.g., `spicedb-operator-dd8f97d95-s78fc`)
</Info>

### Step 2: Create SpiceDB database

Create a dedicated PostgreSQL database and user for SpiceDB:

```sql theme={"system"}
-- Connect to PostgreSQL as admin user
CREATE DATABASE spicedb;
CREATE USER spicedb_user WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE spicedb TO spicedb_user;
```

<Warning>
  SpiceDB requires a dedicated PostgreSQL database. Do not share with other FlowX services.
</Warning>

### Step 3: Create Kubernetes Secret

Create the `spicedb` secret with the required credentials:

```yaml theme={"system"}
apiVersion: v1
kind: Secret
metadata:
  name: spicedb
type: Opaque
data:
  datastore_uri: <base64-encoded-postgres-connection-string>
  preshared_key: <base64-encoded-secure-token>
```

The secret should contain:

```bash theme={"system"}
# Raw values (encode these in base64 for the secret)
datastore_uri='postgres://USERNAME:PASSWORD@postgresql:5432/spicedb?sslmode=disable'
preshared_key='REPLACEME'
```

<Tip>
  Generate a secure preshared key using: `openssl rand -base64 32`
</Tip>

### Step 4: Deploy SpiceDB cluster

<Info>
  The FlowX platform uses a customized SpiceDB cluster chart that includes additional patches for platform status monitoring, health checks, and optimized resource configurations. The deployment uses a dedicated `spicedb` service account for proper RBAC permissions.
</Info>

Install the SpiceDB cluster using Helm (includes platform-status patches):

```bash theme={"system"}
# Install the cluster (using your organization's Helm repository)
helm install spicedb your-org/spicedb-cluster \
  --namespace your-namespace \
  --version <CHART_VERSION> \
  --set version=<SPICEDB_VERSION> \
  --set secretName=spicedb
```

**Custom values.yaml (optional):**

```yaml theme={"system"}
# FlowX SpiceDB Cluster Configuration
version: <SPICEDB_VERSION>
logLevel: debug
datastoreEngine: postgres
httpEnabled: true
secretName: spicedb
replicas: 2

# Optimized resource requests (matches production)
resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: "1"
    memory: 1Gi
```

<Info>
  **FlowX Platform Integration**: The FlowX SpiceDB chart automatically configures health monitoring annotations on the Service resource. These annotations are hardcoded in the chart and include:

  * `flowx.ai/health: "true"`
  * `flowx.ai/health-path: "/healthz"`
  * `flowx.ai/health-port: "8443"`

  No additional configuration is needed for platform health monitoring.
</Info>

<Warning>
  For production deployments, ensure `replicas: 2` or higher for high availability. The FlowX chart includes automatic health monitoring and migration job configurations.
</Warning>

### Step 5: Update FlowX services

<Info>
  The following services need a cas-lib configuration:

  * authorization-service
  * application-manager
  * authorization-system
  * cms-core
  * data-sync
  * document-plugin
  * integration-designer
  * notification-plugin
  * process-engine
  * runtime-manager
  * task-management-plugin
</Info>

Configure FlowX services to connect to SpiceDB. The following configuration values are already set by default in FlowX:

```bash theme={"system"}
FLOWX_SPICEDB_HOST: spicedb #default value
FLOWX_SPICEDB_PORT: 50051 #default value
```

**required configuration**: Add the SpiceDB token to your FlowX services:

```bash theme={"system"}
FLOWX_SPICEDB_TOKEN: REPLACEME
```

#### Helm values configuration

Add the token reference to your Helm values using `extraEnvVarsMultipleSecretsCustomKeys`:

```yaml theme={"system"}
extraEnvVarsMultipleSecretsCustomKeys:
  - name: spicedb
    secrets:
      FLOWX_SPICEDB_TOKEN: preshared_key
```

<Info>
  This configuration tells Helm to:

  1. Look for the existing Kubernetes Secret named `spicedb` (created in Step 3)
  2. Take the value from the `preshared_key` key in that secret
  3. Mount it as environment variable `FLOWX_SPICEDB_TOKEN` in FlowX service pods
</Info>

<Warning>
  **Token Synchronization**: The `preshared_key` value in the SpiceDB secret must match the `FLOWX_SPICEDB_TOKEN` in all FlowX microservices.
</Warning>

## Verification

Verify your SpiceDB deployment:

<Steps>
  <Step title="Check SpiceDB Pods">
    Ensure SpiceDB pods are running:

    ```bash theme={"system"}
    kubectl get pods -l app.kubernetes.io/name=spicedb
    ```
  </Step>

  <Step title="Test Connectivity">
    Verify SpiceDB is accessible on port 50051:

    ```bash theme={"system"}
    kubectl port-forward svc/spicedb 50051:50051
    # Test connection from another terminal
    grpcurl -plaintext localhost:50051 list
    ```
  </Step>

  <Step title="Check FlowX Integration">
    Review FlowX service logs for successful SpiceDB connection:

    ```bash theme={"system"}
    kubectl logs -l app=authorization-system | grep -i spicedb
    ```
  </Step>
</Steps>

## Configuration reference

### Required environment variables

| Variable                     | Required | Description                            | Default Value                                                          | Notes                                                                                |
| ---------------------------- | -------- | -------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `SPICEDB_DATASTORE_ENGINE`   | ✅        | Database engine type                   | `postgres`                                                             | Only PostgreSQL is supported in FlowX                                                |
| `SPICEDB_DATASTORE_CONN_URI` | ✅        | PostgreSQL connection string           | `postgres://postgres:password@postgresql:5432/spicedb?sslmode=disable` | Use Kubernetes Secret - include `sslmode=disable` for internal cluster communication |
| `SPICEDB_GRPC_PRESHARED_KEY` | ✅        | Pre-shared key for gRPC authentication | `your-secure-key-here`                                                 | **This becomes `FLOWX_SPICEDB_TOKEN` in FlowX services**                             |

### Optional configuration

| Variable                           | Required | Description                               | Default Value | Notes                                                      |
| ---------------------------------- | -------- | ----------------------------------------- | ------------- | ---------------------------------------------------------- |
| `SPICEDB_DISPATCH_CLUSTER_ENABLED` | ⚠️       | Enable cluster mode for multiple replicas | `true`        | Required for production deployments with multiple replicas |
| `SPICEDB_LOG_LEVEL`                | ⚠️       | Logging verbosity level                   | `debug`       | Use `debug` for troubleshooting, `info` for production     |

## Customer-specific configuration

<Warning>
  **Required Customization**: These values must be updated for each deployment environment.
</Warning>

* **Database Connection**: Update `datastore_uri` with your PostgreSQL credentials and hostname
* **Security Token**: Generate a unique `preshared_key` for your deployment