Kyverno

Kyverno is a policy engine that runs entirely inside Kubernetes, behind an admission webhook, and its single defining decision is what language a policy gets written in: not Rego, not a bespoke DSL, but the same declarative YAML you already write for a Deployment or a NetworkPolicy. A rule that says "containers must run as non-root" looks like a fragment lifted straight out of a Pod spec, because that's almost literally what it is. That one choice is why Kyverno shows up on so many clusters run by teams who never signed up to become policy-language specialists: its four rule types — validate, mutate, generate, and verifyImages — cover rejecting a bad resource, silently fixing a missing field, auto-provisioning a companion resource like a default-deny NetworkPolicy, and checking a container image's cryptographic signature, and every one of them is expressed the same way: as a pattern laid directly over the resource it's judging.

What Kyverno is and the problem it solves

☺ Like you're 10: It's a policy checker that lives inside the cluster itself, and its policies are ordinary Kubernetes objects written in ordinary Kubernetes YAML, not files in some other language somewhere else.

Kyverno began as an internal project at Nirmata and was open-sourced and donated to the Cloud Native Computing Foundation in 2020; it's a CNCF Incubating project as of this writing — check the CNCF landscape for its current maturity level before citing that in anything official. Functionally it's a Kubernetes-native admission controller: install it, typically via its Helm chart, and it registers mutating and validating webhooks with the API server. Everything past that point is expressed as ordinary Kubernetes custom resources. A ClusterPolicy (cluster-scoped) or Policy (namespace-scoped) isn't a config file sitting in a repository that Kyverno reads on startup — it's a live object you kubectl apply and kubectl get exactly like a Deployment, versioned in git the same way any manifest is, and inspectable with the same tool everyone on the team already has open.

It's worth being precise about where Kyverno sits in the pipeline, because two other pages already cover policy engines and it's easy to conflate them. Checkov, tfsec, and OPA & Conftest check a Terraform plan before anything is ever created — the resource doesn't exist yet, so a violation is caught as a text diff in a pull request, the pre-deploy layer IaC security & policy as code and Infrastructure as Code Hardening cover in depth. Kyverno checks a live Kubernetes API request at the moment a resource is actually being created or changed inside the cluster — after the plan already applied, at the one chokepoint every workload has to pass through to run at all, whether it arrived from a pristine CI pipeline or a kubectl apply someone ran by hand from their laptop. Neither checkpoint substitutes for the other, which is exactly the argument Platform Engineering for Security Guardrails makes about admission control as the layer a per-repo pipeline check can't be silently skipped at.

Four rule types cover essentially everything a real cluster asks of a policy engine, and the rest of this page takes each one in turn: validate accepts or rejects a resource against a pattern, mutate silently patches a resource to add or correct a field, generate creates — and optionally keeps in sync — a companion resource whenever a trigger resource appears, and verifyImages checks a container image's cryptographic signature before letting its Pod through.

Architecture: policies are live Kubernetes objects, not config files

☺ Like you're 10: Kyverno isn't one program — it's a small team of controllers sharing the same policy objects: one blocks or fixes things as they happen, one re-checks things that already exist, one writes down what it found, and one tidies up on a schedule.

Kyverno versions from roughly the 1.10 release line onward split what used to be a single deployment into four narrower controllers, each with a smaller blast radius if it misbehaves: the admission controller (kyverno) runs the actual mutating and validating webhooks and is the only one in the synchronous, request-blocking path; the background controller periodically re-evaluates already-existing resources against every policy and reconciles generate rules whose source resource changed after the fact; the reports controller aggregates the background controller's findings into PolicyReport and ClusterPolicyReport objects; and the cleanup controller runs scheduled CleanupPolicy/ClusterCleanupPolicy objects — a TTL-style mechanism for deleting resources that match a condition, useful for things like expired PolicyException waivers. Older or minimal installs may still run these as one deployment; the logical split is the part worth remembering.

Three fields on every policy's spec decide how much of that machinery actually engages, and getting them wrong is the single most common source of "why didn't this policy do anything" tickets:

• validationFailureAction — Audit records a finding in a PolicyReport without blocking anything; Enforce makes a validate rule an actual admission-time gate. This is precisely the soft-guardrail-vs-hard-gate distinction IaC security & policy as code already covers for Terraform, one layer further downstream.
• background — whether the background controller re-scans already-existing resources against this policy, not just new or changed ones arriving at admission. A policy installed today with background: false tells you nothing about the violations already sitting in the cluster from before it existed.
• failurePolicy — Fail or Ignore, the same admission-webhook doctrine every webhook-based engine shares: if the Kyverno webhook Pod is unreachable, Fail blocks every matching request cluster-wide until it recovers, and Ignore lets everything through unchecked in the meantime. See the warning under Gotchas below.

The four rule types: validate, mutate, generate, verifyImages

☺ Like you're 10: One rule type says no, one quietly fixes what's missing, one creates a second object to go with the first, and one checks a signature — and all four are written the same way, as a pattern laid over the resource.

Every rule lives inside a policy's rules list and starts with a match block selecting which resources it applies to; from there, the rule body is one of the four types below. Kyverno's pattern language layers a handful of anchors on top of plain YAML: * and ? are wildcards for matching part of a value, =(key) is a conditional anchor that only checks the field if it's present (rather than failing when it's absent entirely), ^(key) requires the field to exist, and +(key) — used in mutate rules specifically — means "add this value only if the field isn't already set." Variables come from JMESPath expressions wrapped in {{ }}, pulling from context like request.object, the resource that triggered the rule.

validate — accept or reject against a pattern

The most common rule type. A validate.pattern block mirrors the shape of the resource it's checking, and Kyverno walks the real object looking for a mismatch:

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-non-root
spec:
  validationFailureAction: Audit   # flip to Enforce once the PolicyReport backlog is clean — see Gotchas
  background: true
  rules:
    - name: containers-must-run-as-non-root
      match:
        any:
          - resources:
              kinds: [Pod]
      validate:
        message: "containers must set securityContext.runAsNonRoot: true"
        pattern:
          spec:
            =(securityContext):
              runAsNonRoot: true
            containers:
              - =(securityContext):
                  runAsNonRoot: true

The =() anchors mean this rule doesn't fail a Pod that sets runAsNonRoot only at the Pod level and not per-container, or vice versa — either placement satisfies it, but if neither is set at all, the rule fails, because at least one =() block has to actually match something. Getting comfortable with that anchor is most of learning to write Kyverno validate rules that don't produce false positives on legitimate variation.

mutate — patch a resource instead of just rejecting it

Where OPA-style engines can only say yes or no, Kyverno can fix the problem itself before the object is ever persisted. A patchStrategicMerge block overlays new content onto matching resources, and the +() anchor is what keeps it from clobbering a value someone already set on purpose:

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: default-resource-requests
spec:
  rules:
    - name: add-default-requests
      match:
        any:
          - resources:
              kinds: [Pod]
      mutate:
        patchStrategicMerge:
          spec:
            containers:
              - (name): "*"          # matches every container in the array
                resources:
                  +(requests):        # only ADD requests if this container doesn't already set them
                    cpu: 100m
                    memory: 128Mi

Mutation always runs before validation in the admission chain, which is deliberate: a Pod this rule patches with default requests can then pass a separate validate rule that requires requests to be set, without a developer having to write the field themselves. That ordering is also the thing to watch — a mutate rule that's silently "fixing" something can mask a gap the developer never learns about, which is why pairing a mutate rule with visibility (a linter, a PolicyReport, a code-review norm) matters as much as writing the rule itself.

generate — provision a companion resource automatically

A generate rule fires when its trigger resource is created and produces a second, related resource — most commonly a default-deny NetworkPolicy for every new namespace, closing exactly the gap Kubernetes Security Deep Dive covers about NetworkPolicy rules being additive and denying by default once any policy exists:

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: generate-default-deny-networkpolicy
spec:
  rules:
    - name: default-deny-all
      match:
        any:
          - resources:
              kinds: [Namespace]
      exclude:
        any:
          - resources:
              namespaces: [kube-system, kyverno]
      generate:
        apiVersion: networking.k8s.io/v1
        kind: NetworkPolicy
        name: default-deny-all
        namespace: "{{request.object.metadata.name}}"
        synchronize: true        # if someone deletes or edits it, the background controller reverts it
        data:
          spec:
            podSelector: {}
            policyTypes: [Ingress, Egress]

synchronize: true is the field that turns this from a one-time stamp into an ongoing guarantee: every new namespace gets the NetworkPolicy the moment it's created, and if someone deletes it later — accidentally, or to "just get this working" during an incident — the background controller puts it back on its next pass. That's the same never-negotiates-with-drift behavior IaC security & policy as code describes for infrastructure, running here against live cluster objects instead of cloud resources.

verifyImages — check a container's cryptographic signature

This rule type is Kyverno's most turnkey answer to supply-chain trust: it verifies a Pod's images against a Sigstore cosign signature before admitting it, using either a fixed public key or "keyless" verification tied to an OIDC identity — the same mechanism Platform Engineering for Security Guardrails and Secure SDLC Gates & the DevSecOps Maturity Model both close their build-stage signing story with:

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-signed-images
spec:
  validationFailureAction: Enforce
  background: false
  rules:
    - name: verify-cosign-signature
      match:
        any:
          - resources: { kinds: [Pod] }
      verifyImages:
        - imageReferences: ["registry.acme.internal/*"]
          attestors:
            - entries:
                - keyless:
                    subject: "https://github.com/acme-corp/*/.github/workflows/*"
                    issuer: "https://token.actions.githubusercontent.com"

Read Sigstore & cosign for what "keyless" signing is actually verifying under the hood — the subject and issuer fields above are checking a specific CI workflow's OIDC identity, not a long-lived private key. This rule is deliberately scoped to registry.acme.internal/* rather than every image on the cluster, because a hard requirement that every image everywhere carry a signature would also block every base image, sidecar, and vendor chart the cluster legitimately runs unsigned — imageReferences is how a verifyImages rule stays a gate on your own supply chain instead of an accidental gate on the entire ecosystem you depend on.

Autogen: one policy, every pod controller

☺ Like you're 10: Write a rule about Pods once, and Kyverno automatically copies it to also cover Deployments, StatefulSets, Jobs, and everything else that eventually creates Pods — so you don't have to write the same rule six times.

Almost nobody creates a bare Pod directly in a real cluster — they create a Deployment, a StatefulSet, a DaemonSet, a Job, or a CronJob, and that controller creates the Pod. A validate or mutate rule that only matched kind: Pod would therefore miss the actual moment of creation entirely, since a Deployment's own admission request never has kind: Pod on it. Kyverno solves this with autogen: when a rule's match block targets Pod, Kyverno automatically generates equivalent rules — named autogen-<rule-name> — that fire on the parent controller kinds too, rewriting the pattern to match each controller's spec.template.spec path automatically. You write one rule; six show up in kubectl describe cpol.

This is almost always what you want, and it's also the single most common source of "why did my Deployment get rejected when my policy only mentions Pod" confusion — the answer is that it did mention Pod, just not directly. Autogen behavior is controllable with the pod-policies.kyverno.io/autogen-controllers annotation on the policy: set it to a specific comma-separated list (Deployment,StatefulSet) to narrow which controllers get the generated rules, or to none to disable autogen entirely and match controllers explicitly yourself in the original rule.

Background scanning and PolicyReports: visibility before enforcement

☺ Like you're 10: Before you lock the door, it helps to know how many people are already inside — background scanning checks what's already running against a new rule and writes down what it finds, without kicking anyone out yet.

A brand-new policy applied with validationFailureAction: Enforce only ever sees resources created or changed after it exists — it says nothing about the two hundred Pods already running that would have failed it. The background controller closes that gap: on a schedule, it re-evaluates every existing matching resource against every policy with background: true, regardless of what the policy's failure action is, and writes the results to PolicyReport (namespaced) and ClusterPolicyReport (cluster-scoped) objects — a reporting format shared across several Kubernetes policy engines, not unique to Kyverno, which is why kubectl get policyreport -A is a genuinely useful "what's out of compliance right now" query independent of which tool produced the finding.

The practical workflow this enables is the same audit-then-enforce rollout IaC security & policy as code recommends for Terraform policy: ship a new rule as validationFailureAction: Audit, let the background controller run for a few days, review the PolicyReport backlog it produces, fix or explicitly except the pre-existing violations, and only then flip the rule to Enforce. Skipping straight to Enforce on a rule nobody's tuned against real cluster traffic doesn't just risk one bad admission decision — it can turn into an outage the moment a routine Deployment rollout tries to create a Pod that's been silently non-compliant for months. Part 5 of the capstone and the policy-as-code drill both walk this exact rollout end to end.

Day-to-day: installing, writing, testing, and applying policies

☺ Like you're 10: Install it once with Helm, then almost everything else is either kubectl on the policy objects themselves, or the kyverno CLI checking a policy before it ever touches a real cluster.

# install — Kyverno ships as a Helm chart, same as most platform components
$ helm repo add kyverno https://kyverno.github.io/kyverno/
$ helm repo update
$ helm install kyverno kyverno/kyverno -n kyverno --create-namespace

# every cluster-scoped and namespaced policy currently loaded — cpol/pol are the short names
$ kubectl get cpol
$ kubectl get pol -A
$ kubectl describe cpol require-non-root        # autogen-* rules show up here too

# visibility from background scans — this is where Audit-mode findings live
$ kubectl get policyreport -A
$ kubectl get clusterpolicyreport

# local, no-cluster-needed policy testing with the kyverno CLI
$ kyverno apply require-non-root.yaml --resource pod.yaml   # dry run against one file, no cluster contact
$ kyverno apply require-non-root.yaml --cluster              # dry run against everything live right now
$ kyverno test .                                              # run a declared kyverno-test.yaml test suite

kyverno test is worth calling out on its own — it's what makes a policy itself reviewable and CI-testable, not just the resources it checks, the same discipline OPA & Conftest gets from opa test against Rego. A test file declares which policies and resources to load, then asserts the expected pass/fail outcome for each policy-rule-resource combination:

# kyverno-test.yaml
name: require-non-root-test
policies:
  - require-non-root.yaml
resources:
  - resources.yaml       # contains both a bad-pod and a good-pod object, by metadata.name
results:
  - policy: require-non-root
    rule: containers-must-run-as-non-root
    resource: bad-pod
    kind: Pod
    result: fail
  - policy: require-non-root
    rule: containers-must-run-as-non-root
    resource: good-pod
    kind: Pod
    result: pass

Wiring kyverno test . into the pipeline that manages the policy repository itself closes a loop worth noticing: the policies enforcing shift-left on application code get their own shift-left check before they're ever applied to a cluster — a broken pattern that would have silently matched nothing, or a rule that's accidentally too strict for a legitimate workload, gets caught in the policy repo's own pull request instead of in a production admission failure at 2am.

Gotchas and failure modes

☺ Like you're 10: Most surprises come from one of a handful of habits: forgetting autogen exists, forgetting Audit mode doesn't block anything, or forgetting that the webhook itself is a thing that can go down.

• A down webhook with failurePolicy: Fail is a cluster-wide outage. If the Kyverno admission-controller Pod crashes, gets OOMKilled, or loses its last replica during a bad rollout, every matching write to the API server hangs or is rejected until it recovers — nothing can be scheduled, cluster-wide, the exact failure mode Kubernetes Security Deep Dive flags for any webhook-based policy engine. failurePolicy: Ignore avoids the outage but silently admits everything unchecked while Kyverno is down — there is no free option here, only a choice about which failure mode you'd rather have, and it should be a deliberate choice per policy rather than whatever the default happened to be.
• Autogen can reject a Deployment for a rule that "only mentions Pod." Covered above because it's genuinely the most common point of confusion — check kubectl describe cpol <name> for the autogen-* rules before assuming a policy applies only to bare Pods.
• Audit mode produces findings, not enforcement — and it's easy to forget which one you're in. A team that ships a policy as Audit, watches the PolicyReport stay clean for a week, and concludes "the policy works" has actually learned nothing about whether it would have blocked anything, because it never tried to. Deliberately break a test resource and confirm the finding appears before trusting an Audit-mode policy's silence.
• background: false hides pre-existing violations, permanently. Turning off background scanning to save resources on an expensive policy also means the background controller never re-evaluates resources that existed before the policy did, and — for a generate rule specifically — new namespaces created after a policy edit may not get the updated companion resource without a background pass to reconcile them.
• synchronize: true fights anyone who edits the generated resource by hand. That's the point for a security-critical default like a deny-all NetworkPolicy, but it produces genuinely confusing support tickets from a team that has a legitimate reason to change their generated resource and doesn't understand why it keeps reverting. The fix is a PolicyException, not disabling synchronization cluster-wide — see the object below.
• The pattern language has real expressiveness limits. Kyverno's overlay patterns are declarative and quick to read, but they're not a general logic language — expressing "if resource X exists elsewhere in this namespace, then Y must hold" or genuinely complex cross-resource conditionals pushes toward JMESPath preconditions or, past a certain complexity, toward a tool built for exactly that job. That limit is the whole subject of the next section.
• Newer CEL-based policy kinds are arriving alongside the classic YAML-pattern model. Recent Kyverno releases have begun adding CEL-expression policy kinds that echo Kubernetes' own built-in ValidatingAdmissionPolicy, alongside — not replacing — the pattern-based ClusterPolicy model this page covers. Check the current Kyverno documentation before assuming which policy kind a given cluster version supports; this is a genuinely moving target.

The fix for that synchronize: true gotcha is Kyverno's PolicyException resource — a tracked, reviewable Kubernetes object, not a Slack message nobody can find again six months later, and scoped narrowly to exactly the policy, rule, and namespace it exempts:

apiVersion: kyverno.io/v2beta1
kind: PolicyException
metadata:
  name: legacy-billing-non-root-exception
  namespace: legacy-billing
spec:
  exceptions:
    - policyName: require-non-root
      ruleNames:
        - containers-must-run-as-non-root
  match:
    any:
      - resources:
          kinds: [Pod]
          namespaces: [legacy-billing]

Kyverno vs. OPA Gatekeeper: same job, different language

☺ Like you're 10: Both tools sit at the same door checking the same kinds of things — the real difference is whether you have to learn a whole new language to write the rule, or whether you already basically know it.

OPA & Conftest covers Rego in full; the short version needed here is that Gatekeeper is the Kubernetes admission controller built on the Open Policy Agent engine, wrapping Rego policies behind a validating — and, more recently, mutating — webhook, with policies expressed as ConstraintTemplate CRDs (compiling the Rego itself) parameterized by separate Constraint CRDs. Functionally, Kyverno and Gatekeeper solve the identical admission-control problem: both register webhooks, both evaluate a resource against a policy, both can allow or deny. The entire practical difference is what you have to learn to write the rule, and that difference is larger than it might sound.

Put the same requirement side by side — every container must declare resource requests and limits, the exact rule OPA & Conftest writes in Rego for the same reason this page writes it in Kyverno:

# Gatekeeper / Rego — requires understanding partial-set iteration (some x in ...),
# and the classic "undefined isn't false" trap if the field is simply absent.
package k8srequiredresources

violation[{"msg": msg}] {
  container := input.review.object.spec.containers[_]
  not container.resources.limits
  msg := sprintf("container %v has no resource limits set", [container.name])
}

# Kyverno — reads like the Pod spec it's checking, because it basically is one.
validate:
  message: "every container must set resources.requests and resources.limits"
  pattern:
    spec:
      containers:
        - resources:
            requests: { memory: "?*", cpu: "?*" }
            limits: { memory: "?*", cpu: "?*" }

The Rego version isn't wrong or badly written — it's idiomatic Rego, and an engineer fluent in the language will read it just as fast as the YAML. The point is exactly that clause: fluent in the language. The Rego version depends on understanding partial-set unification (container := input...[_] iterating an array), negation over a possibly-absent field, and the specific shape Gatekeeper injects into input.review.object — none of which is knowledge a Kubernetes-fluent engineer already has by default. The Kyverno version depends on knowing that "?*" means "must be present and non-empty," a single convention learnable in one sitting, applied to a structure — a Pod's containers array — the same engineer has already read a hundred times.

None of this makes Gatekeeper the wrong choice — it makes it a different trade. An organization that already runs Rego for Terraform policy via OPA & Conftest, or that needs genuinely complex cross-resource logic Kyverno's pattern language strains to express, gets real value from one policy language spanning every layer instead of two. But for the far more common case — a platform or DevOps team that's fluent in Kubernetes manifests and wants admission control, mutation, resource generation, and image verification without adding a new language to the team's skill inventory — Kyverno's lower learning curve isn't a minor convenience. It's the difference between a policy a second engineer can review and confidently modify next quarter, and one that quietly becomes "the Rego file nobody but its original author fully trusts themselves to change."