OPA Bundles and Policy Management

📖 Introduction

When I started with OPA, I was loading policies directly into Gatekeeper via ConstraintTemplates applied with kubectl. That works fine for a handful of policies on a single cluster. It breaks down quickly when you have many policies, multiple clusters, or need to ensure every cluster runs the same verified policy set.

OPA Bundles solve this. A bundle is a compressed archive of Rego policies and data that OPA fetches from a remote server and applies atomically. Policies are versioned, distributed, and updated without restarting OPA. This article covers the bundle format, serving bundles, and the workflow for managing policies at scale.

---

📦 What Is an OPA Bundle?

A bundle is a .tar.gz archive containing:

bundle/
├── .manifest          # bundle metadata (revision, roots)
├── policies/
│   ├── pod-security.rego
│   ├── image-registry.rego
│   └── resource-limits.rego
└── data/
    └── config.json    # data document loaded alongside policies

OPA fetches the bundle from a configured URL, validates it, atomically replaces the in-memory policy store, and begins evaluating against the new policies — without a restart.

---

🗂️ Bundle Manifest File

The .manifest file at the bundle root declares metadata:

{
  "revision": "v1.4.2",
  "roots": ["kubernetes/admission", "config"],
  "metadata": {
    "required_capabilities": {
      "features": ["rego_v1"]
    }
  }
}

Field	Purpose
revision	Identifies the bundle version. OPA reports this in status and logs.
roots	Data/policy paths this bundle owns. OPA won't accept conflicting bundles for the same root.
metadata	Optional — can include minimum OPA version requirements.

---

🏗️ Building a Bundle

Directory Structure

policies-repo/
├── .manifest
├── k8s/
│   ├── pod-security.rego
│   ├── required-labels.rego
│   └── image-registry.rego
└── data/
    └── approved-registries.json

approved-registries.json:

{
  "registries": [
    "registry.internal/",
    "gcr.io/myproject/"
  ]
}

k8s/image-registry.rego:

package k8s.image_registry

import rego.v1

violation contains msg if {
    container := input.review.object.spec.containers[_]
    not approved(container.image)
    msg := sprintf("Unapproved image registry: %s", [container.image])
}

approved(image) if {
    registry := data.approved_registries.registries[_]
    startswith(image, registry)
}

Notice data.approved_registries.registries — the policy reads from the data file loaded in the same bundle, rather than hardcoding registry values in the policy itself. Policy logic and configuration are separated.

Build the Bundle

# Using the OPA CLI
opa build -b ./policies-repo -o bundle.tar.gz

# With revision tag
opa build -b ./policies-repo -o bundle.tar.gz \
  --revision $(git rev-parse --short HEAD)

Inspect the built bundle:

opa inspect bundle.tar.gz

MANIFEST:
+-----------+-----------------------------------+
| Field     | Value                             |
+-----------+-----------------------------------+
| Revision  | a3f8c21                           |
| Roots     | k8s, data                         |
+-----------+-----------------------------------+
NAMESPACES:
+--------------------+------------------------------------+
| Namespace          | File                               |
+--------------------+------------------------------------+
| data.approved_...  | data/approved-registries.json      |
| k8s.image_registry | k8s/image-registry.rego            |
+--------------------+------------------------------------+

---

🖥️ Bundle Server Options

OPA can pull bundles from any HTTP server that serves files. Common options in practice:

Option 1: Nginx (Simplest)

server {
    listen 8080;
    root /var/bundles;
    
    location /bundles/ {
        add_header Content-Type application/gzip;
        autoindex on;
    }
}

# Place bundle in the served directory
cp bundle.tar.gz /var/bundles/prod/bundle.tar.gz

Option 2: Object Storage (S3 / GCS)

OPA has native support for S3-compatible storage:

services:
  - name: s3-bundle-server
    url: https://s3.amazonaws.com/my-opa-bundles
    credentials:
      s3_signing:
        environment_credentials: {}

bundles:
  main:
    service: s3-bundle-server
    resource: /prod/bundle.tar.gz
    polling:
      min_delay_seconds: 30
      max_delay_seconds: 60

Option 3: OCI Registry

Since OPA v0.44, bundles can be stored in OCI-compliant container registries:

# Push bundle to an OCI registry
opa push registry.internal/policies/k8s-admission:v1.4.2 bundle.tar.gz

bundles:
  main:
    service: oci-registry
    resource: registry.internal/policies/k8s-admission:v1.4.2

This integrates naturally with existing registry infrastructure and promotion workflows.

---

⚙️ Configuring OPA to Use Bundles

In a standalone OPA server, the config file:

# opa-config.yaml
services:
  - name: bundle-server
    url: https://bundles.internal

bundles:
  kubernetes-policies:
    service: bundle-server
    resource: /bundles/k8s-admission.tar.gz
    polling:
      min_delay_seconds: 10
      max_delay_seconds: 60

decision_logs:
  service: logging-backend
  reporting:
    min_delay_seconds: 5
    max_delay_seconds: 10

opa run --server --config-file=opa-config.yaml

For Gatekeeper

Gatekeeper uses a slightly different bundle mechanism via the externalData feature and the native ConstraintTemplate mechanism. For raw OPA deployments (non-Gatekeeper), the config above applies directly.

---

🔄 Bundle Update Workflow

With bundles, the policy deployment workflow becomes:

Policy updates go through the same review and CI process as application code. No kubectl apply needed per cluster. Every OPA instance pulls the authoritative bundle from the registry.

---

🏷️ Bundle Versioning Strategy

A practical versioning approach:

/bundles/
├── latest/
│   └── bundle.tar.gz          # always points to latest
├── v1.4.0/
│   └── bundle.tar.gz          # pinned version
├── v1.4.1/
│   └── bundle.tar.gz
└── v1.4.2/
    └── bundle.tar.gz

• Production clusters pin to a specific version

• Staging can track latest

• Rollback is just pointing the cluster config back to a previous version

---

📊 Monitoring Bundle Status

OPA exposes bundle status via its status API:

curl http://localhost:8181/v1/status | jq .

{
  "bundles": {
    "kubernetes-policies": {
      "active_revision": "v1.4.2",
      "last_successful_download": "2026-03-02T10:15:30Z",
      "last_successful_activation": "2026-03-02T10:15:30Z",
      "code": "bundle_request_in_progress"
    }
  }
}

Alert if:

• last_successful_download is stale (bundle server unreachable)

• active_revision differs from expected version (bundle not updating)

• Status shows bundle_load_or_save_error (policy compilation error in new bundle)

---

🧭 What's Next

Policies need tests just as much as application code. The next article covers the OPA test framework — unit tests in Rego, table-driven tests, and how Conftest extends this to CI/CD pipelines.

Next: Article 07 — Testing OPA Policies

---

📎 References

• OPA Bundle Documentation

• OPA Build CLI Reference

• OPA Status API

• Gatekeeper External Data