OPA Architecture and Deployment Modes

📖 Introduction

Before I deployed OPA to a real cluster, I needed to understand how it actually works at runtime. The documentation makes the policy language clear, but the deployment model takes some thought. OPA can run as a server, a sidecar, an embedded library, or a CLI tool — and choosing the right mode shapes how you integrate it.

This article covers the internal architecture of OPA and the four ways to deploy it, so the Kubernetes-specific setup in the next article makes sense.

---

🏗️ OPA Internal Architecture

At its core, OPA is a evaluation engine:

1. Policies (Rego files) are compiled into a query plan

2. At query time, OPA loads input and data, then executes the plan

3. The result is returned as JSON

The Data Store

OPA maintains an in-memory document store for the data document. You populate it by:

• Loading JSON/YAML files at startup (opa run -d data.json)

• Pushing data via the REST API (PUT /v1/data/...)

• Loading a bundle (covered in Article 06)

Policy Compilation

When OPA loads a .rego file, it compiles it immediately. Compilation validates syntax, resolves imports, and optimizes the policy into an internal representation. This means policy errors are caught at load time, not evaluation time.

---

🔌 Deployment Modes

OPA can be deployed in four ways. Each suits different integration patterns.

Mode 1: CLI (Local Evaluation)

opa eval -i input.json -d policy.rego "data.example.deny"

Use this for:

• Local development and testing

• CI/CD pipeline policy gates

• One-shot policy checks in scripts

No server needed. OPA loads policies and input, evaluates, exits.

Mode 2: REPL (Interactive)

opa run
> data := {"registries": ["registry.internal"]}
> input := {"image": "nginx:latest"}
> startswith(input.image, data.registries[0])

Use this for:

• Exploring and debugging policies

• Learning Rego interactively

• Testing edge cases before writing unit tests

Mode 3: OPA Server (REST API)

opa run --server --addr=:8181 -d policies/ -d data.json

OPA starts an HTTP server. Any system can query it over REST:

curl -X POST http://localhost:8181/v1/data/example/deny \
  -H "Content-Type: application/json" \
  -d '{"input": {"spec": {"containers": [{"image": "docker.io/nginx"}]}}}'

This is how Kubernetes Gatekeeper and many sidecar deployments work under the hood.

Key API endpoints:

Endpoint	Method	Purpose
/v1/data/<path>	POST	Evaluate a query
/v1/policies/<id>	PUT	Upload a policy
/v1/data/<path>	PUT	Update data
/v1/query	POST	Ad-hoc query evaluation
/health	GET	Liveness check

Mode 4: Go Library (Embedded)

For Go applications, OPA can be embedded directly:

import "github.com/open-policy-agent/opa/v1/rego"

r := rego.New(
    rego.Query("data.myapp.authz.allow"),
    rego.Load([]string{"./policies/"}, nil),
)

query, err := r.PrepareForEval(ctx)
// cache `query`, call Eval() on each request

rs, err := query.Eval(ctx, rego.EvalInput(inputData))
if err != nil { ... }

allowed := rs[0].Bindings["allow"].(bool)

The compiled query is safe to cache and share across goroutines — OPA evaluates each call independently from the cached plan.

Use this when:

• You're writing a Go service that needs policy decisions inline

• Network latency to an OPA server is unacceptable

• You want zero external dependencies at runtime

---

🔄 Sidecar vs Centralized Deployment

When using OPA as a server (Mode 3), you have two topology choices:

Approach	Pros	Cons
Centralized	Single policy update point, easier monitoring	Single point of failure, network latency
Sidecar	Low latency, no external dependency	Policy sync complexity, more instances to manage

For Kubernetes admission control, OPA runs as a Deployment with replicas — not a true sidecar, but centralized within the cluster.

---

🔒 OPA Server Security Considerations

By default, OPA's REST API has no authentication. For any real deployment:

# Run with TLS and bearer token auth
opa run --server \
  --tls-cert-file=cert.pem \
  --tls-private-key-file=key.pem \
  --authentication=token \
  --authorization=basic \
  -d policies/

OPA also supports mTLS, OIDC token verification, and custom authentication plugins.

---

📡 How OPA Gets Policies and Data

Three patterns for keeping OPA's policies and data current:

1. Static Load at Startup

opa run --server -d ./policies/ -d ./data/

Policies are loaded once. Requires restart to update. Fine for development, limiting for production.

2. REST API Push

# Upload a policy at runtime
curl -X PUT http://localhost:8181/v1/policies/pod-security \
  -H "Content-Type: text/plain" \
  --data-binary @pod-security.rego

# Update data at runtime
curl -X PUT http://localhost:8181/v1/data/config/registries \
  -H "Content-Type: application/json" \
  -d '["registry.internal", "gcr.io/myproject"]'

Fine-grained control, but you manage the push mechanism.

3. Bundles (Recommended for Production)

OPA periodically pulls a bundle — a compressed archive of policies and data — from a bundle server. This is the standard production pattern.

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

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

Bundles are covered in depth in Article 06.

---

📊 OPA Decision Logging

In production, you want to know what decisions OPA is making. OPA supports decision logging — every evaluation can be sent to a remote endpoint:

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

Each log entry includes the input, the decision, the policy that matched, and timing information. This is critical for auditing and debugging policy behavior in production.

---

🧭 What's Next

Now that you understand how OPA runs, the next article puts it in Kubernetes using OPA Gatekeeper — the standard way to use OPA as an admission controller.

Next: Article 04 — OPA Gatekeeper on Kubernetes

---

📎 References

• OPA Deployment Documentation

• OPA REST API Reference

• OPA Configuration Reference

• OPA Decision Logs