Service Policy Decision Point

The open source Cerbos server instances that you run in your own infrastructure are called service PDPs. Cerbos Hub is the management control plane for PDP instances that are running inside your environment. Rather than each PDP being responsible for detecting policy changes, parsing, compiling and loading them, they get pre-compiled policy bundles pushed to them from Cerbos Hub. This model ensures that all your data remains within your network perimeter and that authorization checks happen locally with low latency while reducing the overhead of policy updates and the time it takes for the whole fleet to get in sync. A PDP must be configured with the name of a label, workspace secret and client credentials in order to connect to Cerbos Hub.

Deploying a PDP

Connecting to Cerbos Hub is a matter of configuring the hub storage driver, which can be configured using the configuration file, environment variables or command line arguments.

The simplest method to get a connected PDP up and running is to run the container with configuration passed via environment variables:

docker run --rm --name cerbos \
 -p 3592:3592 -p 3593:3593 \
 -e CERBOS_HUB_BUNDLE="latest" \
 -e CERBOS_HUB_WORKSPACE_SECRET="..." \
 -e CERBOS_HUB_CLIENT_ID="..." \
 -e CERBOS_HUB_CLIENT_SECRET="..." \
 ghcr.io/cerbos/cerbos:latest server

The environment variables to set are:

CERBOS_HUB_BUNDLE: The label to load policies from
CERBOS_HUB_WORKSPACE_SECRET: Secret key to decrypt the bundles — generated during workspace creation
CERBOS_HUB_CLIENT_ID: Client ID
CERBOS_HUB_CLIENT_SECRET: Client secret
CERBOS_HUB_PDP_ID: Optional. The name shown for the PDP in the Cerbos Hub monitoring page. If not provided, a random value is used.

Alternatively, you can define these values in the Cerbos configuration file as follows:

server:
  httpListenAddr: ":3592" # The port the HTTP server will listen on
  grpcListenAddr: ":3593" # The port the gRPC server will listen on

hub:
  credentials:
    pdpID: "..." # Optional. Identifier for this Cerbos instance.
    clientID: "..." # ClientID
    clientSecret: "..." # ClientSecret
    workspaceSecret: "..." # WorkspaceSecret to decrypt the bundles -- generated during workspace creation

storage:
  driver: hub
  hub:
    remote:
      bundleLabel: latest # The label to load policies for

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

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

See Configuration for more information about configuring Cerbos.

Monitoring

The Decsion points page in Cerbos Hub provides a view of all the recently connected PDP instances of the workspace.

Connected instances