Chapter 3. 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: General support Operator channels Configuring the Gatekeeper operator Managing the Gatekeeper operator installation policies Integrating Gatekeeper constraints and constraint templates 3.1. General support 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 . 3.2. Operator channels 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 . 3.3. Configuring the Gatekeeper operator 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. 3.3.1. Prerequisites 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 . 3.3.2. Gatekeeper custom resource sample 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 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. 3.3.3. Configuring auditFromCache for sync details 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: 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 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 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" 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 3.4. Managing the Gatekeeper operator installation policies 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: Installing Gatekeeper using a Gatekeeper operator policy Creating a Gatekeeper policy from the console Upgrading Gatekeeper and the Gatekeeper operator Disabling Gatekeeper operator policy Deleting Gatekeeper operator policy Uninstalling Gatekeeper constraints, Gatekeeper instance, and Gatekeeper operator policy 3.4.1. Installing Gatekeeper using a Gatekeeper operator policy 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. 3.4.2. Creating a Gatekeeper policy from the console When you create a Gatekeeper policy from the console, you must set your remediation enforce to install Gatekeeper. 3.4.2.1. Viewing the Gatekeeper operator policy To view your Gatekeeper operator policy and its status from the console, complete the following steps: Select the policy-gatekeeper-operator policy to view more details. Select the Clusters tab to view the policy violations. 3.4.3. Upgrading Gatekeeper and the Gatekeeper operator 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. 3.4.4. Disabling Gatekeeper operator policy 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. 3.4.5. Deleting Gatekeeper operator policy To delete your Gatekeeper operator policy from your CLI, complete the following steps: Delete Gatekeeper operator policy by running the following command: oc delete policies.policy.open-cluster-management.io <policy-gatekeeper-operator-name> -n <namespace> 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> To delete your Gatekeeper operator policy from the console, click the Actions icon for the policy-gatekeeper-operator policy and select Delete . 3.4.6. Uninstalling Gatekeeper constraints, Gatekeeper instance, and Gatekeeper operator policy To uninstall Gatekeeper policy, complete the steps in the following sections: Removing Gatekeeper constraints Removing Gatekeeper instance Removing Gatekeeper operator 3.4.6.1. Removing Gatekeeper constraints To remove the Gatekeeper constraint and ConstraintTemplate from your managed cluster, complete the following steps: Edit your Gatekeeper constraint or ConstraintTemplate policy. Locate the template that you used to create the Gatekeeper Constraint and ConstraintTemplate . Delete the entries from the list of templates. (Or delete the policy if they're the only templates.) Save and apply the policy. Note: The constraint and ConstraintTemplate are provided directly in the policy-templates instead of within a ConfigurationPolicy . 3.4.6.2. Removing Gatekeeper instance To remove the Gatekeeper instance from your managed cluster, complete the following steps: Edit your Gatekeeper operator policy. Locate the ConfigurationPolicy template that you used to create the Gatekeeper operator custom resource. 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. 3.4.6.3. Removing Gatekeeper operator To remove the Gatekeeper operator from your managed cluster, complete the following steps: Edit your Gatekeeper operator policy. Locate the OperatorPolicy template that you used to create the Subscription CR. Change the value for complianceType of the OperatorPolicy template to mustnothave . 3.4.7. Additional resources For more details, see the following resources: Integrating Gatekeeper constraints and constraint templates . Policy Gatekeeper . For an explanation of the optional parameters that can be used for the Gatekeeper operator policy, see Gatekeeper Helm Chart . 3.5. Integrating Gatekeeper constraints and constraint templates 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"] 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 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 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. 3.5.1. Additional resources For more details, see the following resources: policy-gatekeeper-operator.yaml What is OPA Gatekeeper?

Commands:
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
apiVersion: operator.gatekeeper.sh/v1alpha1 kind: Gatekeeper metadata: name: gatekeeper spec: audit: replicas: 2 logLevel: DEBUG auditFromCache: Automatic
get configs.config.gatekeeper.sh config -n openshift-gatekeeper-system
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"
explain gatekeeper.spec.audit.auditFromCache
delete policies.policy.open-cluster-management.io <policy-gatekeeper-operator-name> -n <namespace>
get policies.policy.open-cluster-management.io <policy-gatekeeper-operator-name> -n <namespace>
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"]
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