Storage block

Cerbos supports multiple backends for storing policies. Which storage driver to use is defined by the driver setting.

Blob driver

Cerbos policies can be stored in AWS S3, Google Cloud Storage, or any other S3-compatible storage systems such as Minio.

Configuration keys

• bucket: Required. A URL specifying the service (e.g. S3, GCS), the storage bucket and any other configuration parameters required by the provider.
  • AWS S3: s3://my-bucket?region=us-west-1. Must specify region in the URL.
  • Google Cloud Storage: gs://my-bucket
  • S3-compatible (e.g. Minio): s3://my-bucket?endpoint=http://my.minio.local:8080&hostname_immutable=true&region=local. Must specify region in the URL.
• prefix: Optional. Look for policies only under this key prefix.
• workDir: Optional. Path to the local directory to download the policies to. Defaults to the system cache directory if not specified.
• updatePollInterval: Optional. How frequently the blob store should be checked to discover new or updated policies. Defaults to 0 — which disables polling.
• requestTimeout: Optional. HTTP request timeout. It takes an HTTP request to download a policy file. Defaults to 5s.
• downloadTimeout: Optional. Timeout to download all policies from the storage provider. Must be greater than the requestTimeout. Defaults to 60s.

Credentials

Credentials for accessing the storage buckets are retrieved from the environment. The method of specifying credentials in the environment varies by cloud provider and security configuration.

AWS Example Configuration

storage:
  driver: "blob"
  blob:
    bucket: "s3://my-bucket-name?region=us-east-2"
    prefix: policies
    workDir: ${HOME}/tmp/cerbos/work
    updatePollInterval: 15s
    downloadTimeout: 30s
    requestTimeout: 10s

Google Cloud Storage Example Configuration

storage:
  driver: "blob"
  blob:
    bucket: "gs://my-bucket-name"
    workDir: ${HOME}/tmp/cerbos/work
    updatePollInterval: 10s

Minio Local Container Example Configuration

storage:
  driver: "blob"
  blob:
    bucket: "s3://my-bucket-name?endpoint=http://localhost:9000&hostname_immutable=true&region=local"
    workDir: ${HOME}/tmp/cerbos/work
    updatePollInterval: 10s

Disk driver

The disk driver is a way to serve the policies from a directory on the filesystem. Any .yaml, .yml or .json files in the directory tree rooted at the given path will be read and parsed as policies.

Example Configuration (Static Fileset)

storage:
  driver: disk
  disk:
    directory: /etc/cerbos/policies

Example Configuration (Dynamic Fileset)

storage:
  driver: disk
  disk:
    directory: /etc/cerbos/policies
    watchForChanges: true

Git driver

Git is the preferred method of storing Cerbos policies. The server is smart enough to detect when new commits are made to the git repository and refresh its state based on the changes.

Local Git Repository Example Configuration

storage:
  driver: "git"
  git:
    protocol: file
    url: file://${HOME}/tmp/cerbos/policies
    checkoutDir: ${HOME}/tmp/cerbos/work
    updatePollInterval: 10s

Remote Git Repository (HTTPS) Example Configuration

storage:
  driver: "git"
  git:
    protocol: https
    url: https://github.com/cerbos/policy-test.git
    branch: main
    subDir: policies
    checkoutDir: ${HOME}/tmp/work/policies
    updatePollInterval: 60s
    operationTimeout: 30s
    https:
      username: cerbos
      password: ${GITHUB_TOKEN}

Remote Git Repository (SSH) Example Configuration

storage:
  driver: "git"
  git:
    protocol: ssh
    url: github.com:cerbos/policy-test.git
    branch: main
    subDir: policies
    checkoutDir: ${HOME}/tmp/cerbos/work
    updatePollInterval: 60s
    ssh:
      user: git
      privateKeyFile: ${HOME}/.ssh/id_rsa

MySQL driver

The MySQL storage backend is one of the dynamic stores that supports adding or updating policies at runtime through the Admin API.

Example Configuration

storage:
  driver: "mysql"
  mysql:
    dsn: "${MYSQL_USER}:${MYSQL_PASSWORD}@tcp(localhost:3306)/cerbos"

Secure Connections Example Configuration

storage:
  driver: "mysql"
  mysql:
    dsn: "${MYSQL_USER}:${MYSQL_PASSWORD}@tcp(localhost:3306)/cerbos?tls=mysecuretls"
    tls:
      mysecuretls:
        caCert: /path/to/ca_certificate.crt
        cert: /path/to/certificate.crt
        key: /path/to/private.key

Postgres driver

The Postgres storage backend is one of the dynamic stores that supports adding or updating policies at runtime through the Admin API.

Example Configuration

storage:
  driver: "postgres"
  postgres:
    url: "postgres://${PG_USER}:${PG_PASSWORD}@localhost:5432/postgres?sslmode=disable&search_path=cerbos"

SQLite3 driver

The SQLite3 storage backend is one of the dynamic stores that supports adding or updating policies at runtime through the Admin API.

Example Configuration (In-memory Ephemeral Database)

storage:
  driver: "sqlite3"
  sqlite3:
    dsn: "file::memory:?cache=shared"

Example Configuration (On-disk Persistent Database)

storage:
  driver: "sqlite3"
  sqlite3:
    dsn: "file:/tmp/cerbos.sqlite?mode=rwc&cache=shared&_fk=true"