Getting started

Prerequisites

  • A set of Cerbos policies. An example set of policies are avaliable at https://github.com/cerbos/example-cerbos-policy-repository.

  • Cerbos version 0.45.1 or higher.

  • Outbound internet access from your Cerbos instances so that they can connect to Cerbos Hub to fetch bundle updates and, if enabled, upload audit logs.

Create a policy store

Cerbos Hub uses policy stores to manage your policies. A policy store is a collection of policies and tests that can be built into a deployment and distributed to Cerbos PDPs.

For the guick start, you can create a policy store using the browser and upload a ZIP file containing policies (example) or fork the GitHub example repository and connect it to Cerbos Hub.

Upload policies via browser

  1. Sign in to Cerbos Hub at https://hub.cerbos.cloud and follow the on-boarding wizard to create an Organization and its first Workspace.

  2. Inside the Workspace, select Policy stores then New store.

  3. Give the store a clear name, for example orders-service, choose Browser upload as the source, and click Create.

  4. In the store detail page, click Upload files and select a ZIP file containing your policies. The ZIP file should contain the policies in the root directory, not in a subdirectory.

  5. Cerbos Hub immediately ingests the ZIP file, compiles the policies, and shows the first successful build.

GitHub repository

  1. Sign in to Cerbos Hub at https://hub.cerbos.cloud and follow the on-boarding wizard to create an Organization and its first Workspace.

  2. Inside the Workspace, select Policy stores then New store.

  3. Give the store a clear name, for example orders-service, choose GitHub repository as the source and connect to your GitHub account.

  4. Pick the branch you want Hub to track, usually main, and save. Cerbos Hub immediately ingests the repository, compiles the policies, and shows the first successful build.

You can create additional stores for other branches, teams or projects.

Create a Deployment

Deployments package policies from one or more policy stores into versioned bundles that are automatically distributed to connected Cerbos PDPs.

  1. Open Deployments then click New deployment.

  2. Select the store you just created.

  3. Click Create. Hub starts the initial build. When it finishes, note the deployment ID shown on the detail page. You will need this ID to configure the PDP.

Generate client credentials

Navigate to Settings → Client credentials and click Generate a client credential, giving it a name and select Read & Write so that policies can be pulled down and Audit Logs pushed back. Copy both the Client ID and Client secret. The secret is shown only once.

Configure and run a Cerbos PDP

You can pass the Hub connection settings as environment variables or in a YAML configuration file. The example below uses environment variables for a quick start:

docker run --rm --name cerbos
  -p 3592:3592 -p 3593:3593
  -e CERBOS_HUB_DEPLOYMENT_ID="..." \ # Deployment ID from Hub
  -e CERBOS_HUB_CLIENT_ID="..." \ # From Deployment ▸ Client credentials
  -e CERBOS_HUB_CLIENT_SECRET="..." \ # From Deployment ▸ Client credentials
  ghcr.io/cerbos/cerbos:latest server
shell

Optional variable:

CERBOS_HUB_PDP_ID

The friendly name that will appear on the Cerbos Hub monitoring page. If omitted a random identifier is generated.

YAML alternative

server:
  httpListenAddr: ":3592"
  grpcListenAddr: ":3593"

hub:
  credentials:
    pdpID: "orders-pdp-01" # Optional
    clientID: "..."
    clientSecret: "..."

storage:
  driver: hub
  hub:
    remote:
      deploymentID: "..." # Deployment ID from Hub
yaml

Assuming you saved the file as .cerbos.yaml in the current directory, start Cerbos with:

docker run --rm --name cerbos
  -v $(pwd):/conf
  -p 3592:3592 -p 3593:3593
  ghcr.io/cerbos/cerbos:latest server --config=/conf/.cerbos.yaml
shell

See Configuration for advanced configuration options.

Enable audit log collection (optional)

Add the Hub audit backend to stream decision logs to Cerbos Hub:

audit:
  backend: hub
  hub:
    storagePath: "/var/cerbos/audit-buffer" # Local buffer used when the network is unavailable
yaml

Refer to Audit log collection for details on filtering sensitive fields and other advanced options.

With a policy store connected, a deployment created, and at least one PDP running, you are ready to iterate on your policies. Push a change to the repository, watch Cerbos Hub build a new deployment version, and see the PDP update itself automatically within seconds.