Rego Language Fundamentals

📖 Introduction

Learning Rego felt unfamiliar at first. I'd been writing Python, TypeScript, and Go — all imperative to some degree. Rego is declarative in a way that took me a few sessions to internalize. It doesn't describe how to check something; it describes what must be true. Once that clicked, writing policies became intuitive.

This article is a ground-up tour of the Rego language. Every concept here is something you'll use when writing real Kubernetes policies later in the series.

---

🧩 Packages

Every Rego file starts with a package declaration. Packages organize policies into namespaces and determine how rules are referenced.

package myapp.security

When OPA evaluates a policy, results are available under data.<package.path>.<rule>:

data.myapp.security.deny

---

📥 Input and Data

Rego operates on two special global documents:

• input — the JSON document sent by the caller (the thing being evaluated)

• data — JSON loaded into OPA ahead of time (configuration, external data)

package example

# Access fields from input
app_name := input.metadata.name

# Access fields from loaded data
approved_registries := data.config.registries

Both are immutable during evaluation. OPA finds values; it doesn't mutate state.

---

📐 Rules

Rules are the core building blocks. A rule has a head (what it produces) and a body (the conditions under which it's true).

Simple Boolean Rules

package example

# Rule is true if the condition holds
is_privileged if {
    input.spec.containers[_].securityContext.privileged == true
}

If the body evaluates to true, the rule is defined (truthy). If the body is undefined or false, the rule itself is undefined.

Rules With Values

package example

# Rule produces a value
team := input.metadata.labels["team"]

Default Values

When a rule might be undefined, use default to provide a fallback:

package example

default allow := false

allow if {
    input.metadata.namespace == "staging"
}

Without the default, querying allow when no rule body matches would return undefined — which is different from false. The default makes intent explicit.

---

🔁 Iteration

Rego iterates implicitly using variables and the _ wildcard.

Wildcard Iteration

The _ placeholder means "any element, I don't care about the index":

package example

# true if any container requests privileged mode
any_privileged if {
    input.spec.containers[_].securityContext.privileged == true
}

Named Variable Iteration

Use a named variable when you need to reference the same element in multiple expressions:

package example

# true if any container uses an unapproved registry
uses_unapproved_image if {
    container := input.spec.containers[_]
    not startswith(container.image, "registry.internal/")
}

some for Explicit Iteration

The some keyword makes iteration explicit and is required in certain contexts:

package example

# Iterate with some
deny contains msg if {
    some container in input.spec.containers
    not startswith(container.image, "registry.internal/")
    msg := sprintf("container '%s' uses unapproved image: %s", [container.name, container.image])
}

some container in input.spec.containers binds container to each element of the array.

---

📦 Sets and Set Comprehensions

Rego has native set support. Partial rules that use contains build sets:

package example

# Builds a set of container names that violate the image policy
violating_containers contains name if {
    some container in input.spec.containers
    not startswith(container.image, "registry.internal/")
    name := container.name
}

You can also use set comprehensions inline:

package example

all_images := {img | img := input.spec.containers[_].image}

---

📋 Object Comprehensions

Build maps (JSON objects) inline:

package example

# Map of container name -> image
container_images := {name: img |
    container := input.spec.containers[_]
    name := container.name
    img := container.image
}

---

🔗 Logical AND and OR

AND — Multiple Expressions in One Body

All expressions in a single rule body must be true simultaneously (AND):

package example

deny contains msg if {
    input.kind == "Pod"                                   # AND
    input.spec.containers[_].securityContext.runAsRoot    # AND
    msg := "pods must not run as root"
}

OR — Multiple Rule Bodies With the Same Name

If you define multiple rules with the same name, OPA ORs them:

package example

# deny if any container runs as root
deny contains msg if {
    some c in input.spec.containers
    c.securityContext.runAsUser == 0
    msg := sprintf("container '%s' runs as root", [c.name])
}

# deny if hostNetwork is enabled — separate rule, same name "deny"
deny contains msg if {
    input.spec.hostNetwork == true
    msg := "hostNetwork must not be enabled"
}

OPA collects all values from all matching rules into the deny set.

---

🔧 Built-in Functions

OPA provides a rich set of built-in functions. The ones you'll use most in Kubernetes policies:

String Functions

# Check prefix
startswith("registry.internal/app:v1", "registry.internal/")  # true

# Check suffix
endswith("app:latest", ":latest")  # true

# Format strings
msg := sprintf("container '%s' violates policy", ["myapp"])

# Split
parts := split("registry.internal/app:v1", "/")

Collection Functions

# Count elements
count(input.spec.containers) > 0

# Check membership
"privileged" in input.spec.containers[_].capabilities.add

# every: all elements must satisfy condition
every c in input.spec.containers {
    c.resources.limits.memory != ""
}

every — Universal Quantification

package example

# All containers must have memory limits
all_have_memory_limits if {
    every c in input.spec.containers {
        c.resources.limits.memory != ""
    }
}

every passes only if the condition is true for every element in the collection.

---

🧮 Functions (User-Defined)

You can define reusable functions in Rego:

package example

# Helper function: check if an image uses a tag (not a digest)
uses_mutable_tag(image) if {
    not contains(image, "@sha256:")
    not endswith(image, ":latest") # latest is also mutable but handled separately
}

deny contains msg if {
    some c in input.spec.containers
    uses_mutable_tag(c.image)
    msg := sprintf("container '%s' uses mutable image tag: %s", [c.name, c.image])
}

---

🌳 Nested Data Access

Kubernetes resources are deeply nested. Rego handles this cleanly:

package example

# Safe navigation — if field doesn't exist, rule body is undefined
has_security_context if {
    _ = input.spec.containers[_].securityContext
}

# Accessing optional nested fields
deny contains msg if {
    some c in input.spec.containers
    c.securityContext.allowPrivilegeEscalation == true
    msg := sprintf("container '%s' allows privilege escalation", [c.name])
}

If securityContext doesn't exist on a container, c.securityContext.allowPrivilegeEscalation is undefined — and an undefined expression causes the rule body to not match (no false positive, no crash).

---

🔬 Trying Rego Locally

The fastest way to learn Rego is the interactive REPL:

opa run

> input := {"metadata": {"name": "myapp"}, "spec": {"containers": [{"name": "app", "image": "docker.io/nginx:latest"}]}}
> input.spec.containers[0].image
"docker.io/nginx:latest"
> startswith(input.spec.containers[0].image, "registry.internal/")
false

Or evaluate a policy file against an input file:

# Write a policy
cat > policy.rego <<EOF
package example

deny contains msg if {
    some c in input.spec.containers
    not startswith(c.image, "registry.internal/")
    msg := sprintf("unapproved image: %s", [c.image])
}
EOF

# Write an input
cat > input.json <<EOF
{
  "spec": {
    "containers": [
      {"name": "app", "image": "docker.io/nginx:latest"}
    ]
  }
}
EOF

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

Output:

{
  "result": [
    {
      "expressions": [
        {
          "value": ["unapproved image: docker.io/nginx:latest"],
          "text": "data.example.deny"
        }
      ]
    }
  ]
}

---

🗺️ Rego Mental Model Summary

Concept	Purpose
package	Namespace for rules
input	The thing being evaluated
data	Loaded external configuration
default	Fallback when a rule is undefined
contains	Build a set incrementally
_	Wildcard iteration
some ... in ...	Explicit iteration
every ... in ...	Universal quantification

---

🧭 What's Next

You now know enough Rego to write meaningful policies. The next article covers how OPA runs — the architecture, deployment modes, and how the query flow actually works before we get into Kubernetes-specific usage.

Next: Article 03 — OPA Architecture and Deployment Modes

---

📎 References

• OPA Policy Language Reference

• Built-in Functions Reference

• OPA Playground

• Rego Style Guide