Storage block

This documentation is for a previous version of Cerbos. Choose 0.53.0 from the version picker at the top right or navigate to https://docs.cerbos.dev for the latest version.

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

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.

Static fileset with no change detection

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

Dynamic fileset with change detection

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

Archive files

Alternatively, you can opt to archive and/or compress your policies directory into a Zip (.zip), Tar (.tar) or Gzip file (.tgz or .tar.gz). The archive is assumed to be laid out like a standard policy directory. It must contain no non-policy YAML files.

You specify the file in your config like so:

Archived fileset using a Zip file

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

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=my.minio.local:8080&disableSSL=true&s3ForcePathStyle=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 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.

Using Postgres as a storage backend for Cerbos

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

Database object definitions

You can customize the script below to suit your environment. Make sure to specify a strong password for the cerbos_user user.

CREATE SCHEMA IF NOT EXISTS cerbos;

SET search_path TO cerbos;

CREATE TABLE IF NOT EXISTS policy (
    id bigint NOT NULL PRIMARY KEY,
    kind VARCHAR(128) NOT NULL,
    name VARCHAR(1024) NOT NULL,
    version VARCHAR(128) NOT NULL,
    scope VARCHAR(512),
    description TEXT,
    disabled BOOLEAN default false,
    definition BYTEA
);

CREATE TABLE IF NOT EXISTS policy_dependency (
    policy_id BIGINT,
    dependency_id BIGINT,
    PRIMARY KEY (policy_id, dependency_id),
    FOREIGN KEY (policy_id) REFERENCES cerbos.policy(id) ON DELETE CASCADE
);

CREATE TABLE IF NOT EXISTS policy_ancestor (
    policy_id BIGINT,
    ancestor_id BIGINT,
    PRIMARY KEY (policy_id, ancestor_id),
    FOREIGN KEY (policy_id) REFERENCES cerbos.policy(id) ON DELETE CASCADE
);

CREATE TABLE IF NOT EXISTS policy_revision (
    revision_id SERIAL PRIMARY KEY,
    action VARCHAR(64),
    id BIGINT,
    kind VARCHAR(128),
    name VARCHAR(1024),
    version VARCHAR(128),
    scope VARCHAR(512),
    description TEXT,
    disabled BOOLEAN,
    definition BYTEA,
    update_timestamp TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS attr_schema_defs (
    id VARCHAR(255) PRIMARY KEY,
    definition JSON
);