​
Overview

SpiceDB is a database for managing authorization policies. It is used to store and manage the authorization policies for the Authorization Service.
For more information about SpiceDB, see the SpiceDB documentation.

​
Prerequisites

  • A Kubernetes cluster
  • A PostgreSQL database
  • A SpiceDB instance

​
Core configuration variables

VariableRequiredDescriptionExampleNotes
SPICEDB_DATASTORE_ENGINE✅Database engine typepostgresOnly PostgreSQL is supported in FlowX
SPICEDB_DATASTORE_CONN_URI✅PostgreSQL connection stringpostgres://postgres:password@postgresql-spicedb:5432/spicedb?sslmode=disableInclude sslmode=disable for internal cluster communication

​
Authentication & security

VariableRequiredDescriptionExampleNotes
SPICEDB_GRPC_PRESHARED_KEY✅Pre-shared key for gRPC authenticationyour-secure-key-hereMust match FlowX Engine’s SPICEDB_TOKEN
SPICEDB_GRPC_NO_TLS⚠️Disable TLS for gRPC connectionstrueSet to true for internal Kubernetes communication

​
Logging & debugging

VariableRequiredDescriptionExampleNotes
SPICEDB_LOG_LEVEL⚠️Logging verbosity leveldebugUse debug for troubleshooting, info for production

​
Application behavior variables

​
HTTP API configuration

VariableRequiredDescriptionExampleNotes
SPICEDB_HTTP_ENABLED⚠️Enable HTTP API servertrueRequired for health checks and debugging

​
Startup & bootstrap

VariableRequiredDescriptionExampleNotes
SPICEDB_DATASTORE_BOOTSTRAP_OVERWRITE⚠️Allow schema overwrite during bootstraptrueUseful for development; be cautious in production

​
Shutdown behavior

VariableRequiredDescriptionExampleNotes
SPICEDB_GRPC_SHUTDOWN_GRACE_PERIOD⚠️Grace period before forced shutdown1sAllows graceful connection termination

​
Telemetry & monitoring

VariableRequiredDescriptionExampleNotes
SPICEDB_TELEMETRY_ENDPOINT⚠️Telemetry collection endpoint"" (empty)Set to empty string to disable telemetry

​
Init container environment variables

​
PostgreSQL readiness check (wait-for-postgres)

VariableRequiredDescriptionExampleNotes
PGHOST✅PostgreSQL hostnamepostgresql-spicedbKubernetes service name
PGPORT✅PostgreSQL port5432Standard PostgreSQL port
PGUSER✅PostgreSQL usernamepostgresDatabase user for connection testing
PGPASSWORD✅PostgreSQL passwordyour-db-passwordShould be stored in Kubernetes Secret

​
Database migration (spicedb-migrate)

The migration init container uses the same core SpiceDB variables:
VariableRequiredDescriptionExampleNotes
SPICEDB_DATASTORE_ENGINE✅Database engine typepostgresSame as main container
SPICEDB_LOG_LEVEL⚠️Migration logging leveldebugHelpful for troubleshooting migrations
SPICEDB_DATASTORE_CONN_URI✅Database connection stringpostgres://postgres:password@postgresql-spicedb:5432/spicedb?sslmode=disableSame as main container

​
FlowX Engine integration variables

The FlowX Engine requires these environment variables to connect to SpiceDB:
VariableDescriptionValueNotes
SPICEDB_ENDPOINTSpiceDB gRPC endpointspicedb-service:50051Kubernetes service name and gRPC port
SPICEDB_TOKENAuthentication tokenSame as SPICEDB_GRPC_PRESHARED_KEYMust match exactly
SPICEDB_INSECURESkip TLS verificationtrue for internal clusterSet to false when using TLS

​
Troubleshooting environment variables

​
Enable debug logging

- name: SPICEDB_LOG_LEVEL
  value: debug

​
Database Connection Issues

Verify the connection string format: 
# Test connection from within cluster
psql "postgres://postgres:password@postgresql-spicedb:5432/spicedb?sslmode=disable"

​
Authentication Problems

Ensure preshared keys match between SpiceDB and FlowX Engine: 
# Check SpiceDB logs for authentication errors
kubectl logs deployment/spicedb | grep -i "auth\|preshared"

​
Environment Variable Validation

​
Required Variables Checklist

Before deploying SpiceDB, ensure these variables are set:
  • ✅ SPICEDB_DATASTORE_ENGINE=postgres
  • ✅ SPICEDB_DATASTORE_CONN_URI (valid PostgreSQL connection string)
  • ✅ SPICEDB_GRPC_PRESHARED_KEY (secure random string)
  • ✅ SPICEDB_LOG_LEVEL=info (or debug for troubleshooting)
  • ✅ SPICEDB_HTTP_ENABLED=true (for health checks)
  • ✅ SPICEDB_TELEMETRY_ENDPOINT="" (disable telemetry)

​
FlowX specific

  • ✅ SPICEDB_GRPC_NO_TLS=true (for internal Kubernetes communication)
  • ✅ SPICEDB_GRPC_SHUTDOWN_GRACE_PERIOD=1s (graceful shutdowns)