Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 5. Gatekeeper operator overview

The Gatekeeper operator installs Gatekeeper, which is a validating webhook with auditing capabilities. Install the Gatekeeper operator on a Red Hat OpenShift Container Platform cluster from the Operator Lifecycle Manager operator catalog. With Red Hat Advanced Cluster Management for Kubernetes, you can install Gatekeeper on your hub cluster by using the Gatekeeper operator policy. After you install Gatekeeper, use it for the following benefits:

  • Deploy and check Gatekeeper ConstraintTemplates and constraints on managed clusters by using the Red Hat Advanced Cluster Management policy integration.
  • Enforce Kubernetes custom resource definition-based policies that run with your Open Policy Agent (OPA).
  • Evaluate Kubernetes resource compliance requests for the Kubernetes API by using the Gatekeeper constraints.
  • Use OPA as the policy engine and use Rego as the policy language.

Prerequisite: You need a Red Hat Advanced Cluster Management for Kubernetes or Red Hat OpenShift Container Platform Plus subscription to install Gatekeeper and apply Gatekeeper policies to your cluster.

To learn more about using the Gatekeeper operator, see the following resources:

5.1. General support
Copy link

To understand the support you receive from the Gatekeeper operator, see the following list:

  • Supports current version of the Gatekeeper operator, preceding versions, and all z-stream releases of those versions.
  • Receive maintenance support and relevant security vulnerability fixes for preceding and current versions.
  • Support for all Red Hat OpenShift Container Platform versions that receive standard support. Note: The Gatekeeper operator is not supported on end-of-life OpenShift Container Platform versions or versions that receive extended support.

To view the release notes for the Gatekeeper operator, see gatekeeper-operator-bundle.

5.2. Operator channels
Copy link

With the Gatekeeper operator, you have access to two types of channels to help you make upgrades. These channels are the stable channel and the y-stream version channel.

With the stable channel, you can access the latest available version, whether it is an x-stream, y-stream, or z-stream. The stable channel includes the latest version of the latest y-stream channel.

With the y-stream version channel, you can access all the z-stream versions for a particular y-stream.

5.3. Configuring the Gatekeeper operator
Copy link

Install the Gatekeeper operator from the Operator Lifecycle Manager catalog to install Gatekeeper on your cluster. With Red Hat Advanced Cluster Management you can use a policy to install the Gatekeeper operator by using the governance framework. After you install the Gatekeeper operator, configure the Gatekeeper operator custom resource to install Gatekeeper.

5.3.1. Prerequisites
Copy link

  • Required access: Cluster administrator.
  • Understand how to use the Operator Lifecycle Manager (OLM) and the OperatorHub by completing the Adding Operators to a cluster and the Additional resources section in the OpenShift Container Platform documentation.

5.3.2. Gatekeeper custom resource sample
Copy link

The Gatekeeper operator custom resource tells the Gatekeeper operator to start the Gatekeeper installation on the cluster. To install Gatekeeper, use the following sample YAML, which includes sample and default values: 

apiVersion: operator.gatekeeper.sh/v1alpha1
kind: Gatekeeper
metadata:
  name: gatekeeper
spec:
  audit:
    replicas: 1
    auditEventsInvolvedNamespace: Enabled
1 

    logLevel: DEBUG
    auditInterval: 10s
    constraintViolationLimit: 55
    auditFromCache: Enabled
    auditChunkSize: 66
    emitAuditEvents: Enabled
    containerArguments:
2 

    - name: ""
      value: ""
    resources:
      limits:
        cpu: 500m
        memory: 150Mi
      requests:
        cpu: 500m
        memory: 130Mi
  validatingWebhook: Enabled
  mutatingWebhook: Enabled
  webhook:
    replicas: 3
    emitAdmissionEvents: Enabled
    admissionEventsInvolvedNamespace: Enabled
3 

    disabledBuiltins:
     - http.send
    operations:
4 

     - "CREATE"
     - "UPDATE"
     - "CONNECT"
    failurePolicy: Fail
    containerArguments:
5 

    - name: ""
      value: ""
    resources:
      limits:
        cpu: 480m
        memory: 140Mi
      requests:
        cpu: 400m
        memory: 120Mi
  nodeSelector:
    region: "EMEA"
  affinity:
    podAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchLabels:
              auditKey: "auditValue"
          topologyKey: topology.kubernetes.io/zone
  tolerations:
    - key: "Example"
      operator: "Exists"
      effect: "NoSchedule"
  podAnnotations:
    some-annotation: "this is a test"
    other-annotation: "another test"
  config:
6 

    matches:
      - excludedNamespaces: ["test-*", "my-namespace"]
        processes: ["*"]
    disableDefaultMatches: false
7
Copy to Clipboard Toggle word wrap
1
For version 3.14 and later, enable the auditEventsInvolvedNamespace parameter to manage the namespace audit event you want to create. When you enable this parameter, the Gatekeeper controller deployment runs with the following argument: --audit-events-involved-namespace=true.
3
For version 3.14 and later, enable the admissionEventsInvolvedNamespace parameter to manage the namespace admission event you want to create. When you enable this parameter, the Gatekeeper controller deployment runs with the following argument: --admission-events-involved-namespace=true.
4
For version 3.14 and later, to manage your webhook operations, use the following values for the operations parameter, "CREATE", "UPDATE", "CONNECT", and "DELETE".
2 5
For version 3.17 and later, specify containerArguments by providing a list of argument names and values to pass to the container. Omit leading dashes from the argument name. An omitted value is treated as true. Arguments that you provide are ignored if the argument is set previously by the operator or configurations from other fields. See the following list of flags that are deny-listed and are not currently supported:
  • port
  • prometheus-port
  • health-addr
  • validating-webhook-configuration-name
  • mutating-webhook-configuration-name
  • disable-cert-rotation
  • client-cert-name
  • tls-min-version
6
Use the config section to exclude namespaces from certain processes for all constraints on your hub cluster.
7
The disableDefaultMatches parameter is a boolean parameter that disables appending the default exempt namespaces provided by the Gatekeeper operator. The default exempt namespaces are OpenShift Container Platform or Kubernetes system namespaces. By default, this parameter is set to false to allow the default namespaces to be appended.

5.3.3. Configuring auditFromCache for sync details
Copy link

For versions 3.14 or later, the Gatekeeper operator exposes a setting in the Gatekeeper operator custom resource for the audit configuration with the auditFromCache parameter, which is disabled by default. Configure the auditFromCache parameter to collect resources from constraints.

When you set the auditFromCache parameter to Automatic, the Gatekeeper operator collects resources from constraints and inserts those resources into your Gatekeeper Config resource. If the resource does not exist, the Gatekeeper operator creates the Config resource.

If you set the auditFromCache parameter to Enabled, you need to manually set the Gatekeeper Config resource with the objects to sync to the cache. For more information, see Configuring Audit in the Gatekeeper documentation.

To configure the auditFromCache parameter for resource collection from constraints, complete the following steps:

  1. Set auditFromCache to Automatic in the Gatekeeper resource. See the following example: 

    apiVersion: operator.gatekeeper.sh/v1alpha1
kind: Gatekeeper
metadata:
  name: gatekeeper
spec:
  audit:
    replicas: 2
    logLevel: DEBUG
    auditFromCache: Automatic
    Copy to Clipboard Toggle word wrap

  2. To verify that the resources are added to your Config resource, view that the syncOnly parameter section is added. Run the following command: 

    oc get configs.config.gatekeeper.sh config -n openshift-gatekeeper-system
    Copy to Clipboard Toggle word wrap

    Your Config resource might resemble the following example: 

    apiVersion: config.gatekeeper.sh/v1alpha1
kind: Config
metadata:
 name: config
 namespace: "openshift-gatekeeper-system"
spec:
 sync:
   syncOnly:
   - group: ""
     version: "v1"
     kind: "Namespace"
   - group: ""
     version: "v1"
     kind: "Pod"
    Copy to Clipboard Toggle word wrap

Optional: You can view the explanation of the auditFromCache setting from the description of the Gatekeeper operator custom resource by running the following command: 

oc explain gatekeeper.spec.audit.auditFromCache
Copy to Clipboard Toggle word wrap

5.3.4. Additional resources
Copy link

Use the Red Hat Advanced Cluster Management policy to install the Gatekeeper operator and Gatekeeper on a managed cluster.

Required access: Cluster administrator

To create, view, and update your Gatekeeper operator installation policies, complete the following sections:

To install the Gatekeeper operator policy, use the configuration policy controller. During the install, the operator group and subscription pull the Gatekeeper operator to install it on your managed cluster. Then, the policy creates a Gatekeeper custom resource to configure Gatekeeper.

The Red Hat Advanced Cluster Management configuration policy controller checks the Gatekeeper operator policy and supports the enforce remediation action. When you set the controller to enforce it automatically creates the Gatekeeper operator objects on the managed cluster.

When you create a Gatekeeper policy from the console, you must set your remediation enforce to install Gatekeeper.

5.4.2.1. Viewing the Gatekeeper operator policy
Copy link

To view your Gatekeeper operator policy and its status from the console, complete the following steps:

  1. Select the policy-gatekeeper-operator policy to view more details.
  2. Select the Clusters tab to view the policy violations.

You can upgrade the versions for Gatekeeper and the Gatekeeper operator. When you install the Gatekeeper operator with the Gatekeeper operator policy, notice the value for upgradeApproval. The operator upgrades automatically when you set upgradeApproval to Automatic.

If you set upgradeApproval to Manual, you must manually approve the upgrade for each cluster where the Gatekeeper operator is installed.

5.4.4. Disabling Gatekeeper operator policy
Copy link

To disable your policy-gatekeeper-operator policy, select the Disable option from the Actions menu in the console, or set spec.disabled: true from the CLI.

5.4.5. Deleting Gatekeeper operator policy
Copy link

To delete your Gatekeeper operator policy from your CLI, complete the following steps:

  1. Delete Gatekeeper operator policy by running the following command: 

    oc delete policies.policy.open-cluster-management.io <policy-gatekeeper-operator-name> -n <namespace>
    Copy to Clipboard Toggle word wrap

  2. Verify that you deleted your policy by running the following command: 

    oc get policies.policy.open-cluster-management.io <policy-gatekeeper-operator-name> -n <namespace>
    Copy to Clipboard Toggle word wrap

To delete your Gatekeeper operator policy from the console, click the Actions icon for the policy-gatekeeper-operator policy and select Delete.

To uninstall Gatekeeper policy, complete the steps in the following sections:

5.4.6.1. Removing Gatekeeper constraints
Copy link

To remove the Gatekeeper constraint and ConstraintTemplate from your managed cluster, complete the following steps:

  1. Edit your Gatekeeper constraint or ConstraintTemplate policy.
  2. Locate the template that you used to create the Gatekeeper Constraint and ConstraintTemplate.
  3. Delete the entries from the list of templates. (Or delete the policy if they’re the only templates.)
  4. Save and apply the policy.

Note: The constraint and ConstraintTemplate are provided directly in the policy-templates instead of within a ConfigurationPolicy.

5.4.6.2. Removing Gatekeeper instance
Copy link

To remove the Gatekeeper instance from your managed cluster, complete the following steps:

  1. Edit your Gatekeeper operator policy.
  2. Locate the ConfigurationPolicy template that you used to create the Gatekeeper operator custom resource.
  3. Change the value for complianceType of the ConfigurationPolicy template to mustnothave. Changing the value deletes the Gatekeeper operator custom resource, signaling to the Gatekeeper operator to clean up the Gatekeeper deployment.

5.4.6.3. Removing Gatekeeper operator
Copy link

To remove the Gatekeeper operator from your managed cluster, complete the following steps:

  1. Edit your Gatekeeper operator policy.
  2. Locate the OperatorPolicy template that you used to create the Subscription CR.
  3. Change the value for complianceType of the OperatorPolicy template to mustnothave.

5.4.7. Additional resources
Copy link

For more details, see the following resources:

To create Gatekeeper policies, use ConstraintTemplates and constraints. Add templates and constraints to the policy-templates of a Policy resource. View the following YAML examples that use Gatekeeper constraints in Red Hat Advanced Cluster Management policies:

  • ConstraintTemplates and constraints: Use the Gatekeeper integration feature by using Red Hat Advanced Cluster Management policies for multicluster distribution of Gatekeeper constraints and Gatekeeper audit results aggregation on the hub cluster. The following example defines a Gatekeeper ConstraintTemplate and constraint (K8sRequiredLabels) to ensure the gatekeeper label is set on all namespaces: 

    apiVersion: policy.open-cluster-management.io/v1
kind: Policy
metadata:
  name: require-gatekeeper-labels-on-ns
spec:
  remediationAction: inform
    1 
    
  disabled: false
  policy-templates:
    - objectDefinition:
        apiVersion: templates.gatekeeper.sh/v1beta1
        kind: ConstraintTemplate
        metadata:
          name: k8srequiredlabels
          annotations:
            policy.open-cluster-management.io/severity: low
    2 
    
        spec:
          crd:
            spec:
              names:
                kind: K8sRequiredLabels
              validation:
                openAPIV3Schema:
                  properties:
                    labels:
                      type: array
                      items: string
          targets:
            - target: admission.k8s.gatekeeper.sh
              rego: |
                package k8srequiredlabels
                violation[{"msg": msg, "details": {"missing_labels": missing}}] {
                  provided := {label | input.review.object.metadata.labels[label]}
                  required := {label | label := input.parameters.labels[_]}
                  missing := required - provided
                  count(missing) > 0
                  msg := sprintf("you must provide labels: %v", [missing])
                }
    - objectDefinition:
        apiVersion: constraints.gatekeeper.sh/v1beta1
        kind: K8sRequiredLabels
        metadata:
          name: ns-must-have-gk
          annotations:
            policy.open-cluster-management.io/severity: low
    3 
    
        spec:
          enforcementAction: dryrun
          match:
            kinds:
              - apiGroups: [""]
                kinds: ["Namespace"]
          parameters:
            labels: ["gatekeeper"]
    Copy to Clipboard Toggle word wrap
    1
    Since the remediationAction is set to inform, the enforcementAction field of the Gatekeeper constraint is overridden to warn. This means that Gatekeeper detects and warns you about creating or updating a namespace that is missing the gatekeeper label. If the policy remediationAction is set to enforce, the Gatekeeper constraint enforcementAction field is overridden to deny. In this context, this configuration prevents any user from creating or updating a namespace that is missing the gatekeeper label.
    2 3
    Optional: Set a severity value for the policy.open-cluster-management.io/severity annotation for each Gatekeeper constraint or constraint template. Valid values are the same as for other Red Hat Advanced Cluster Management policy types: low, medium, high, or critical.

    With the previous policy, you might receive the following policy status message: warn - you must provide labels: {"gatekeeper"} (on Namespace default); warn - you must provide labels: {"gatekeeper"} (on Namespace gatekeeper-system). When you delete Gatekeeper constraints or ConstraintTemplates from a policy, the constraints and ConstraintTemplates are also deleted from your managed cluster.

    To view the Gatekeeper audit results for a specific managed cluster from the console, go to to the policy template Results page. If search is enabled, view the YAML of the Kubernetes objects that failed the audit.

    Notes:

    • The Related resources section is only available when Gatekeeper generates audit results.
    • The Gatekeeper audit runs every minute by default. Audit results are sent back to the hub cluster to be viewed in the Red Hat Advanced Cluster Management policy status of the managed cluster.

  • policy-gatekeeper-admission: Use the policy-gatekeeper-admission configuration policy within a Red Hat Advanced Cluster Management policy to check for Kubernetes API requests denied by the Gatekeeper admission webhook. View the following example: 

    apiVersion: policy.open-cluster-management.io/v1
kind: ConfigurationPolicy
metadata:
  name: policy-gatekeeper-admission
spec:
  remediationAction: inform
    1 
    
  severity: low
  object-templates:
    - complianceType: mustnothave
      objectDefinition:
        apiVersion: v1
        kind: Event
        metadata:
          namespace: openshift-gatekeeper-system
    2 
    
          annotations:
            constraint_action: deny
            constraint_kind: K8sRequiredLabels
            constraint_name: ns-must-have-gk
            event_type: violation
    Copy to Clipboard Toggle word wrap
    1
    The ConfigurationPolicy remediationAction parameter is overwritten by remediationAction in the parent policy.
    2
    Set to the actual namespace where Gatekeeper is running if it is different.

5.5.1. Additional resources
Copy link

For more details, see the following resources:

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat