Testing OPA Policies

📖 Introduction

Untested policies are a liability. A policy that should block images from untrusted registries but silently passes them due to a Rego logic error is worse than no policy — it creates false confidence. I learned this the hard way after deploying a hostNetwork restriction that passed all resources because I had a subtle logic inversion in the rule body.

The good news: OPA has a built-in test framework. Policy unit tests are written in Rego, run with opa test, and integrate naturally into CI/CD pipelines. This article covers everything you need to write thorough, maintainable policy tests.

---

🧪 OPA Test Basics

OPA test files are regular .rego files where every rule starting with test_ is a test case. Tests pass if the rule body evaluates to true (or is non-empty for sets). They fail if the body is false, undefined, or empty.

package k8snolatesttag_test

import rego.v1
import data.k8snolatesttag

# --- Test data ---

pod_with_latest := {
    "review": {
        "object": {
            "spec": {
                "containers": [{"name": "app", "image": "nginx:latest"}]
            }
        }
    }
}

pod_with_pinned := {
    "review": {
        "object": {
            "spec": {
                "containers": [{"name": "app", "image": "nginx:1.25.3"}]
            }
        }
    }
}

# --- Tests ---

test_deny_latest_tag if {
    count(k8snolatesttag.violation) > 0 with input as pod_with_latest
}

test_allow_pinned_tag if {
    count(k8snolatesttag.violation) == 0 with input as pod_with_pinned
}

Key patterns:

• with input as <value> — override input for this evaluation

• import data.<package> — import the policy under test

• Test file uses the _test suffix by convention (not required)

---

🏃 Running Tests

# Run all tests in current directory (recursive)
opa test .

# Run with verbose output
opa test . -v

# Run with coverage
opa test . --coverage

Sample output:

PASS: 8/8

k8snolatesttag_test.rego:
  test_deny_latest_tag: PASS (1.2ms)
  test_allow_pinned_tag: PASS (0.8ms)
  test_deny_no_tag: PASS (0.9ms)

k8sapprovedregistries_test.rego:
  test_deny_unapproved_registry: PASS (1.1ms)
  test_allow_approved_registry: PASS (0.9ms)
  test_deny_init_container: PASS (1.0ms)
  test_allow_approved_init_container: PASS (0.8ms)
  test_deny_multiple_containers_one_violates: PASS (1.1ms)

---

🗂️ Test Structure Conventions

Structure your policy and test files alongside each other:

policies/
├── k8s/
│   ├── image-registry.rego
│   ├── image-registry_test.rego
│   ├── no-latest-tag.rego
│   ├── no-latest-tag_test.rego
│   ├── pod-security.rego
│   └── pod-security_test.rego
└── data/
    └── approved-registries.json

---

📋 Writing Comprehensive Tests

A complete test file for the image registry policy:

package k8sapprovedregistries_test

import rego.v1
import data.k8sapprovedregistries

# --- Test fixtures ---

input_with(containers) := {
    "review": {
        "object": {
            "metadata": {"name": "test-pod"},
            "spec": {
                "containers": containers,
                "initContainers": []
            }
        }
    },
    "parameters": {
        "registries": ["registry.internal/", "gcr.io/myproject/"]
    }
}

# Single approved container
test_allow_approved_registry if {
    count(k8sapprovedregistries.violation) == 0
        with input as input_with([
            {"name": "app", "image": "registry.internal/myapp:v1.2.3"}
        ])
}

# Single unapproved container
test_deny_unapproved_registry if {
    violations := k8sapprovedregistries.violation
        with input as input_with([
            {"name": "app", "image": "docker.io/nginx:latest"}
        ])
    count(violations) == 1
    violations[_] == "Container 'app' uses unapproved image: docker.io/nginx:latest"
}

# Multiple containers — one violates
test_deny_one_unapproved_among_many if {
    violations := k8sapprovedregistries.violation
        with input as input_with([
            {"name": "app", "image": "registry.internal/myapp:v1.2.3"},
            {"name": "sidecar", "image": "docker.io/nginx:latest"},
            {"name": "helper", "image": "gcr.io/myproject/helper:v2"}
        ])
    count(violations) == 1
}

# Multiple containers — all violate
test_deny_all_unapproved if {
    violations := k8sapprovedregistries.violation
        with input as input_with([
            {"name": "app", "image": "docker.io/nginx:latest"},
            {"name": "db", "image": "quay.io/postgres:14"}
        ])
    count(violations) == 2
}

# Second approved registry prefix
test_allow_gcr_approved_prefix if {
    count(k8sapprovedregistries.violation) == 0
        with input as input_with([
            {"name": "app", "image": "gcr.io/myproject/myapp:v3"}
        ])
}

Good test coverage should include:

• Happy path — allowed resource produces no violations

• Violation path — each violation condition triggers

• Edge cases — empty arrays, missing fields, multiple containers

• Violation message — the message content is correct

---

🔤 Testing with with for Data

When policies reference data (like approved registries loaded externally), you can override it in tests:

test_deny_with_custom_registries if {
    violations := k8sapprovedregistries.violation
        with input as input_with([{"name": "app", "image": "myrepo.io/app:v1"}])
        with data.approved_registries.registries as ["registry.internal/"]
    count(violations) == 1
}

test_allow_with_custom_registries if {
    count(k8sapprovedregistries.violation) == 0
        with input as input_with([{"name": "app", "image": "myrepo.io/app:v1"}])
        with data.approved_registries.registries as ["myrepo.io/"]
}

---

📊 Code Coverage

Run with --coverage to see which lines are exercised by tests:

opa test . --coverage --format=json | jq '.files."k8s/image-registry.rego"'

{
  "covered": [
    {"start": {"row": 5}, "end": {"row": 10}},
    {"start": {"row": 14}, "end": {"row": 18}}
  ],
  "not_covered": [
    {"start": {"row": 21}, "end": {"row": 25}}
  ],
  "coverage": 80
}

Uncovered lines usually indicate missing test cases — add tests for the edge case that exercises those lines.

---

🧰 Conftest: Policy Testing for YAML and JSON Files

conftest is a tool built on OPA that makes it easy to test Kubernetes manifests, Terraform plans, and other config files against Rego policies — without writing a Gatekeeper setup. It's particularly useful in CI/CD pipelines.

brew install conftest

Directory Structure for Conftest

project/
├── manifests/
│   └── deployment.yaml
└── policy/
    └── image-registry.rego

Conftest looks for policies in the policy/ directory by default.

Writing Conftest-compatible Policies

Conftest uses deny, warn, or violation rules:

package main

import rego.v1

deny contains msg if {
    input.kind == "Deployment"
    container := input.spec.template.spec.containers[_]
    not startswith(container.image, "registry.internal/")
    msg := sprintf("Unapproved image: %s", [container.image])
}

Note: with Conftest, input is the YAML/JSON document directly (not wrapped in review.object).

Running Conftest

# Test a single file
conftest test manifests/deployment.yaml

# Test with specific policy directory
conftest test --policy ./policy manifests/

# Test against multiple files  
conftest test manifests/*.yaml

Output:

FAIL - manifests/deployment.yaml - main - Unapproved image: docker.io/nginx:latest

1 test, 0 warnings, 1 failure

---

🔄 Integration with opa test in a Makefile

A simple Makefile target that validates and tests policies:

.PHONY: policy-test policy-check

# Run all OPA unit tests
policy-test:
	opa test ./policies/ -v

# Check for syntax errors
policy-check:
	opa check ./policies/

# Build bundle (only after tests pass)
bundle: policy-test
	opa build -b ./policies/ -o dist/bundle.tar.gz \
	  --revision $(shell git rev-parse --short HEAD)

---

🧭 What's Next

The final article in this series brings everything together in a CI/CD pipeline — enforcing policies on manifests and Terraform plans before anything reaches the cluster.

Next: Article 08 — OPA in CI/CD Pipelines

---

📎 References

• OPA Policy Testing Documentation

• OPA Test CLI Reference

• Conftest Documentation

• Conftest GitHub