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 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. See Runtime authorization for the runtime model.

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:

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

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:

   kubectl get pods -l app.kubernetes.io/name=spicedb
   
2. 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
   
3. 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