OPA bundles — package policy and data for distributed OPA servers

Contents

  1. 1. Bundle layout
  2. 2. OPA server APIs
  3. 3. Bundle management APIs
  4. 4. How you embed OPA
    1. 4.1. OPA server
    2. 4.2. Go library
  5. 5. Metrics
  6. 6. Try it locally

A bundle is how OPA ships policy and data as one artifact. The engine was built for sidecars and daemons in cloud-native setups, so distribution, updates, and observability show up early — not as an afterthought.

Bundles cover:

  • Central config for policy + data
  • Hot(ish) policy refresh without redeploying every consumer
  • Health, metrics, and decision logs from many OPA instances

With Rego on top, that’s what makes OPA feel like a general policy layer instead of a one-off authz library.

Below: bundle layout, server APIs, remote bundle config, embedding options, and metrics. There’s a docker-compose demo in the koans repo—run it locally once you’ve skimmed the sections.

Bundle layout

Under a bundle directory, only data.json / data.yaml files become JSON document roots; parent directories become the data prefix.

Example (bundle/example):

1
2
3
4
5
6
7
8
9
10
cd bundle/example
tree -a
.
├── .manifest
├── bindings
│ └── data.json
├── main.rego
├── rbac.rego
└── roles
└── data.json

roles/data.json loads at data.roles.

Optional .manifest:

1
2
3
4
5
cat .manifest
{
"revision" : "9f160bcd446bf50b1b17b570c322198a68d8e106",
"roots": ["roles", "bindings","rbac","system"]
}

revision is the bundle version. roots lists allowed path prefixes — also what the bundle API may overwrite when you push updates.

Ship as a tarball:

1
2
3
cd bundle/example
tar -czf bundle.tar.gz .
opa run -b bundle.tar.gz

REPL input for bundles: use repl/input/data.json instead of repl.input:quick-start/input.json. See bundle file format.

OPA server APIs

Before bundle-specific endpoints, the REST API surface:

API Purpose
Data Query rules and virtual documents
Policy Read compiled policy
Query Ad-hoc query execution
Compile Partial evaluation
Health Liveness
Metrics Prometheus text

Spin up server mode on the quick-start tree:

1
opa run --server quick-start

Paths are under /v1/; data queries under /v1/data/.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
cat <<EOF > v1-data-input.json
{
"input": $(cat quick-start/input.json)
}
EOF
curl -s http://0.0.0.0:8181/v1/data/example_rbac?pretty=true -d @v1-data-input.json

{
"result": {
"allow": true,
"role_has_permission": [
"widget-reader"
],
"user_has_role": [
"widget-reader"
]
}
}

Default decision path is data.system.main — then the POST body is input, not wrapped. Override: opa run --server --set=default_decision=example_rbac/allow quick-start and curl -s http://0.0.0.0:8181/ -d @quick-start/input.json

Data API also accepts explain, metrics, provenance, etc. — see docs when debugging.

Bundle management APIs

Four channels aimed at fleets of OPAs:

  • Bundles — poll and pull tarball updates
  • Decision logs — upload gzipped log batches (size-partitioned, traceable by log id)
  • Status — periodic heartbeat with metrics snapshot
  • Discovery — central OPA config; nodes sync and then pull the right bundles

management api

Annotated config sketch (details in official docs; the demo wires this for real):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# opa/config-bundle.yaml
services:
- name: example_bundle
url: http://demo-server:8888/

labels:
app: myapp

bundles:
authz:
service: example_bundle
resource: bundle/rbac.tar.gz
# → http://demo-server:8888/bundle/rbac.tar.gz
polling:
min_delay_seconds: 300
max_delay_seconds: 600

decision_logs:
service: example_bundle
partition_name: bundle
# → http://demo-server:8888/logs/bundle (gzip payloads)
reporting:
min_delay_seconds: 30
max_delay_seconds: 60

status:
service: example_bundle
partition_name: bundle
# → http://demo-server:8888/status/bundle

default_decision: rbac/allow

How you embed OPA

OPA server

1
opa run -s -a 0.0.0.0:8181 -c opa/config-bundle.yaml

On start it fetches rbac.tar.gz, serves decisions, and pushes logs/status on the reporting intervals.

Go library

github.com/open-policy-agent/opa/rego:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
var err error
query, err := rego.New(
rego.LoadBundle("./rbac.tar.gz"),
rego.Query("x = data.rbac.allow"),
).PrepareForEval(context.Background())

results, err := query.Eval(context.Background(), rego.EvalInput(input))
if err != nil {
fmt.Fatalln("Opa eval error:", err)
return
} else if len(results) == 0 {
fmt.Fatalln("Opa eval error: no result")
return
}

fmt.Println("Opa result:", results[0].Expressions[0].Value)

Deployment patterns (official diagrams):

host-local

distributed-enforcement

Go sample: example-api-authz-go

Metrics

Server exposes Prometheus metrics — scrape and graph:

prometheus

grafana

Try it locally

Docker Compose demo in the koans repo:

  • opa-bundle
  • opa-discovery
  • demo-server (Go lib)
  • slim vs advanced monitoring stacks

NewbMiao/opa-koans/bundle — README has step-by-step; open issues if something drifts.

That closes the baseline tutorial arc. Later posts can stitch official examples into production-shaped stories.

Bundle verify flow from the repo:

scripts/bundleVerify.sh

More in the OPA series.

Questions? Leave a comment below or email: newbvirgil@gmail.com