# Engine block

## Default policy version

[Cerbos policies](https://docs.cerbos.dev/cerbos/latest/policies/) have a `version` field to support use cases such as having different policies for different environments (production, staging etc.) or for gradual rollout of a new version of an application. By default, when a request does not explicitly specify the policy version, the Cerbos engine attempts to find a matching policy that has its version set to `default`. You can change this fallback value by setting the `defaultPolicyVersion`. For example, if you have a Cerbos deployment for your staging environment, you may want to set `defaultPolicyVersion: staging` to ensure that the default policies in effect are the ones versioned as `staging`.

```yaml
engine:
  defaultPolicyVersion: "default"
```

## Default scope

[Cerbos policies](https://docs.cerbos.dev/cerbos/latest/policies/) have a `scope` field to support a way to model hierarchical relationships that regularly occur in many situations. By default, when a request does not explicitly specify the scope, the Cerbos engine attempts to find a matching policy that has its scope set to `""`. You can change this fallback value by setting the `defaultScope`. For example, you may set the default scope to `acme` with `defaultScope: acme` which will take effect when the request does not explicitly specify `scope` field.

```yaml
engine:
  defaultScope: "acme"
```

## Globals

Global variables are a way to pass environment-specific information to [policy conditions](https://docs.cerbos.dev/cerbos/latest/policies/conditions). For example, you might want to grant additional permissions to a role in your staging environment, without creating separate policy versions for different environments.

```yaml
engine:
  globals:
    environment: "staging"
```

Values set in `globals` can then be referenced in policy conditions:

```yaml
rules:
  - actions:
      - view
    effect: EFFECT_ALLOW
    roles:
      - developer
    condition:
      match:
        expr: globals.environment != "production"
```

As with other configuration settings, environment variables can be used to set global values.

```yaml
engine:
  globals:
    environment: ${CERBOS_ENVIRONMENT:development}
```

## Lenient scope search

When working with [scopes](https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies), the default behaviour of the Cerbos engine is to expect that a policy file exists for the requested scope. For example, if the API request defines `a.b.c` as the `scope`, a policy file _must exist_ in the policy repository with the `a.b.c` scope. This behaviour can be overridden by setting `lenientScopeSearch` configuration to `true`. When lenient scope search is enabled, if a policy with scope `a.b.c` does not exist in the store, Cerbos will attempt to find scopes `a.b`, `a` and `""` in that order.

|     |     |
| --- | --- |
|  | This setting only affects how Cerbos treats missing leaf scopes when searching for policies. The policies stored in your policy store _must_ have unbroken scope chains (for example, if you have a scoped policy `a.b.c` in the store, the policy files for scopes `a.b`, `a` and `""` must also exist). |

```yaml
engine:
  lenientScopeSearch: true
```