Deploy Cerbos to Cloud platforms

Fly.io

You can deploy Cerbos on Fly.io as a Fly Launch app. The following fly.toml file shows how to deploy Cerbos with healthchecks and metrics:

app = '<APPLICATION_NAME>' (1)
primary_region = '<REGION>' (2)

[build]
  image = 'ghcr.io/cerbos/cerbos:0.34.0'

[[mounts]]
  source = 'policies'
  destination = '/policies'
  initial_size = '1GB'

[[services]]
  protocol = ''
  internal_port = 3592

[[services.ports]]
    port = 3592
    handlers = ['tls', 'http']

[[services.http_checks]]
    interval = '5s'
    timeout = '2s'
    grace_period = '5s'
    method = 'get'
    path = '/_cerbos/health'
    protocol = 'http'

[[services]]
  protocol = ''
  internal_port = 3593

[[services.ports]]
    port = 3593
    handlers = ['tls']

[services.ports.tls_options]
      alpn = ['h2']

[[vm]]
  memory = '1gb'
  cpu_kind = 'shared'
  cpus = 1

[metrics]
  port = 3592
  path = "/_cerbos/metrics"

The example above launches a Cerbos instance with the minimal configuration using an empty Fly volume mounted as the policy directory. For production use cases, consider using one of the following methods for policy storage.

• Cerbos git driver with a Git provider such as GitHub or GitLab

• Cerbos blob driver with Tigris

• Cerbos sqlite3 driver with a standalone SQLite database or LiteFS

• Cerbos postgres driver with Fly Postgres

• Cerbos Hub

Using Tigris as a policy repository

Cerbos blob driver can be used with any S3-compatible blob storage backend such as Tigris.

Create a storage bucket on Tigris. Refer to https://fly.io/docs/reference/tigris/#create-and-manage-a-tigris-storage-bucket for more information about creating storage buckets.

flyctl storage create

flyctl apps create <APPLICATION_NAME> (1)
flyctl secrets set --app=<APPLICATION_NAME> AWS_ACCESS_KEY_ID=tid_XXXXXX (2)
flyctl secrets set --app=<APPLICATION_NAME> AWS_SECRET_ACCESS_KEY=tsec_XXXXXX (3)

Create a fly.toml file.

app = '<APPLICATION_NAME>' (1)
primary_region = '<REGION>' (2)

[build]
  image = 'ghcr.io/cerbos/cerbos:0.34.0'

[experimental]
  cmd = [\
    'server',\
    '--set', 'storage.driver=blob',\
    '--set', 'storage.blob.bucket=s3://<BUCKET_NAME>?endpoint=fly.storage.tigris.dev&region=auto', (3)\
    '--set', 'storage.blob.downloadTimeout=30s',\
    '--set', 'storage.blob.prefix=policies',\
    '--set', 'storage.blob.updatePollInterval=15s',\
    '--set', 'storage.blob.workDir=/policies'\
  ]

[[mounts]]
  source = 'policies'
  destination = '/policies'
  initial_size = '1GB'

[[services]]
  protocol = ''
  internal_port = 3592
  auto_stop_machines = true

[[services.ports]]
    port = 3592
    handlers = ['tls', 'http']

[[services.http_checks]]
    interval = '5s'
    timeout = '2s'
    grace_period = '5s'
    method = 'get'
    path = '/_cerbos/health'
    protocol = 'http'

[[services]]
  protocol = ''
  internal_port = 3593
  auto_stop_machines = true

[[services.ports]]
    port = 3593
    handlers = ['tls']

[services.ports.tls_options]
      alpn = ['h2']

[[vm]]
  memory = '1gb'
  cpu_kind = 'shared'
  cpus = 1

[metrics]
  port = 3592
  path = "/_cerbos/metrics"

Deploy the app.

flyctl deploy

Using LiteFS as a policy repository

Fly.io’s distributed SQLite storage layer LiteFS can be used for policy storage using Cerbos' sqlite3 driver.

Start by creating an app on Fly.io.

flyctl apps create <APPLICATION_NAME>

Create a LiteFS configuration file named litefs.yml.

data:
  dir: "/var/lib/litefs"

exec:
  - cmd: "/cerbos server --set=storage.driver=sqlite3 --set=storage.sqlite3.dsn=file:/litefs/db --set=server.adminAPI.enabled=true --set=server.adminAPI.adminCredentials.username=$CERBOS_ADMIN_USER --set=server.adminAPI.adminCredentials.passwordHash=$CERBOS_ADMIN_PASSWORD_HASH"

exit-on-error: false

fuse:
  dir: "/litefs"

lease:
  advertise-url: "http://${FLY_ALLOC_ID}.vm.${FLY_APP_NAME}.internal:20202"
  candidate: ${FLY_REGION == PRIMARY_REGION}
  consul:
    url: "${FLY_CONSUL_URL}"
    key: "${FLY_APP_NAME}/primary"
  promote: true
  type: "consul"

Create a Dockerfile.

FROM flyio/litefs:0.5 AS litefs

FROM ghcr.io/cerbos/cerbos:0.34.0 AS cerbos

FROM alpine:3.16 AS base
RUN apk add fuse3 sqlite
ADD litefs.yml /etc/litefs.yml
COPY --from=cerbos /cerbos /cerbos
COPY --from=litefs /usr/local/bin/litefs /usr/local/bin/litefs

ENTRYPOINT ["litefs"]
CMD ["mount"]

Create a fly.toml file to launch Cerbos.

app = '<APPLICATION_NAME>' (1)
primary_region = '<REGION>' (2)

[build]
  dockerfile = "Dockerfile"

[mounts]
  source = "litefs"
  destination = "/var/lib/litefs" (3)

[[services]]
  protocol = ''
  internal_port = 3592

[[services.ports]]
    port = 3592
    handlers = ['tls', 'http']

[[services.http_checks]]
    interval = '5s'
    timeout = '2s'
    grace_period = '5s'
    method = 'get'
    path = '/_cerbos/health'
    protocol = 'http'

[[services]]
  protocol = ''
  internal_port = 3593

[[services.ports]]
    port = 3593
    handlers = ['tls']

[services.ports.tls_options]
      alpn = ['h2']

[[vm]]
  memory = '1gb'
  cpu_kind = 'shared'
  cpus = 1

[metrics]
  port = 3592
  path = "/_cerbos/metrics"

Create secrets to hold Cerbos Admin API credentials. Refer to password hash generation instructions to learn how to generate the password hash.

flyctl secrets set CERBOS_ADMIN_USER=<ADMIN_USER_NAME>
flyctl secrets set CERBOS_ADMIN_PASSWORD_HASH=<ADMIN_PASSWORD_HASH>

Attach to Consul to manage LiteFS leases.

flyctl consul attach

Finally, deploy Cerbos.

flyctl deploy

You can interact with the Cerbos Admin API using one of the Cerbos SDKs or the cerbosctl utility to manage the policies stored on LiteFS.

List policies with cerbosctl

cerbosctl \
  --server=<APPLICATION_NAME>.fly.dev:3593 \
  --username=<ADMIN_USER_NAME> \
  --password=<ADMIN_PASSWORD> \
  get rp

Put a policy or a directory consisting of multiple policies with cerbosctl

cerbosctl \
  --server=<APPLICATION_NAME>.fly.dev:3593 \
  --username=<ADMIN_USER_NAME> \
  --password=<ADMIN_PASSWORD> \
  put policies -R \
  policy_dir