Gatekeeper: Complete Configuration Guide

Introduction to Gatekeeper

Gatekeeper is a Kubernetes-native policy controller that integrates Open Policy Agent (OPA) with the Kubernetes API server. It allows platform teams to enforce custom policies across clusters by defining declarative constraints and auditing existing resources for compliance. Gatekeeper leverages Kubernetes Custom Resource Definitions (CRDs) to manage policies as code, making it an essential tool for governance, security, and compliance in cloud-native environments.

Why Gatekeeper Matters

In Kubernetes, RBAC controls who can do what, but it doesn’t answer questions like “What labels must a namespace have?” or “Which image registries are allowed?”. Gatekeeper fills this gap by enforcing fine-grained policies that govern the properties of resources, not just access. It provides:

• Preventive enforcement: Block non-compliant resources at admission time.
• Continuous auditing: Identify existing violations without breaking workloads.
• Policy as Code: Version-controlled, testable policies written in Rego.
• Dry-run mode: Test policies before enforcing them.
• Multi-tenancy governance: Ensure tenant isolation and consistent configurations.

Core Concepts

Gatekeeper operates around three key object types:

• Constraint Templates: Rego-based policy definitions that describe the logic and parameters. They define the schema for constraints.
• Constraints: Instances of a template, specifying allowed values for parameters and the resources to target (e.g., namespaces, labels).
• Audits: Periodic scans of existing resources to produce violations, stored in status fields.

A typical workflow: you create a Constraint Template that contains the Rego policy logic, then instantiate it with one or more Constraints that provide the specific configuration (e.g., allowed image prefixes). Gatekeeper evaluates incoming admission requests against the constraints and, if configured, denies non-compliant requests.

Installation and Setup

Gatekeeper can be installed via Helm or static manifests. The recommended approach is Helm, as it allows easier upgrades and configuration.

Using Helm

# Add the OPA Gatekeeper Helm repository
helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts
helm repo update

# Install Gatekeeper in the gatekeeper-system namespace
helm install gatekeeper gatekeeper/gatekeeper --namespace gatekeeper-system --create-namespace

After installation, verify the CRDs and controller pods are running:

kubectl get crd | grep gatekeeper
kubectl -n gatekeeper-system get pods

Key Configuration Flags

Common Helm values to customize:

• auditInterval: How often the audit scanner runs (default 60s).
• emitAdmissionEvents: Enable Kubernetes events for denials (default true).
• excludedNamespaces: List of namespaces to exclude from enforcement (e.g., kube-system).
• podSecurity: Enable pod security policy replacement if needed.

Defining Constraint Templates

A Constraint Template defines the policy logic in Rego and the parameters users can supply. The template must include targets: admission.k8s.gatekeeper and a crd specification.

Example: a template that requires all namespaces to have a label owner.

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8srequiredlabels
  annotations:
    description: "Requires a label on all namespaces."
spec:
  crd:
    spec:
      names:
        kind: K8sRequiredLabels
      validation:
        openAPIV3Schema:
          type: object
          properties:
            labels:
              type: array
              items:
                type: string
  targets:
    - target: admission.k8s.gatekeeper
      rego: |
        package k8srequiredlabels

        get_message(parameters) = {
          "message": sprintf("Missing required labels: %v", [missing_labels])
        }

        violation[{"msg": msg}] {
          provided := {label | input.review.object.metadata.labels[label]}
          required := {label | parameters.labels[label]}
          missing := required - provided
          count(missing) > 0
          msg := get_message(parameters).message
        }

The crd section defines the schema for the constraint parameters. The rego block contains the policy logic. The violation rule produces a message when a required label is missing.

Creating Constraints

Once the template exists, you can create a Constraint that references it. The constraint specifies match criteria (which resources to evaluate) and the parameters.

Example: require namespaces with the label owner set to any value.

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
  name: ns-require-owner-label
spec:
  match:
    kinds:
      - apiGroups: [""]
        kinds: ["Namespace"]
    namespaces: [] # apply to all namespaces
  parameters:
    labels: ["owner"]

To target specific namespaces, use excludedNamespaces or namespaces lists in match.

Dry-Run Constraints

Gatekeeper supports an enforcementAction field (set via spec.enforcementAction). Valid values: deny (default), dryrun. A dryrun constraint logs violations but does not block admission. This is perfect for testing policies before full enforcement.

spec:
  enforcementAction: dryrun
  match: ...
  parameters: ...

Audit and Violations

Gatekeeper’s audit functionality periodically scans existing resources and records violations in the constraint’s status field. View violations with:

kubectl get constraints -A -o json | jq '.items[].status.violations'

Or use the dedicated command (if gatekeeper CLI installed). The audit interval can be adjusted via Helm value auditInterval.

Best Practices

• Start with dryrun: Deploy constraints in dryrun mode first to identify violations without disrupting users. Then switch to deny after confirming correctness.
• Use descriptive template names and annotations: Help operators understand what the policy does.
• Parameterize policies: Keep templates generic; use parameters for flexibility (e.g., allowed registries, required labels). Avoid hardcoding values in Rego.
• Leverage the audit log: Regularly monitor violations to track compliance drift.
• Exclude system namespaces: Prevent accidental denial of Kubernetes system components by excluding kube-system, gatekeeper-system, etc.
• Version control policies: Store templates and constraints in Git for audit trails and CI/CD integration.
• Test policies with OPA tools: Use opa test or the Gatekeeper gator CLI to validate Rego logic before deployment.
• Monitor Gatekeeper itself: Ensure the controller is healthy; set up alerts for audit failures or high denial rates.

Conclusion

Gatekeeper transforms Kubernetes governance into a transparent, code-driven process. By defining Constraint Templates and Constraints, platform teams can enforce everything from labeling requirements to container security standards without handcrafting admission webhooks. The combination of admission-time enforcement and periodic auditing ensures both preventive and detective controls. Adopting best practices like dry-run testing, parameterization, and Git-based policy management will help you build a robust, scalable governance framework that evolves with your clusters. Start with simple label requirements, expand to image policies, and gradually secure your entire fleet with confidence.