Writing Kubernetes Admission Policies

📖 Introduction

This is the article I wish I'd had when I started writing Kubernetes policies. The conceptual foundation is important, but most of what you actually need is practical: how do I enforce image registry restrictions? How do I require labels? How do I stop people from using latest tags? What does the admission input actually look like?

This article covers the most common Kubernetes admission policies, written in Rego for OPA Gatekeeper. Each policy comes with the ConstraintTemplate, a Constraint example, and notes on edge cases.

---

🗂️ The Admission Review Input Shape

Before writing policies, you need to know what input contains inside a Gatekeeper Rego policy:

{
  "review": {
    "operation": "CREATE",
    "kind": {
      "group": "apps",
      "version": "v1",
      "kind": "Deployment"
    },
    "object": {
      // the Kubernetes resource being created/updated
    },
    "oldObject": {
      // previous version (for UPDATE operations)
    },
    "userInfo": {
      "username": "system:serviceaccount:ci:deployer",
      "groups": ["system:serviceaccounts"]
    }
  },
  "parameters": {
    // values from the Constraint instance
  }
}

Most policies operate on input.review.object — the resource itself. For debugging, the OPA Playground is useful: paste in a real Kubernetes YAML converted to JSON and test your policy interactively.

---

🧱 Policy 1: Required Labels

Enforce that specific labels exist on resources. In multi-team clusters, labels like team, app, and environment are required for cost allocation and incident response.

ConstraintTemplate:

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8srequiredlabels
spec:
  crd:
    spec:
      names:
        kind: K8sRequiredLabels
      validation:
        openAPIV3Schema:
          type: object
          properties:
            labels:
              type: array
              items:
                type: string
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package k8srequiredlabels

        violation[{"msg": msg}] {
            provided := {label | input.review.object.metadata.labels[label]}
            required := {label | label := input.parameters.labels[_]}
            missing := required - provided
            count(missing) > 0
            msg := sprintf("Required labels missing: %v", [missing])
        }

Constraint:

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
  name: require-standard-labels
spec:
  enforcementAction: deny
  match:
    kinds:
      - apiGroups: [""]
        kinds: ["Namespace"]
      - apiGroups: ["apps"]
        kinds: ["Deployment"]
  parameters:
    labels: ["team", "app", "environment"]

Test:

kubectl create namespace missing-labels
# Error: Required labels missing: {"app", "environment", "team"}

---

🖼️ Policy 2: Approved Image Registries

One of the first policies I deployed on a shared cluster. Prevents workloads from pulling from arbitrary public registries and pulling unvetted images.

ConstraintTemplate:

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8sapprovedregistries
spec:
  crd:
    spec:
      names:
        kind: K8sApprovedRegistries
      validation:
        openAPIV3Schema:
          type: object
          properties:
            registries:
              type: array
              items:
                type: string
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package k8sapprovedregistries

        violation[{"msg": msg}] {
            container := input.review.object.spec.containers[_]
            not approved_registry(container.image)
            msg := sprintf("Container '%s' uses unapproved image: %s", [container.name, container.image])
        }

        # Also check initContainers
        violation[{"msg": msg}] {
            container := input.review.object.spec.initContainers[_]
            not approved_registry(container.image)
            msg := sprintf("initContainer '%s' uses unapproved image: %s", [container.name, container.image])
        }

        approved_registry(image) {
            registry := input.parameters.registries[_]
            startswith(image, registry)
        }

Constraint:

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sApprovedRegistries
metadata:
  name: approved-registries
spec:
  enforcementAction: deny
  match:
    kinds:
      - apiGroups: [""]
        kinds: ["Pod"]
      - apiGroups: ["apps"]
        kinds: ["Deployment", "StatefulSet", "DaemonSet"]
    excludedNamespaces: ["kube-system", "gatekeeper-system"]
  parameters:
    registries:
      - "registry.internal/"
      - "gcr.io/myproject/"

---

🏷️ Policy 3: No Latest Tag

The latest tag is mutable — what an image resolves to can change between deployments, making rollbacks unreliable and behavior unpredictable.

ConstraintTemplate:

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8snolatesttag
spec:
  crd:
    spec:
      names:
        kind: K8sNoLatestTag
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package k8snolatesttag

        violation[{"msg": msg}] {
            container := input.review.object.spec.containers[_]
            endswith(container.image, ":latest")
            msg := sprintf("Container '%s' uses ':latest' tag. Pin to a specific version or digest.", [container.name])
        }

        violation[{"msg": msg}] {
            container := input.review.object.spec.containers[_]
            not contains(container.image, ":")    # no tag at all defaults to latest
            msg := sprintf("Container '%s' has no image tag. Specify a version or digest.", [container.name])
        }

Constraint:

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sNoLatestTag
metadata:
  name: no-latest-tag
spec:
  enforcementAction: deny
  match:
    kinds:
      - apiGroups: ["apps"]
        kinds: ["Deployment", "StatefulSet"]
    excludedNamespaces: ["kube-system", "gatekeeper-system"]

---

🔐 Policy 4: Pod Security — No Root Containers

Containers running as UID 0 have elevated privileges inside the container. This policy enforces non-root execution.

ConstraintTemplate:

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8snoroot
spec:
  crd:
    spec:
      names:
        kind: K8sNoRoot
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package k8snoroot

        violation[{"msg": msg}] {
            container := input.review.object.spec.containers[_]
            container.securityContext.runAsUser == 0
            msg := sprintf("Container '%s' must not run as root (runAsUser: 0)", [container.name])
        }

        violation[{"msg": msg}] {
            container := input.review.object.spec.containers[_]
            container.securityContext.runAsNonRoot == false
            msg := sprintf("Container '%s' has runAsNonRoot set to false", [container.name])
        }

        # Also check pod-level security context
        violation[{"msg": msg}] {
            input.review.object.spec.securityContext.runAsUser == 0
            msg := "Pod security context sets runAsUser to 0 (root)"
        }

Constraint:

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sNoRoot
metadata:
  name: no-root-containers
spec:
  enforcementAction: deny
  match:
    kinds:
      - apiGroups: [""]
        kinds: ["Pod"]
      - apiGroups: ["apps"]
        kinds: ["Deployment", "StatefulSet", "DaemonSet"]
    excludedNamespaces: ["kube-system", "gatekeeper-system"]

---

📊 Policy 5: Resource Limits Required

Workloads without resource limits can starve neighbors on a shared cluster. This policy enforces that every container declares CPU and memory limits.

ConstraintTemplate:

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8srequiredresourcelimits
spec:
  crd:
    spec:
      names:
        kind: K8sRequiredResourceLimits
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package k8srequiredresourcelimits

        violation[{"msg": msg}] {
            container := input.review.object.spec.containers[_]
            not container.resources.limits.cpu
            msg := sprintf("Container '%s' has no CPU limit set", [container.name])
        }

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

Constraint:

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredResourceLimits
metadata:
  name: require-resource-limits
spec:
  enforcementAction: deny
  match:
    kinds:
      - apiGroups: ["apps"]
        kinds: ["Deployment", "StatefulSet", "DaemonSet"]
    excludedNamespaces: ["kube-system", "gatekeeper-system"]

---

🌐 Policy 6: Disallow HostNetwork

Pods with hostNetwork: true bypass network isolation and can see all host-level network traffic. It should be restricted to a small set of system workloads.

ConstraintTemplate:

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8snohostnetwork
spec:
  crd:
    spec:
      names:
        kind: K8sNoHostNetwork
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package k8snohostnetwork

        violation[{"msg": msg}] {
            input.review.object.spec.hostNetwork == true
            msg := sprintf("Pod '%s' uses hostNetwork which is not allowed", 
                [input.review.object.metadata.name])
        }

Constraint:

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sNoHostNetwork
metadata:
  name: no-host-network
spec:
  enforcementAction: deny
  match:
    kinds:
      - apiGroups: [""]
        kinds: ["Pod"]
      - apiGroups: ["apps"]
        kinds: ["Deployment", "StatefulSet", "DaemonSet"]
    excludedNamespaces: ["kube-system", "gatekeeper-system"]

---

🔬 Debugging Policies

When a policy isn't behaving as expected, the most useful debugging workflow:

1. Check audit violations

kubectl get <constraint-kind> <constraint-name> -o jsonpath='{.status.violations}' | jq .

2. Test the Rego logic directly

Extract the input from a real resource:

kubectl get pod mypod -o json | jq '{review: {object: .}}' > input.json

Then test against your policy file:

opa eval -i input.json -d policy.rego "data.<package>.violation"

3. Use dryrun enforcement

Switch a constraint to enforcementAction: dryrun, apply it, and check status violations without blocking real traffic:

kubectl patch constraint require-resource-limits \
  --type merge \
  -p '{"spec":{"enforcementAction":"dryrun"}}'

---

📐 Gatekeeper Library

The Gatekeeper Library project maintains a collection of production-ready ConstraintTemplates. Before writing a policy from scratch, it's worth checking if a tested version already exists there.

# Clone and browse
git clone https://github.com/open-policy-agent/gatekeeper-library
ls library/

Common library policies: K8sRequiredLabels, K8sAllowedRepos, K8sNoPrivilegedContainers, K8sResourceLimits, K8sRequiredProbes.

---

🧭 What's Next

You now have a working library of Kubernetes policies. The next article covers how to manage and distribute policies at scale — OPA bundles, versioning, and the bundle server pattern.

Next: Article 06 — OPA Bundles and Policy Management

---

📎 References

• Gatekeeper Policy Library

• Gatekeeper ConstraintTemplate Reference

• Kubernetes Admission Controllers

• Pod Security Standards