Skip to main content
Cerbos requires a storage backend to load and manage policies. The storage driver is specified in the main configuration section.

​
Storage Driver Selection

​
storage.driver
string
required
Storage backend to use. Valid values: disk, git, blob, postgres, mysql, sqlite3.
storage:
  driver: disk

​
Disk Storage

Store policies in a local directory. Ideal for development and simple deployments.
​
storage.disk.directory
string
required
Path to the directory containing policy files.
​
storage.disk.watchForChanges
boolean
default:"false"
required
Enable automatic policy reloading when files change.
storage:
  driver: disk
  disk:
    directory: /var/cerbos/policies
    watchForChanges: true
File watching uses filesystem notifications for efficient change detection. On some systems, you may need to increase inotify limits.

​
Git Storage

Fetch policies from a Git repository with automatic updates.
​
storage.git.protocol
string
required
Git protocol to use: https, ssh, or file.
​
storage.git.url
string
required
URL to the Git repository.
​
storage.git.branch
string
default:"master"
Branch to checkout.
​
storage.git.subDir
string
Subdirectory within the repository where policies are stored.
​
storage.git.checkoutDir
string
Local directory to checkout the repository to. Defaults to system cache directory.
​
storage.git.updatePollInterval
duration
default:"0s"
Interval to poll for repository updates. Set to 0 to disable polling.
​
storage.git.operationTimeout
duration
default:"60s"
Timeout for Git operations (clone, fetch, pull).

​
HTTPS Authentication

​
storage.git.https.username
string
Username for HTTPS authentication.
​
storage.git.https.password
string
Password or personal access token for HTTPS authentication.
storage:
  driver: git
  git:
    protocol: https
    url: https://github.com/example/policies.git
    branch: main
    subDir: cerbos/policies
    checkoutDir: /var/cerbos/git
    updatePollInterval: 60s
    https:
      username: ${GIT_USERNAME}
      password: ${GITHUB_TOKEN}

​
SSH Authentication

​
storage.git.ssh.user
string
default:"git"
SSH user for authentication.
​
storage.git.ssh.privateKeyFile
string
Path to the SSH private key file.
​
storage.git.ssh.password
string
Password for the SSH private key (if encrypted).
storage:
  driver: git
  git:
    protocol: ssh
    url: git@github.com:example/policies.git
    branch: main
    ssh:
      user: git
      privateKeyFile: /home/cerbos/.ssh/id_rsa
      password: ${SSH_KEY_PASSWORD}

​
File Protocol

storage:
  driver: git
  git:
    protocol: file
    url: file:///var/repos/policies
    branch: main
    updatePollInterval: 30s

​
Blob Storage (S3, GCS, Azure)

Fetch policies from cloud blob storage with automatic updates.
​
storage.blob.bucket
string
required
Bucket URL. Format depends on provider:
  • S3: s3://bucket-name?region=us-east-1
  • GCS: gs://bucket-name
  • Azure: azblob://container-name
​
storage.blob.prefix
string
Prefix (subdirectory) within the bucket to download policies from.
​
storage.blob.workDir
string
Local directory to download policies to. Defaults to system cache directory.
​
storage.blob.updatePollInterval
duration
default:"0s"
Interval to poll for bucket updates. Set to 0 to disable polling.
​
storage.blob.downloadTimeout
duration
default:"60s"
Timeout for downloading from cloud storage.
​
storage.blob.requestTimeout
duration
default:"5s"
Timeout for individual HTTP requests to cloud storage.

​
AWS S3

storage:
  driver: blob
  blob:
    bucket: s3://my-policies-bucket?region=us-west-2
    prefix: cerbos/policies
    workDir: /var/cerbos/work
    updatePollInterval: 60s
    downloadTimeout: 30s
    requestTimeout: 10s
S3 authentication uses the default AWS credential chain (environment variables, IAM role, shared credentials file).

​
Google Cloud Storage

storage:
  driver: blob
  blob:
    bucket: gs://my-policies-bucket
    prefix: policies
    updatePollInterval: 60s
GCS authentication uses Application Default Credentials (ADC).

​
Azure Blob Storage

storage:
  driver: blob
  blob:
    bucket: azblob://my-container
    prefix: policies
    updatePollInterval: 60s
Azure authentication uses environment variables (AZURE_STORAGE_ACCOUNT, AZURE_STORAGE_KEY) or managed identity.

​
PostgreSQL Storage

Store policies in a PostgreSQL database.
​
storage.postgres.url
string
required
PostgreSQL connection URL. Format: postgres://user:password@host:port/database?options
​
storage.postgres.skipSchemaCheck
boolean
default:"false"
Skip checking for required database schema on startup.

​
Connection Pool

​
storage.postgres.connPool.maxLifeTime
duration
Maximum lifetime of a connection.
​
storage.postgres.connPool.maxIdleTime
duration
Maximum time a connection can be idle.
​
storage.postgres.connPool.maxOpen
integer
Maximum number of open connections.
​
storage.postgres.connPool.maxIdle
integer
Maximum number of idle connections.

​
Connection Retry

​
storage.postgres.connRetry.maxAttempts
integer
default:"3"
Maximum number of connection attempts.
​
storage.postgres.connRetry.initialInterval
duration
Initial wait time between retry attempts.
​
storage.postgres.connRetry.maxInterval
duration
Maximum wait time between retry attempts.
storage:
  driver: postgres
  postgres:
    url: postgres://cerbos:password@localhost:5432/cerbos?sslmode=require
    connPool:
      maxLifeTime: 60m
      maxIdleTime: 45s
      maxOpen: 10
      maxIdle: 2
    connRetry:
      maxAttempts: 5
      initialInterval: 500ms
      maxInterval: 60s
Ensure the database schema is initialized before starting Cerbos. Use the schema migration scripts provided in the Cerbos distribution.

​
MySQL Storage

Store policies in a MySQL/MariaDB database.
​
storage.mysql.dsn
string
required
MySQL data source name (DSN). Format: user:password@tcp(host:port)/database?options
​
storage.mysql.skipSchemaCheck
boolean
default:"false"
Skip checking for required database schema on startup.

​
Connection Pool and Retry

Same options as PostgreSQL: connPool and connRetry.

​
TLS Configuration

​
storage.mysql.tls
object
Map of TLS configuration names to certificate paths.
​
storage.mysql.serverPubKey
object
Map of server public key names to file paths.
storage:
  driver: mysql
  mysql:
    dsn: cerbos:password@tcp(localhost:3306)/cerbos?tls=custom&interpolateParams=true
    tls:
      custom:
        cert: /etc/cerbos/tls/client.crt
        key: /etc/cerbos/tls/client.key
        caCert: /etc/cerbos/tls/ca.crt
    connPool:
      maxLifeTime: 60m
      maxIdleTime: 45s
      maxOpen: 4
      maxIdle: 1
    connRetry:
      maxAttempts: 3
      initialInterval: 500ms
      maxInterval: 60s
The interpolateParams=true option is recommended for better performance and security.

​
SQLite Storage

Store policies in an SQLite database file.
​
storage.sqlite3.dsn
string
required
SQLite data source name. Can be a file path or :memory: for in-memory database.
storage:
  driver: sqlite3
  sqlite3:
    dsn: "/var/cerbos/db/policies.db?_fk=true"

storage:
  driver: sqlite3
  sqlite3:
    dsn: ":memory:?_fk=true"
SQLite is suitable for development and small deployments. For production use with multiple instances, use PostgreSQL or MySQL.
The _fk=true parameter enables foreign key constraints, which is recommended.

​
Complete Examples

​
Production Git Setup

storage:
  driver: git
  git:
    protocol: https
    url: https://github.com/acme/policies.git
    branch: production
    subDir: cerbos
    updatePollInterval: 300s
    operationTimeout: 120s
    https:
      username: bot-account
      password: ${GITHUB_TOKEN}

​
Production S3 Setup

storage:
  driver: blob
  blob:
    bucket: s3://acme-cerbos-policies?region=eu-west-1
    prefix: prod/policies
    updatePollInterval: 120s
    downloadTimeout: 60s

​
Production PostgreSQL Setup

storage:
  driver: postgres
  postgres:
    url: postgres://cerbos:${DB_PASSWORD}@db.internal:5432/cerbos?sslmode=verify-full&sslrootcert=/etc/cerbos/ca.crt
    connPool:
      maxLifeTime: 3600s
      maxIdleTime: 300s
      maxOpen: 20
      maxIdle: 5
    connRetry:
      maxAttempts: 5
      initialInterval: 1s
      maxInterval: 30s