Configuration Reference Edit

This page defines the format of OPA configuration files. Fields marked as required must be specified if the parent is defined. For example, when the configuration contains a status key, the status.service field must be defined.

The configuration file path is specified with the -c or --config-file command line argument:

opa run -s -c config.yaml

The file can be either JSON or YAML format.

Example

services:
  acmecorp:
    url: https://example.com/control-plane-api/v1
    credentials:
      bearer:
        token: "bGFza2RqZmxha3NkamZsa2Fqc2Rsa2ZqYWtsc2RqZmtramRmYWxkc2tm"

labels:
  app: myapp
  region: west
  environment: production

bundle:
  name: http/example/authz
  service: acmecorp
  prefix: bundles
  polling:
    min_delay_seconds: 60
    max_delay_seconds: 120

decision_logs:
  service: acmecorp
  reporting:
    min_delay_seconds: 300
    max_delay_seconds: 600

status:
  service: acmecorp

default_decision: /http/example/authz/allow

Environment Variable Substitution

Only supported with the OPA runtime (opa run).

Environment variables referenced with the ${...} notation within the configuration will be replaced with the value of the environment variable.

Example using BASE_URL and BEARER_TOKEN environment variables:

services:
  acmecorp:
    url: ${BASE_URL}
    credentials:
      bearer:
        token: "${BEARER_TOKEN}"

discovery:
  name: /example/discovery
  prefix: configuration

The environment variables BASE_URL and BEARER_TOKEN will be substituted in when the config file is loaded by the OPA runtime.

If the variable is undefined then an empty string ("") is substituted. It will not raise an error.

CLI Runtime Overrides

Only supported with the OPA runtime (opa run).

Using opa run there are CLI options to explicitly set config values. These will override any values set in the config file.

There are two options to use: --set and --set-file

Both options take in a key=value format where the key is a selector for the yaml config structure, for example: decision_logs.reporting.min_delay_seconds=300 is equivalent to JSON {"decision_logs: {"reporting": {"min_delay_seconds: 300}}}. Multiple values can be specified with comma separators (key1=value,key2=value2,..). Or with additional --set parameters.

Example using several different options:

opa run \
  --set "default_decision=/http/example/authz/allow" \
  --set "services.acmecorp.url=https://test-env/control-plane-api/v1" \
  --set "services.acmecorp.credentials.bearer.token=\${TOKEN}"
  --set "labels.app=myapp,labels.region=west"

This is equivalent to a YAML config file that looks like:

services:
  acmecorp:
    url: https://test-env/control-plane-api/v1
    credentials:
      bearer:
        token: ${TOKEN}

labels:
  app: myapp
  region: west

default_decision: /http/example/authz/allow

The --set-file option is expecting a file path for the value. This allows keeping secrets in files and loading them into the config at run time. For Example:

With a file /var/run/secrets/bearer_token.txt that has contents:

bGFza2RqZmxha3NkamZsa2Fqc2Rsa2ZqYWtsc2RqZmtramRmYWxkc2tm

Then using the --set-file flag for OPA

opa run --set-file "services.acmecorp.credentials.bearer.token=/var/run/secrets/bearer_token.txt"

It will read the contents of the file and set the config value with the token.

Override Limitations

If using arrays/lists in the configuration the --set and --set-file overrides will not be able to patch sub-objects of the list. They will overwrite the entire index with the new object.

For example, a config.yaml file with contents:

services:
  - name: acmecorp
    url: https://test-env/control-plane-api/v1
    credentials:
      bearer:
        token: ""

Used with overrides:

opa run \
  --config-file config.yaml
  --set-file "services[0].credentials.bearer.token=/var/run/secrets/bearer_token.txt"

Will result in configuration like:

services:
  - credentials:
      bearer:
        token: bGFza2RqZmxha3NkamZsa2Fqc2Rsa2ZqYWtsc2RqZmtramRmYWxkc2tm

Because the entire 0 index was overwritten.

It is highly recommended to use objects/maps instead of lists for configuration for this reason.

Services

Services represent endpoints that implement one or more control plane APIs such as the Bundle or Status APIs. OPA configuration files may contain multiple services.

FieldTypeRequiredDescription
services[_].namestringYesUnique name for the service. Referred to by plugins.
services[_].urlstringYesBase URL to contact the service with.
services[_].headersobjectNoHTTP headers to include in requests to the service.
services[_].allow_insecure_tlsboolNoAllow insecure TLS.
services[_].credentials.bearer.tokenstringNoEnables token-based authentication and supplies the bearer token to authenticate with.
services[_].credentials.bearer.schemestringNoBearer token scheme to specify.
services[_].credentials.client_tls.certstringNoThe path to the client certificate to authenticate with.
services[_].credentials.client_tls.private_keystringNoThe path to the private key of the client certificate.
services[_].credentials.client_tls.private_key_passphrasestringNoThe passphrase to use for the private key.

Services can be defined as an array or object. When defined as an object, the object keys override the services[_].name fields. For example:

services:
  s1:
    url: https://s1/example/
  s2:
    url: https://s2/

Is equivalent to

services:
  - name: s1
    url: https://s1/example/
  - name: s2
    url: https://s2/

Miscellaenous

FieldTypeRequiredDescription
labelsobjectYesSet of key-value pairs that uniquely identify the OPA instance. Labels are included when OPA uploads decision logs and status information.
default_decisionstringNo (default: /system/main)Set path of default policy decision used to serve queries against OPA’s base URL.
default_authorization_decisionstringNo (default: /system/authz/allow)Set path of default authorization decision for OPA’s API.
pluginsobjectNo (default: {})Location for custom plugin configuration. See Plugins for details.

Bundles

FieldTypeRequiredDescription
bundle.namestringYesName of the bundle to download.
bundle.prefixstringNo (default: bundles)Path prefix to use to download bundle from remote server.
bundle.servicestringYesName of service to use to contact remote server.
bundle.polling.min_delay_secondsint64No (default: 60)Minimum amount of time to wait between bundle downloads.
bundle.polling.max_delay_secondsint64No (default: 120)Maximum amount of time to wait between bundle downloads.

Status

FieldTypeRequiredDescription
status.servicestringYesName of service to use to contact remote server.
status.partition_namestringNoPath segment to include in status updates.

Decision Logs

FieldTypeRequiredDescription
decision_logs.servicestringYesName of the service to use to contact remote server.
decision_logs.partition_namestringNoPath segment to include in status updates.
decision_logs.reporting.buffer_size_limit_bytesint64NoDecision log buffer size limit in bytes. OPA will drop old events from the log if this limit is exceeded. By default, no limit is set.
decision_logs.reporting.upload_size_limit_bytesint64No (default: 32768)Decision log upload size limit in bytes. OPA will chunk uploads to cap message body to this limit.
decision_logs.reporting.min_delay_secondsint64No (default: 300)Minimum amount of time to wait between uploads.
decision_logs.reporting.max_delay_secondsint64No (default: 600)Maximum amount of time to wait between uploads.
decision_logs.pluginstringNoUse the named plugin for decision logging. If this field exists, the other configuration fields are not required.

Discovery

FieldTypeRequiredDescription
discovery.namestringYesName of the discovery configuration to download.
discovery.prefixstringNo (default: bundles)Path prefix to use to download configuration from remote server.
discovery.polling.min_delay_secondsint64No (default: 60)Minimum amount of time to wait between configuration downloads.
discovery.polling.max_delay_secondsint64No (default: 120)Maximum amount of time to wait between configuration downloads.