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.

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