OPA Gatekeeper on Kubernetes

📖 Introduction

Setting up a raw OPA admission webhook in Kubernetes by hand is instructive once — you learn exactly what's happening under the hood. But Gatekeeper is the practical path. It wraps OPA with a Kubernetes-native API: ConstraintTemplates define policy schemas, Constraints instantiate them, and the framework handles webhook registration, status reporting, and audit mode automatically.

This article walks through installing Gatekeeper on a local cluster and understanding its architecture before we write actual policies in Article 05.

---

🏗️ Gatekeeper Architecture

Gatekeeper extends Kubernetes with two custom resource types:

• ConstraintTemplate — defines a new constraint kind and the Rego policy logic behind it

• Constraint — an instance of a ConstraintTemplate with specific parameters applied to specific resources

The separation of template and instance is powerful:

• One template (e.g., RequiredLabels) defines the policy logic once

• Multiple constraints can instantiate it with different parameters for different namespaces or resource types

---

🔄 How the Admission Flow Works

Gatekeeper also runs in audit mode — it periodically re-checks all existing resources against all active constraints and reports violations in the constraint's status. This catches resources that predate a policy or were created while Gatekeeper was down.

---

📦 Installing Gatekeeper

Prerequisites

# Local cluster with kind
kind create cluster --name opa-demo

# Verify kubectl context
kubectl cluster-info --context kind-opa-demo

Install via Helm (Recommended)

helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts
helm repo update

helm install gatekeeper gatekeeper/gatekeeper \
  --namespace gatekeeper-system \
  --create-namespace \
  --version 3.17.1

Install via Manifest (Alternative)

kubectl apply -f https://raw.githubusercontent.com/open-policy-agent/gatekeeper/v3.17.1/deploy/gatekeeper.yaml

Verify Installation

kubectl -n gatekeeper-system get pods

NAME                                             READY   STATUS    RESTARTS   AGE
gatekeeper-audit-7bf79d4f7d-xkpl2               1/1     Running   0          60s
gatekeeper-controller-manager-6bc5db9bfc-8fnwx  1/1     Running   0          60s
gatekeeper-controller-manager-6bc5db9bfc-tbzmh  1/1     Running   0          60s

Three components:

• controller-manager — handles admission webhook requests (2 replicas for HA)

• audit — periodically re-evaluates existing resources

Check the validating webhook was registered:

kubectl get validatingwebhookconfiguration gatekeeper-validating-webhook-configuration

---

🧩 ConstraintTemplate Structure

A ConstraintTemplate has two parts:

1. CRD schema — defines the custom resource (the Constraint kind) and any parameters it accepts

2. Rego targets — the actual policy logic

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8srequiredlabels
spec:
  crd:
    spec:
      names:
        kind: K8sRequiredLabels       # This becomes a new CRD kind
      validation:
        openAPIV3Schema:
          type: object
          properties:
            labels:                   # Parameters the constraint can pass in
              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 are missing: %v", [missing])
        }

Key things to notice:

• The Rego package name matches the template name by convention

• input.review.object is the Kubernetes resource being evaluated

• input.parameters contains the values from the Constraint instance

• Violations are expressed as a set — each element must have a msg field

---

🎛️ Constraint Structure

Once a ConstraintTemplate is installed (and its CRD is created), you instantiate it with a Constraint:

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
  name: require-team-label
spec:
  match:
    kinds:
      - apiGroups: [""]
        kinds: ["Namespace"]
  parameters:
    labels: ["team", "environment"]

This constraint:

• Uses the K8sRequiredLabels template

• Matches all Namespace resources

• Requires the labels team and environment

Apply both:

kubectl apply -f constrainttemplate.yaml
kubectl apply -f constraint.yaml

Test it:

# This should be denied
kubectl create namespace test-no-labels

# Error output:
# Error from server (Forbidden): admission webhook "validation.gatekeeper.sh" denied the request:
# [require-team-label] Required labels are missing: {"environment", "team"}

---

🔍 Scoping Constraints

The match field controls what a constraint applies to:

spec:
  match:
    # Match specific resource kinds
    kinds:
      - apiGroups: ["apps"]
        kinds: ["Deployment", "StatefulSet"]
    
    # Restrict to certain namespaces
    namespaces: ["production", "staging"]
    
    # Exclude certain namespaces
    excludedNamespaces: ["kube-system", "gatekeeper-system"]
    
    # Label selector on the resource
    labelSelector:
      matchLabels:
        enforce-policy: "true"

This granularity lets you roll out policies incrementally — start with one namespace or resource type, expand as you gain confidence.

---

📋 Checking Constraint Status

After applying a constraint, check its status for audit results:

kubectl get k8srequiredlabels require-team-label -o yaml

Look for the status.violations field — it lists all currently violating resources:

status:
  violations:
  - enforcementAction: deny
    kind: Namespace
    message: 'Required labels are missing: {"team", "environment"}'
    name: default
  - enforcementAction: deny
    kind: Namespace
    message: 'Required labels are missing: {"team", "environment"}'
    name: kube-public

This is audit mode in action — existing resources that violate the policy are reported without blocking them (unless enforcementAction: deny is set).

---

⚠️ Enforcement Actions

Gatekeeper supports three enforcement actions:

Action	Behavior
deny	Block the admission request
warn	Allow but return a warning message
dryrun	Allow; only report violations in status

Set it in the Constraint:

spec:
  enforcementAction: warn   # or deny, dryrun

dryrun is invaluable when rolling out a new policy: you can see what would be blocked before actually blocking anything.

---

🛡️ Exempting Namespaces

Gatekeeper itself (and Kubernetes system namespaces) should be exempt from most policies. Configure exemptions at the Gatekeeper level:

# In the Helm values or gatekeeper config
apiVersion: config.gatekeeper.sh/v1alpha1
kind: Config
metadata:
  name: config
  namespace: gatekeeper-system
spec:
  match:
    - excludedNamespaces: ["kube-system", "gatekeeper-system", "cert-manager"]
      processes: ["*"]

Or per-constraint via excludedNamespaces in the match spec.

---

🧭 What's Next

You now have Gatekeeper running and understand how templates and constraints work together. The next article focuses on writing real, practical Kubernetes policies — pod security, image registries, resource limits, and more.

Next: Article 05 — Writing Kubernetes Admission Policies

---

📎 References

• Gatekeeper GitHub

• Gatekeeper Documentation

• Gatekeeper Library (Policy Templates)

• OPA Kubernetes Tutorial