Reliability

Cerbos Hub is designed for high availability. All PDPs continue to operate independently even when Cerbos Hub experiences disruptions.

Network requirements

PDPs reach Cerbos Hub over outbound HTTPS on port 443. Allow these hosts through any egress proxy or firewall:

Host Port Purpose

api.cerbos.cloud

443

Bundle update stream and audit log ingest. Uses the Connect protocol over HTTP/2; the update stream is a long-lived HTTP/2 stream.

cdn.cerbos.cloud

443

All bundle content downloads: the bootstrap bundle at startup, and every bundle delivered by a subsequent policy update. Plain HTTPS.

All connections to Cerbos Hub require TLS 1.3; a proxy that downgrades below TLS 1.3 is refused. The PDP honors the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables.

Push-based updates

When a PDP connects to Cerbos Hub, it establishes a two-way communication channel used to receive the initial policy bundle and subsequent update notifications. Because there is no polling, all PDPs converge on the same policy version within seconds of a change.

Disconnection handling

If Cerbos Hub becomes temporarily unavailable:

Running PDPs

Continue serving requests using the last downloaded bundle while attempting to reconnect in the background. Authorization decisions are unaffected.
New PDPs

Can start with the last successfully built bundle, served from a separate high-availability fallback service.

Local bundle caching

For additional resilience, configure a cache directory to persist bundles to disk:

storage:
  driver: hub
  hub:
    remote:
      deploymentID: "..."
      cacheDir: /var/cerbos/hub # Directory to cache downloaded bundles

Mount a persistent volume at this path when running in containers or Kubernetes. Caching avoids re-downloading an unchanged bundle on restart. It does not enable an offline start: a PDP still contacts Cerbos Hub at startup to fetch its bundle, and fails to start if Hub cannot be reached.

Fallback to git

As a last resort, switch the PDP to read policies directly from your Git repository:

storage:
  driver: git
  git:
    protocol: https
    url: https://github.com/your-org/policies.git
    branch: main
    checkoutDir: /tmp/cerbos/policies
    updatePollInterval: 60s

This bypasses Cerbos Hub entirely, though you lose pre-compilation, testing, and centralized management.

Monitoring connectivity

Monitor PDP connectivity using the cerbos_dev_hub_connected Prometheus metric:

1

PDP is connected to Cerbos Hub
0

PDP is disconnected (using cached bundle)

Additional metrics for bundle operations:

cerbos_dev_store_bundle_updates_count

Number of bundle updates received from Cerbos Hub
cerbos_dev_store_bundle_op_latency

Time to perform bundle operations
cerbos_dev_store_bundle_fetch_errors_count

Count of errors during bundle downloads

See Observability for the full list of available metrics.