gatekeeper-policy-manager

[GPM Release] [Helm Chart Release] [License]

Gatekeeper Policy Manager is a read-only web UI that shows the status of OPA Gatekeeper policies in a Kubernetes cluster.

The target Kubernetes cluster can be the same one where GPM runs, or a remote cluster that GPM connects to with a kubeconfig file. You can also run GPM locally on a client machine and connect to a remote cluster.

GPM lets you see in detail:

• Constraint Templates with their rego code.
• Constraints with their current status, violations, enforcement action, matches definitions, etc.
• Mutations defined and their details.
• Events emitted by OPA Gatekeeper (alpha feature).
• Gatekeeper Configuration custom resource values.

You can see some screenshots below ⤵.

Requirements

GPM needs OPA Gatekeeper in your cluster. It also needs some constraint templates and constraints. Without them, GPM has nothing to show.

[!TIP] You can deploy Gatekeeper to your cluster with the SIGHUP Distribution Policy Module (also open source).

Deploying GPM

Deploy using Kustomize

To deploy Gatekeeper Policy Manager to your cluster, apply the kustomization file with this command:

kubectl apply -k https://github.com/sighupio/gatekeeper-policy-manager

By default, this creates a deployment and a service named gatekeeper-policy-manager in the gatekeeper-system namespace. To configure more, see the kustomization.yaml file.

[!NOTE] GPM can run as a Pod in a Kubernetes cluster, or locally with a kubeconfig file. It autodetects the correct configuration.

If you did not configure an ingress, use port-forward to access the web UI:

kubectl -n gatekeeper-system port-forward  svc/gatekeeper-policy-manager 8080:80

Then open http://127.0.0.1:8080 in your browser.

Deploy using Helm

You can also deploy GPM with the Helm chart.

First create a values file, for example my-values.yaml, with your custom values for the release. See the chart's readme and the default values.yaml for more information.

From v2.1.0 the chart is published as an OCI artifact on quay.io, next to the container image. There is no helm repo add step any more. You need Helm 3.8 or later, which supports OCI registries. Then execute:

helm upgrade --install --namespace gatekeeper-system --set image.tag=v2.1.2 --values my-values.yaml gatekeeper-policy-manager oci://quay.io/sighup/charts/gatekeeper-policy-manager --version 0.20.2

[!IMPORTANT] Replace my-values.yaml with the path to your values file, and --version 0.20.2 with the chart version you want.

Running locally

You can also run GPM locally with Docker (or another container runtime) and a kubeconfig. If the kubeconfig file is at ~/.kube/config, run this command:

docker run -v ~/.kube/config:/home/nonroot/.kube/config -p 8080:8080 quay.io/sighup/gatekeeper-policy-manager:v2.1.2

Then open http://127.0.0.1:8080 in your browser.

You can also run the app binary directly. See the development section for more information.

Configuration

GPM is stateless. You configure it with environment variables. The most common ones are:

For more information, read these documents:

• Configuration: all the environment variables, subpath deployment, and events RBAC.
• Authentication: OIDC login, or an authenticating proxy such as Pomerium.
• RBAC-aligned views: show each person only what their Kubernetes account can read.
• Multi-cluster support: one GPM for more than one cluster, and AWS IAM authentication.

Screenshots

Development

GPM is written in Go. It uses the Echo framework and renders the UI on the server with the standard library's html/template, plus a small amount of Alpine.js for interactivity. There is no separate frontend build.

Alpine.js is vendored as static/ssr/alpine.min.js. Its version is pinned in package.json so Dependabot tracks it; after a bump, run mise run vendor-alpine to refresh the vendored file (the check-alpine-version task, part of mise run lint, fails if the two drift).

To develop GPM, run these commands:

# Install the dependencies
$ go mod download
# Run the development server
$ GPM_LOG_LEVEL=DEBUG go run .

[!TIP] A Kubernetes cluster with OPA Gatekeeper deployed helps you debug the application.

Contributing

Let us know if you use GPM and which features you want. Create an issue here on GitHub 💪🏻

To contribute, pick one of the open issues and work on it. It is better to tell us first on the issue.

When you are happy with your work, open a Pull Request.

We try to stick to conventional commits when writing commit messages.