Health probes

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

Endpoints

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.

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.

Health check command

The healthcheck command checks whether a Synapse instance is serving the Cerbos API. It prints the reported status and exits with a non-zero code when the instance is not serving. The Synapse container image uses this command as its Docker HEALTHCHECK.

$ synapse healthcheck --conf.path=/config/.synapse.yaml
SERVING

The command reads the server address and TLS settings from the Synapse configuration:

  • With no configuration file and no overrides, it checks 127.0.0.1:3594 without TLS.

  • With a configuration file given by --conf.path or the SYNAPSE_CONFIG environment variable, it uses server.listenAddress and server.tls from the file.

  • --conf.set overrides individual values, with or without a configuration file.

When server.tls is configured, the server certificate is verified against server.tls.caCert, or against server.tls.cert when no CA certificate is set.

$ synapse healthcheck \
    --conf.path=/config/.synapse.yaml \
    --conf.set=server.listenAddress=synapse.internal:3594 \
    --conf.set=server.tls.caCert=/certs/ca.crt
Flag Environment variable Description

--insecure

SYNAPSE_HC_INSECURE

Skip verification of the server certificate.

--timeout

SYNAPSE_HC_TIMEOUT

Time to wait for a response. Defaults to 2s.

When the configuration makes Synapse listen on a tailnet, the command exits successfully without performing a check.

In the container image, SYNAPSE_CONFIG defaults to the built-in default configuration. Pass the location of a mounted configuration file through SYNAPSE_CONFIG rather than --conf.path, so that the server and the health check read the same file. See Running Synapse in a container.

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.