Policy as Code

Policies expressed in version-controlled, testable, machine-verifiable form. Kyverno, OPA/Rego, Conftest, AWS IAM Conditions. The discipline that makes 'we have a policy' actually true.

Policies live in Git, get reviewed in PRs, get tested in CI, and get enforced at admission time. Not a Word doc. Status: STUB — promoted to OUTLINE in Y3 Phase 27.

What this pattern is

Policy-as-code expresses organizational policies (security, compliance, naming conventions, resource limits, network connectivity rules) in version-controlled, testable, machine-verifiable form rather than as prose in a wiki. The pattern is operationally instantiated by Kyverno (Kubernetes-native, YAML-based policies that block non-compliant admission), OPA and Rego (general-purpose policy engine that runs as a sidecar or admission webhook), Conftest (CI-time Rego checks against IaC), AWS IAM Conditions (policies on resource access), and GitHub Actions or GitLab CI (deployment-time policy gates).

The pattern’s value is that policies become real: they’re tested, they’re enforced automatically, drift is impossible without a code change, and a violation is a CI failure or admission rejection, not a quarterly audit finding. Prose policies in wikis have a well-documented failure mode. Engineers can’t remember them, so they violate them; auditors find the violations quarterly and produce action items; engineers fix a subset and forget the rest; repeat. Policy-as-code short-circuits this by making the policy an active participant in the deploy pipeline. If your code violates a policy, the policy blocks the deploy. There’s no quarterly-audit accumulation of drift because drift can’t happen.

The discipline composes with defense-in-depth (policy is one layer of enforcement) and gitops (policy code reconciles like every other declaration). Well-designed policy-as-code setups reuse GitOps machinery: policies live in the same repo shape as other declarations; they’re deployed via the same Flux reconciler; they’re tested via the same CI pipeline. No separate policy-management tooling.

Concrete instances in the wild

  • Kyverno on Kubernetes. YAML-based policies enforced at admission. Example policies: block pods running as root, require resource limits on every workload, prohibit latest image tags, enforce specific labels on every resource.
  • OPA / Gatekeeper. Rego-based policies with more expressive power than Kyverno. Used at Google, Netflix, and other hyperscale K8s deployments.
  • Conftest. OPA-powered CI-time policy checks against Terraform, Kubernetes manifests, Dockerfiles. Runs in GitHub Actions before merge.
  • HashiCorp Sentinel. Terraform Enterprise’s policy engine. Blocks Terraform plans that would create disallowed resources.
  • AWS IAM Conditions. IAM policies with conditions like aws:RequestedRegion or aws:SourceIP scope access dynamically. The pattern applied at the cloud IAM layer.
  • Falco. Runtime security policy engine. Detects and alerts on suspicious behavior (unexpected process, unexpected network flow) at runtime.
  • eBPF-based policies. Cilium’s runtime policies, Tetragon’s observability. Policy enforcement at the kernel level.
  • GitHub branch protection rules. Simple policy-as-code: main requires PR, PR requires review, PR requires CI green. Version-controlled through GitHub’s API and Terraform providers.
  • Cloud Custodian. AWS/Azure/GCP resource-scanning policy engine. Detects and remediates non-compliant resources (unencrypted buckets, unused resources, misconfigured IAM).

Why this pattern matters

Without policy-as-code, security and compliance are aspirational. Policies live in Confluence pages that nobody reads. Engineers know some subset of them by heart and forget the rest. Audits find violations; teams remediate the specific violations; the wiki doesn’t get updated; the cycle repeats. The organization has policies in name only.

With policy-as-code, policies are executable. A pod that violates a security policy can’t deploy. An IaC change that provisions a non-compliant resource can’t merge. A resource that drifts out of compliance triggers an alert or a remediation. The gap between “we have a policy” and “the policy is enforced” collapses to zero.

The pattern also makes policies explainable. A Kyverno policy that blocks non-compliant workloads produces a rejection message that names the policy. Engineers see the policy and understand what to fix. Contrast with the ambiguity of “the security team said we can’t do that” — no version, no test case, no defined behavior. Policy-as-code turns policies into engineering artifacts that engineers can reason about, test, and improve.

The counter-failure mode is policy overreach. Every policy is friction. Too many policies, or policies that are hard to understand, produce engineer workarounds (sneaky bypasses, over-permissive exceptions, disabled enforcement). Well-run policy-as-code programs balance strictness with usability, measure the friction, and remove policies that produce more workarounds than security benefit.

Depth progression

STUB     ← you are here.
OUTLINE  Promoted when Y3 Phase 27 deploys Kyverno on basecamp with at least
         5 enforced policies.
DEEP     Promoted after Y3 end — Kyverno operational ~6+ months, including at
         least one PR that policy-as-code blocked before merge.

Preview: what OUTLINE will answer

When Y3 Phase 27 promotes this entry to OUTLINE, it will name:

  • PROBLEM. How do you make organizational policies actually enforced rather than aspirational?
  • PRINCIPLES. Policies as version-controlled code. Automated enforcement (admission or CI). Human-readable rejection messages. Testable policies (unit tests for policy logic). Break-glass procedure for legitimate exceptions.
  • TRADE-OFFS. Strictness (more policies, more friction) vs enforcement (fewer violations). Runtime enforcement (Kyverno admission) vs CI enforcement (Conftest) vs drift detection (Cloud Custodian). Global policies (apply everywhere) vs scoped (namespace/team-specific). Warning mode (log, don’t block) vs enforcement mode (block).
  • TOOLS (time-stamped as of 2026-06): Kyverno, OPA / Gatekeeper, Conftest, HashiCorp Sentinel, AWS IAM Conditions, Cloud Custodian, Falco, GitHub branch protection.

The DEEP promotion, after Y3 end with real Kyverno operation, will add MASTERY (operating Kyverno with 10+ enforced policies for months), COMPARE (Kyverno vs OPA/Gatekeeper), OPERATE (a specific PR blocked and remediated because of policy-as-code), and CONTRIBUTE (a Kyverno policy contributed to a policy library or a Kyverno documentation fix).

Canonical references

  • Kyverno documentation, particularly the policy library. Free at kyverno.io.
  • Open Policy Agent (OPA) documentation and the Rego language reference. Free at openpolicyagent.org.
  • Justin Cormack’s talks on policy-as-code — practical framing from Docker’s security lead.
  • CNCF’s TAG Security policy documentation.
  • Cloud Custodian project documentation for AWS/Azure/GCP resource compliance.

Cross-references