README.md

OPA Gatekeeper Operator

Operator for OPA Gatekeeper

Design

Please see the Gatekeeper Operator design document located at https://docs.google.com/document/d/1Nxw4Agq6nJrPL24fJPiTXtjtLQRsLJtHo9x5urwYB_I/edit?usp=sharing for some background information.

Installation

To install the Gatekeeper Operator, you can either run it outside the cluster, for faster iteration during development, or inside the cluster.

But first we require installing the Operator CRD:

make install

Then proceed to the installation method you prefer below.

Note: By default, docker is used to build and push images in Makefile. To use podman instead, set DOCKER=podman when calling make.

Outside the Cluster

If you would like to run the Gatekeeper Operator outside the cluster, the operator will use the default namespace to deploy Gatekeeper. If instead you would like to have the operator deploy Gatekeeper to a different namespace, then set the NAMESPACE environment variable. To do that just execute:

make run NAMESPACE=<namespace>

Inside the Cluster

If you would like to run the Operator inside the cluster, you'll need to build a container image. You can use a local private registry, or host it on a public registry service like quay.io.

1. Build your image:

   make docker-build IMG=<registry>/<imagename>:<tag>

2. Push the image:

   make docker-push IMG=<registry>/<imagename>:<tag>

3. Deploy the Operator:

   make deploy IMG=<registry>/<imagename>:<tag>

You can also specify in which namespace you want the operator to be deployed to by providing the NAMESPACE variable. If not provided the default namespace will be gatekeeper-system.

make deploy IMG=<registry>/<imagename>:tag NAMESPACE=mygatekeeper

Deploy Operator using OLM

If you would like to deploy Operator using OLM, you'll need to build and push the bundle image and index image. You need to host the images on a public registry service like quay.io.

1. Build your bundle image

   make bundle-build REPO=<registry>

2. Push the bundle image

   make docker-push IMG=<bundle image name>

3. Build the index image

   This make target will install opm if it is not already installed. If you would like to install it in your PATH manually instead, get it from here.

   make bundle-index-build REPO=<registry>

4. Push the index image

   make docker-push IMG=<index image name>

5. Create the CatalogSource/OperatorGroup/Subscription

   ---
   apiVersion: operators.coreos.com/v1alpha1
   kind: CatalogSource
   metadata:
     name: gatekeeper-operator
     namespace: gatekeeper-system
   spec:
     displayName: Gatekeeper Operator Upstream
     image: <index image name>
     publisher: github.com/stolostron/gatekeeper-operator
     sourceType: grpc
   ---
   apiVersion: operators.coreos.com/v1
   kind: OperatorGroup
   metadata:
     name: gatekeeper-operator
     namespace: gatekeeper-system
   ---
   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: gatekeeper-operator-sub
     namespace: gatekeeper-system
   spec:
     name: gatekeeper-operator
     channel: alpha
     source: gatekeeper-operator
     sourceNamespace: gatekeeper-system

Usage

Before using Gatekeeper you have to create a gatekeeper resource that will be consumed by the operator and create all the necessary resources for you.

Here you can find an example of a gatekeeper resource definition:

apiVersion: operator.gatekeeper.sh/v1alpha1
kind: Gatekeeper
metadata:
  name: gatekeeper
spec:
  # Add fields here
  audit:
    replicas: 1
    logLevel: ERROR

If nothing is defined in the spec, the default values will be used. In the example above the number of replicas for the audit pod is set to 1 and the logLevel to ERROR where the default is INFO.

The default behaviour for the ValidatingWebhookConfiguration is ENABLED, that means that it will be created. To disable the ValidatingWebhookConfiguration deployment, set the validatingWebhook spec property to DISABLED.

In order to create an instance of gatekeeper in the specified namespace you can start from one of the sample configurations.

kubectl create -f config/samples/operator_v1alpha1_gatekeeper.yaml

Add Default Exempt Namespaces

Go to controllers/config_helper.go. Update spec.match[].exemptNamespaces in the getDefaultConfig function.

// Default config data
	config := &v1alpha1.Config{
		ObjectMeta: metav1.ObjectMeta{
			Namespace: namespace,
			Name:      "config",
		},
		Spec: v1alpha1.ConfigSpec{
			Match: []v1alpha1.MatchEntry{
				{
					ExcludedNamespaces: []wildcard.Wildcard{
						"kube-*", "multicluster-engine",
						"hypershift", "hive", "rhacs-operator", "open-cluster-*", "openshift-*"
					},
					Processes: []string{
						 "webhook",
					},
				},
			},
		},
	}