Variables and constants

This documentation is for an as-yet unreleased version of Cerbos. Choose 0.39.0 from the version picker at the top right or navigate to https://docs.cerbos.dev for the latest version.

Variables

You can use variables to reduce duplication in policy condition expressions. Variables may either be defined locally within a policy, or in a standalone exportVariables policy file that can be imported by other policies.

Defining local variables

Local variables are only accessible from the policy they are defined. In particular, local variables defined for derived roles can’t be used in resource policies that import the derived roles.

---
apiVersion: api.cerbos.dev/v1
resourcePolicy:
  variables:
    local: (1)
      flagged_resource: request.resource.attr.flagged
      label: '"latest"' # assigning a string literal
      teams: '["red", "blue"]' # assigning an array literal
      lookup: '{"red": 9001, "blue": 0}' # assigning a map literal
  # ...

1	Map of variable name to expression.

Defining and importing exported variables

To reuse variables between policies, they can be exported from a separate file.

---
apiVersion: api.cerbos.dev/v1
description: Common variables used within the Apatr app
exportVariables:
  name: apatr_common_variables (1)
  definitions: (2)
    flagged_resource: request.resource.attr.flagged
    label: '"latest"' # assigning a string literal
    teams: '["red", "blue"]' # assigning an array literal
    lookup: '{"red": 9001, "blue": 0}' # assigning a map literal

1	Name to use when importing this set of variables.
2	Map of variable name to expression.

Other policies can then import the variables by name.

---
apiVersion: api.cerbos.dev/v1
resourcePolicy:
  variables:
    import: (1)
      - apatr_common_variables
  # ...

1	List of names of variable sets to import.

Using variables in policy conditions

Variables can be referenced via the variables (aliased to V) special variable in policy condition expressions.

---
condition:
  match:
    expr: variables.flagged_resource

Local and imported variable definitions are merged, and each variable is evaluated before any rule condition. If a variable is defined in more than one location, the policy will fail to compile.

Top-level variables field

In earlier versions of Cerbos, local variables were defined in a top-level variables field in the policy file. This field is deprecated in favour of the variables.local section within the policy body. For backwards compatibility, the deprecated top-level field is merged with the variables.local section in derived roles, resource, and principal policies.

Constants

Variables are expressions that are evaluated at runtime. That makes them slightly awkward to use with literal values, because you have to quote the value to make it a valid Common Expression Language (CEL) expression.

Constants are an alternative to defining variables with literal values, which allow the values to be written using standard YAML or JSON syntax.

Defining local constants

Local constants are only accessible from the policy they are defined. In particular, local constants defined for derived roles can’t be used in resource policies that import the derived roles.

---
apiVersion: api.cerbos.dev/v1
resourcePolicy:
  constants:
    local: (1)
      label: latest
      teams:
        - red
        - blue
      lookup:
        red: 9001
        blue: 0
  # ...

1	Map of constant name to value.

Defining and importing exported constants

To reuse constants between policies, they can be exported from a separate file.

---
apiVersion: api.cerbos.dev/v1
description: Common constants used within the Apatr app
exportConstants:
  name: apatr_common_constants (1)
  definitions: (2)
    label: latest
    teams:
      - red
      - blue
    lookup:
      red: 9001
      blue: 0

1	Name to use when importing this set of constants.
2	Map of constant name to value.

Other policies can then import the constants by name.

---
apiVersion: api.cerbos.dev/v1
resourcePolicy:
  constants:
    import: (1)
      - apatr_common_constants
  # ...

1	List of names of constant sets to import.

Using constants in policy conditions

Constants can be referenced via the constants (aliased to C) special variable in policy condition expressions.

---
condition:
  match:
    expr: constants.lookup[request.principal.attr.team] > 9000

Local and imported constant definitions are merged. If a constant is defined in more than one location, the policy will fail to compile.