Managing OPA

OPA is a general-purpose policy engine that let’s you offload decisions from your service. To do so, OPA needs to have access to policies and data that it can use to make decisions.

Prior to v0.8, OPA only exposed low-level HTTP APIs that let you push policy and data into the engine. With v0.8, we’re excited to provide new management features in OPA which make it easier to distribute policies (and data) as well as monitor the health of your agents.

Bundle API

To simplify distribution of policy and data, you can now configure OPA to download “bundles” from remote HTTP endpoints. Bundles are simply gzipped tarballs containing Rego and JSON files. When you configure the Bundle feature, OPA will periodically call out to the remote HTTP and GET the named bundle:

GET /bundles/example/authz HTTP/1.1

Services implementing the Bundle API should reply with a gzipped tarball that contains the policy and data to load into OPA.

If your service includes an HTTP ETag header (and OPA is able to successfully activate the bundle), the ETag will be included in the If-None-Match header of subsequent GET requests. This allows services to avoid re-sending the same bundle over and over and simply respond with HTTP 301 Not Modified.

For more information check out the Bundles section in the docs.

Status API

Once you deploy OPA and distribute policies and data to it, the next question is how to tell if the agents are healthy. There are different ways to measure health (and OPA already supports performance metrics reporting with Prometheus), but two important question are:

• Which version of policy and data is OPA currently running with?
• What (if any) errors did OPA encounter while trying to load the policy and data?

In v0.8, you can configure OPA to periodically call out to a remote HTTP endpoint to report its status. The status updates contain useful information that describes the currently active policy bundle, reasons why the policy bundle failed to download or activate, and so on.

POST /status HTTP/1.1
Content-Type: application/json
{
  “labels”: {
    “app”: “my-example-app”,
    “id”: “1780d507-aea2–45cc-ae50-fa153c8e4a5a”
  },
  “bundle”: {
    “name”: “http/example/authz”,
    “active_revision”: “660daf152602bd95ea2d2139d215678b0ed[…]”,
    “last_successful_download”: “2018–04–17T12:34:40.258Z”,
    “last_successful_activation”: “2018–04–17T12:34:42.196Z”
  }
}

The update payload also includes a set of labels that allow the service to uniquely identify the agent.

For more information see the Status section in the docs.

Decision Log API

Finally, in addition to reporting status information, it’s often useful (or required) to have a record of all policy decisions that OPA returned to your service. Auditing and debugging are are two common tasks that require these kind of detailed information.

In v0.8, you can configure OPA to buffer and periodically upload batches of policy decisions to a remote HTTP endpoint. The batches are simply collections of policy decisions made by the agent. Each event in the batch contains all of the information require to analyze the decision:

• The name of the policy decision requested by your service.
• The input provided in the query by your service.
• The result returned by OPA to your service.

The events also include important metadata about the decision such as the bundle revision, the labels that uniquely identify the agent, and more.

For more information see the Decision Logs section in the docs.

Wrap Up

We are excited about these features because they not only simplify out-of-the-box management of OPA in large-scale systems but they also enable sophisticated tooling in the management layer.

If you find these features useful or you have ideas for other management-related features in OPA we would love to hear from you. Feel free to reach out on Slack. Thanks for reading!