> ## 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.

> [!NOTE]
>
> **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](https://docs.flowx.ai/6.x/setup-guides/access-management/runtime-authorization.md) for the runtime model.

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

## Prerequisites

> [card] Infrastructure
>
> * Kubernetes cluster with admin access
> * PostgreSQL database server
> * Network connectivity between SpiceDB and FlowX services

> [card] FlowX Integration
>
> * FlowX platform components that integrate with SpiceDB
> * CAS client library configuration in all FlowX services
> * Proper secret management for authentication

## 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.

## Installation steps

### Step 1: Install SpiceDB operator

> [!NOTE]
>
> 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.

Install the namespace-restricted SpiceDB operator using Helm:

```bash theme={"dark"}
# 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>
```

> [!NOTE]
>
> The operator must be installed in the same namespace as FlowX because it operates with namespace-scoped permissions and cannot access other namespaces.

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

```yaml theme={"dark"}
# 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.

Verify the operator is running:

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

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

### Step 2: Create SpiceDB database

Create a dedicated PostgreSQL database and user for SpiceDB:

```sql theme={"dark"}
-- 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.

### Step 3: Create Kubernetes Secret

Create the `spicedb` secret with the required credentials:

```yaml theme={"dark"}
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={"dark"}
# 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`

### Step 4: Deploy SpiceDB cluster

> [!NOTE]
>
> 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.

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

```bash theme={"dark"}
# 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={"dark"}
# 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
```

> [!NOTE]
>
> **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.

> [!WARNING]
>
> For production deployments, ensure `replicas: 2` or higher for high availability. The FlowX chart includes automatic health monitoring and migration job configurations.

### Step 5: Update FlowX services

> [!NOTE]
>
> 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

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

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

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

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

#### Helm values configuration

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

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

> [!NOTE]
>
> 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

> [!WARNING]
>
> **Token Synchronization**: The `preshared_key` value in the SpiceDB secret must match the `FLOWX_SPICEDB_TOKEN` in all FlowX microservices.

## Verification

Verify your SpiceDB deployment:

**1. Check SpiceDB Pods**

Ensure SpiceDB pods are running:

```bash theme={"dark"}
kubectl get pods -l app.kubernetes.io/name=spicedb
```

**2. Test Connectivity**

Verify SpiceDB is accessible on port 50051:

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

**3. Check FlowX Integration**

Review FlowX service logs for successful SpiceDB connection:

```bash theme={"dark"}
kubectl logs -l app=authorization-system | grep -i spicedb
```

## 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.

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


## Related topics

- [FlowX.AI architecture: services, layers, and data flow](https://docs.flowx.ai/6.x/docs/platform-overview/flowx-architecture.md)
- [Microservices setup guides](https://docs.flowx.ai/6.x/setup-guides/setup-guides-overview.md)
- [Prerequisites](https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/prerequisites.md)
- [License service setup](https://docs.flowx.ai/6.x/setup-guides/license-engine-setup.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.