Cerbos v0.14.0

This release requires updating existing policy tests to match the new matrix test format. See upgrade documentation for more information.


This release includes many improvements that enhance policy authoring and testing along with updates that make deployment, management, and monitoring of Cerbos easier.

The policy testing framework is updated to support writing matrix tests and to treat invalid test files as failures. You can now define a set of principals, resources, and actions in a test case and the test runner automatically runs tests against all combinations of principal, resource, and action tuples. Only the tuples that are expected to produce an ALLOW response needs to be defined in the expectations list. Every other tuple is assumed to produce a DENY response and the tests fail if they don’t. This is one of the rare cases where a breaking change was necessary to make the developer experience better. Existing test suites must be updated to work with this version of Cerbos. See upgrade documentation for more information.

Deploying Cerbos to environments that utilise the Docker HEALTHCHECK directive (AWS Elastic Container Service, for example) is now easier using the built-in cerbos healthcheck command. The Cerbos container image ships with a default HEALTHCHECK configured using this command and it can be tuned using environment variables or command-line flags. See cerbos healthcheck documentation for details.

The cerbosctl management tool now supports adding or updating policies and schemas to a running Cerbos instance using the new put subcommand. The Admin API must be enabled on the Cerbos instance and it must be configured to use one of the database storage backends such as Postgres or MySQL in order for this command to work. For more information see cerbosctl put documentation.

You can write policy conditions that make use of the current time using the newly introduced now function. It’s designed to provide a stable timestamp value that returns the time that particular policy started executing. The semantics of the timeSince function has changed to use this stable definition of now as well.

The size of the in-memory caches that hold compiled policies and schemas have a significant impact on the performance of Cerbos PDPs. This release introduces two new configuration options to tune the sizes of these caches. If you are running Cerbos on Kubernetes or other orchestration system that imposes memory resource limits on containers, make sure to consider the cache sizes when configuring those limits. By default Cerbos holds 1024 compiled policies and 1024 schemas in its cache. The size and usage metrics of caches are available through the metrics endpoint (/_cerbos/metrics).


Bug Fixes

  • Configure GoReleaser to generate Homebrew formula in tap’s Formula subdirectory (#685)

  • Require at least one action in every rule (#690)


  • Add now function that returns the current timestamp (#670)

  • Add healthcheck command (#692)

  • BREAKING Add matrix tests (#701)

  • Introduce cerbosctl put (#676)


  • Add cache metrics (#706)

  • Add index entry count metric (#677)

  • Allow compile and schema cache sizes to be configured (#700)

  • Allow policies to be empty (#694)

  • Do not ignore invalid test suites (#686)

  • Include type of unexpected result in error message (#693)

  • Use camel case for custom functions (#672)


  • Add context to policy documentation (#699)

  • Fix YAML syntax in testing documentation (#678)


  • Add response and wantedResponse check for the load tests (#691)

  • Add support for load testing with the postgres store (#698)

  • Bump actions/checkout from 2 to 3 (#709)

  • Bump bufbuild/buf-setup-action from 1.0.0 to 1.1.0 (#708)

  • Bump github.com/bufbuild/buf from 1.0.0 to 1.1.0 in /tools (#717)

  • Bump github.com/envoyproxy/protoc-gen-validate from 0.6.2 to 0.6.7 in /tools (#716)

  • Bump github.com/envoyproxy/protoc-gen-validate from 0.6.3 to 0.6.7 (#713)

  • Bump github.com/fergusstrange/embedded-postgres from 1.14.0 to 1.15.0 (#711)

  • Bump github.com/goreleaser/goreleaser in /tools (#715)

  • Bump github.com/grpc-ecosystem/grpc-gateway/v2 from 2.7.3 to 2.8.0 (#720)

  • Bump github.com/grpc-ecosystem/grpc-gateway/v2 from 2.7.3 to 2.8.0 in /tools (#718)

  • Bump github.com/lestrrat-go/jwx from 1.2.18 to 1.2.19 (#680)

  • Bump github.com/lestrrat-go/jwx from 1.2.19 to 1.2.20 (#710)

  • Bump github.com/minio/minio-go/v7 from 7.0.22 to 7.0.23 (#682)

  • Bump go.uber.org/multierr from 1.7.0 to 1.8.0 (#712)

  • Bump golangci/golangci-lint-action from 2 to 3.1.0 (#679)

  • Bump modernc.org/sqlite from 1.14.6 to 1.14.7 (#681)

  • Bump modernc.org/sqlite from 1.14.7 to 1.14.8 (#714)

  • Bump version to 0.14.0

  • Don’t reuse the DB for client tests (#719)

  • Fix linter issues when running make lint, but not in CI (#673)

  • Modify policy generator to use templates (#683)

  • Rename Helm chart README to README.md (#671)

  • Replace cobra with kong in cerbosctl (#668)

  • Tweak load test script (#675)