gatekeeper component overview and release history - Container Service for Kubernetes

The gatekeeper add-on helps you manage and apply Open Policy Agent (OPA) policies in ACK clusters, including namespace label management. This topic describes gatekeeper functionality, usage instructions, and release notes. gatekeeper integrates OPA into ACK clusters to define and enforce admission policies with CRDs. Control resource creation by labels, resource types, namespaces, and other attributes. gatekeeper also manages namespace labels.

To use gatekeeper:

Install gatekeeper from the Add-ons page in the ACK console. See Manage components.
Create a constraint template to define policy logic in Rego.
Create a constraint to apply the template to specific namespaces or resource types.
Verify the constraint works as expected.

See Open Policy Agent.

How it works

Gatekeeper runs as an admission webhook. validation.gatekeeper.sh intercepts resource creation and update requests and evaluates them against active constraints.

The policy model has two layers:

ConstraintTemplate: defines policy logic in Rego and registers a new CRD kind.
Constraint: an instance of a ConstraintTemplate that specifies target resources and enforcement parameters.

See How to use Gatekeeper.

Enforce pod label policies

This example requires all pods in a namespace to carry a specific label. Both the template and constraint take about 10 seconds to initialize.

Prerequisites

Ensure that you have:

An ACK cluster with gatekeeper installed
kubectl configured to connect to the cluster

Create a namespace and label it

Create a test namespace with the label that the constraint matches:

kubectl create ns test-gatekeeper
kubectl label ns test-gatekeeper name=test-gatekeeper

Create a constraint template

This template registers a K8sRequiredLabels CRD and defines the policy logic in Rego:

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

        # A violation is triggered when required labels are missing from the resource.
        violation[{"msg": msg, "details": {"missing_labels": missing}}] {
          # Collect all labels on the incoming resource.
          provided := {label | input.review.object.metadata.labels[label]}
          # Collect all labels required by the constraint parameters.
          required := {label | label := input.parameters.labels[_]}
          # Compute the set of labels that are required but not provided.
          missing := required - provided
          count(missing) > 0
          msg := sprintf("you must provide labels: %v", [missing])
        }
EOF

Wait about 10 seconds for initialization.

Create a constraint

Apply the K8sRequiredLabels template to pods in namespaces labeled name=test-gatekeeper, requiring the gatekeeper-test-label label:

kubectl apply -f - <<EOF
apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
  name: pod-must-have-gatekeeper-test-label
spec:
  match:
    kinds:
      - apiGroups: [""]
        kinds: ["Pod"]
    namespaceSelector:
      matchExpressions:
      - key: name
        operator: In
        values: ["test-gatekeeper"]
  parameters:
    labels: ["gatekeeper-test-label"]
EOF

Wait about 10 seconds for activation.

Verify the constraint

Run these tests to verify the constraint.

Test 1: Pod without the required label is denied.

kubectl -n test-gatekeeper run test-deny --image=nginx --restart=Never

Expected output:

Error from server ([denied by pod-must-have-gatekeeper-test-label] you must provide labels: {"gatekeeper-test-label"}): admission webhook "validation.gatekeeper.sh" denied the request: [denied by pod-must-have-gatekeeper-test-label] you must provide labels: {"gatekeeper-test-label"}

Rejected: the test-gatekeeper namespace matches the selector, and the pod lacks gatekeeper-test-label.

Test 2: Pod with the required label is allowed.

kubectl -n test-gatekeeper run test-pass -l gatekeeper-test-label=pass --image=nginx --restart=Never

Expected output:

pod/test-pass created

Admitted: the pod carries gatekeeper-test-label.

Test 3: Pod in an unconstrained namespace is allowed.

kubectl -n default run test-deny --image=nginx --restart=Never

Expected output:

pod/test-deny created

The default namespace lacks the name=test-gatekeeper label, so the constraint does not apply.

Release notes

March 2025

Version	Image address	Release date	Description	Impact
v3.18.2.192-ge2860248-aliyun	registry-cn-hangzhou.ack.aliyuncs.com/acs/gatekeeper:v3.18.2.192-ge2860248-aliyun	2025-03-04	Updated OPA Gatekeeper to v3.18.2. Upgraded Go to 1.23.6 for stability.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

December 2024

Version	Image address	Release date	Description	Impact
v3.17.1.174-g6383c639-aliyun	registry-cn-hangzhou.ack.aliyuncs.com/acs/gatekeeper:v3.17.1.174-g6383c639-aliyun	2024-12-09	Updated OPA Gatekeeper to v3.17.1.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

September 2024

Version	Image address	Release date	Description	Impact
v3.16.3.158-g5e73c0ad-aliyun	registry-cn-hangzhou.ack.aliyuncs.com/acs/gatekeeper:v3.16.3.158-g5e73c0ad-aliyun	2024-09-25	Updated OPA Gatekeeper to v3.16.3.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

March 2024

Version	Image address	Release date	Description	Impact
v3.15.1.150-g29b8b2a8-aliyun	registry-cn-hangzhou.ack.aliyuncs.com/acs/gatekeeper:v3.15.1.150-g29b8b2a8-aliyun	2024-03-27	Updated OPA Gatekeeper to v3.15.1.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

October 2023

Version	Image address	Release date	Description	Impact
v3.12.0.138-g1ee37e37-aliyun	registry-cn-hangzhou.ack.aliyuncs.com/acs/gatekeeper:v3.12.0.138-g1ee37e37-aliyun	2023-10-09	Updated OPA Gatekeeper to v3.12.0. Added policy support for Service deletion events.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

April 2023

Version	Image address	Release date	Description	Impact
v3.10.0.130-g0e79597d-aliyun	registry.cn-hangzhou.aliyuncs.com/acs/gatekeeper:v3.10.0.130-g0e79597d-aliyun	2023-04-18	Updated OPA Gatekeeper to v3.10.0. Data replication is disabled by default. Enable it on the Add-ons page. See Replicating Data. Added policy support for namespace deletion events. Added Kubernetes 1.26 support.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

June 2022

Version	Image address	Release date	Description	Impact
v3.8.1.113-geb7947ef-aliyun	registry.cn-hangzhou.aliyuncs.com/acs/gatekeeper:v3.8.1.113-geb7947ef-aliyun	2022-06-08	Updated OPA Gatekeeper to v3.8.1. Auditing pods are disabled by default. Enable them on the Add-ons page. CPU, memory, and replica count are configurable on the Add-ons page.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

April 2022

Version	Image address	Release date	Description	Impact
v3.7.1.93-gaf375989-aliyun	registry.cn-hangzhou.aliyuncs.com/acs/gatekeeper:v3.7.1.93-gaf375989-aliyun	2022-04-02	Mutation is disabled by default. Enable it on the Add-ons page. See Mutation.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

February 2022

Version	Image address	Release date	Description	Impact
v3.7.0.84-gf5fd3ffd-aliyun	registry.cn-hangzhou.aliyuncs.com/acs/gatekeeper:v3.7.0.84-gf5fd3ffd-aliyun	2022-02-15	Optimized performance. Fixed abnormal CPU utilization in extreme cases.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

January 2022

Version	Image address	Release date	Description	Impact
v3.7.0.82-gafe4391b-aliyun	registry.cn-hangzhou.aliyuncs.com/acs/gatekeeper:v3.7.0.82-gafe4391b-aliyun	2022-01-14	Updated OPA Gatekeeper to v3.7.0. Added ARM64 support.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

September 2021

Version	Image address	Release date	Description	Impact
v3.6.0.62-g156146d-aliyun	registry.cn-hangzhou.aliyuncs.com/acs/gatekeeper:v3.6.0.62-g156146d-aliyun	2021-09-20	gatekeeper 3.6.0.62 and later requires Kubernetes 1.16.9 or later. Updated OPA Gatekeeper to v3.6.0.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

March 2021

Version	Image address	Release date	Description	Impact
v3.3.0.24-8e68abc-aliyun	registry.cn-hangzhou.aliyuncs.com/acs/gatekeeper:v3.3.0.24-8e68abc-aliyun	2021-03-16	Added support for registered clusters. Updated OPA Gatekeeper to 3.3.0.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.

August 2020

Version	Image address	Release date	Description	Impact
v3.1.0.11-24bab09-aliyun	registry.cn-hangzhou.aliyuncs.com/acs/gatekeeper:v3.1.0.11-24bab09-aliyun	2020-08-20	Updated OPA Gatekeeper to 3.1.0-beta.12.	If exceptions occur during the component update, changes to cluster resources may fail. Perform the update during off-peak hours.