SpiceDB setup

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 5.0’s multi-tenant architecture.

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.

For more information about SpiceDB, see the SpiceDB documentation.

Prerequisites

Infrastructure

Kubernetes cluster with admin access
PostgreSQL database server
Network connectivity between SpiceDB and FlowX services

FlowX Integration

FlowX 5.0+ platform components that will 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

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

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:

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

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:

# SpiceDB Operator Configuration
replicaCount: 1

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

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

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:

kubectl get pods -l app.kubernetes.io/name=spicedb-operator -n your-flowx-namespace

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:

-- 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;

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:

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:

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

Generate a secure preshared key using: openssl rand -base64 32

Step 4: Deploy SpiceDB cluster

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):

# 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):

# 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

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.

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

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:

FLOWX_SPICEDB_HOST: spicedb #default value
FLOWX_SPICEDB_PORT: 50051 #default value

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

FLOWX_SPICEDB_TOKEN: REPLACEME

Helm values configuration

Add the token reference to your Helm values using extraEnvVarsMultipleSecretsCustomKeys:

extraEnvVarsMultipleSecretsCustomKeys:
  - name: spicedb
    secrets:
      FLOWX_SPICEDB_TOKEN: preshared_key

This configuration tells Helm to:

Look for the existing Kubernetes Secret named spicedb (created in Step 3)
Take the value from the preshared_key key in that secret
Mount it as environment variable FLOWX_SPICEDB_TOKEN in FlowX service pods

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:

Check SpiceDB Pods

Ensure SpiceDB pods are running:

kubectl get pods -l app.kubernetes.io/name=spicedb

Test Connectivity

Verify SpiceDB is accessible on port 50051:

kubectl port-forward svc/spicedb 50051:50051
# Test connection from another terminal
grpcurl -plaintext localhost:50051 list

Check FlowX Integration

Review FlowX service logs for successful SpiceDB connection:

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

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

Microservices

Plugins

Observability

Access management

SpiceDB setup

Overview

Prerequisites

Infrastructure

FlowX Integration

FlowX customizations

Installation steps

Step 1: Install SpiceDB operator

Step 2: Create SpiceDB database

Step 3: Create Kubernetes Secret

Step 4: Deploy SpiceDB cluster

Step 5: Update FlowX services

Helm values configuration

Verification

Configuration reference

Required environment variables

Optional configuration

Customer-specific configuration

​Overview

​Prerequisites

Infrastructure

FlowX Integration

​FlowX customizations

​Installation steps

​Step 1: Install SpiceDB operator

​Step 2: Create SpiceDB database

​Step 3: Create Kubernetes Secret

​Step 4: Deploy SpiceDB cluster

​Step 5: Update FlowX services

​Helm values configuration

​Verification

​Configuration reference

​Required environment variables

​Optional configuration

​Customer-specific configuration

Overview

Prerequisites

FlowX customizations

Installation steps

Step 1: Install SpiceDB operator

Step 2: Create SpiceDB database

Step 3: Create Kubernetes Secret

Step 4: Deploy SpiceDB cluster

Step 5: Update FlowX services

Helm values configuration

Verification

Configuration reference

Required environment variables

Optional configuration

Customer-specific configuration