Health probes

Synapse exposes health and metrics endpoints on the address configured by server.listenAddress (:3594 by default).

Endpoints

Path Method Description

Path	Method	Description
`/_cerbos/live`	`GET`	Returns `200 OK` while the process is running. This endpoint does not check the configured PDP.
`/_cerbos/ready`	`GET`	Returns `200 OK` when the configured PDP is ready to serve requests and `503 Service Unavailable` otherwise.
`/_cerbos/health`	`GET`	Compatibility alias for `/_cerbos/ready`. This path can be used by probes migrated from a standalone Cerbos PDP.
`/_cerbos/metrics`	`GET`	Prometheus metrics endpoint. See Observability.

/_cerbos/live

GET

Returns 200 OK while the process is running. This endpoint does not check the configured PDP.

/_cerbos/ready

GET

Returns 200 OK when the configured PDP is ready to serve requests and 503 Service Unavailable otherwise.

/_cerbos/health

GET

Compatibility alias for /_cerbos/ready. This path can be used by probes migrated from a standalone Cerbos PDP.

/_cerbos/metrics

GET

Prometheus metrics endpoint. See Observability.

These endpoints accept GET requests. A HEAD request returns 405 Method Not Allowed.

Readiness

The readiness check reports the health of the configured PDP. For pdp.inProcess, it remains unavailable until the policy store is initialized. This includes the initial bundle download for the hub storage driver and the initial bucket clone for the blob storage driver. For pdp.external, readiness follows the health of the external PDP.

After initialization, readiness does not track connectivity to the policy source. For example, if the connection to Cerbos Hub is interrupted, the PDP continues to serve requests using its current bundle and /_cerbos/ready continues to return 200. Use the cerbos_dev_hub_connected metric to monitor Hub connectivity.

If the in-process PDP cannot start, Synapse exits. If an external PDP is unavailable, Synapse continues running but remains unready. Check the container logs for startup and connectivity errors.

Kubernetes probes

Use separate liveness and readiness probes:

livenessProbe:
  httpGet:
    path: /_cerbos/live
    port: 3594
    scheme: HTTP (1)

readinessProbe:
  httpGet:
    path: /_cerbos/ready
    port: 3594
    scheme: HTTP (1)

1	Use `HTTPS` when TLS is configured for the Synapse server.

The Synapse Helm chart configures these endpoints by default. When migrating manifests from the standalone Cerbos PDP, /_cerbos/health remains available for compatibility, but separate liveness and readiness probes are recommended.