OPA gatekeeper is an open source, general-purpose policy engine that enables unified, context-aware policy enforcement.

Gatekeeper is a validating webhook that enforces CRD-based policies executed by Open Policy Agent. Policies are defined in a language called rego. Incoming requests that try to create or alter a resource that violates any of these policies will be rejected.

In addition to admission, Gatekeeper offers audit functionality, which allows administrators to see which resources are currently violating any given policy.

Deployment

The gatekeeper webhook and audit services exist in separate charms, you should deploy both of them. First you need to make sure that you have a Charmed Kubernetes environment set up and running. See the quickstart if you haven't. The gatekeeper-audit charm requires storage so make sure your Juju model has a registered storage-pool.

Next, create a new Kubernetes model:

juju add-model gatekeeper-system k8s-cloud

Then you can deploy the Gatekeeper charms:

juju deploy ch:gatekeeper-controller-manager
juju deploy ch:gatekeeper-audit

Using RBAC

If using RBAC, you must deploy the charms using the --trust flag as the charm needs permissions in order to create the necessary resources:

juju deploy --trust ch:gatekeeper-controller-manager
juju deploy --trust ch:gatekeeper-audit

Policies

Policies are defined as ConstraintTemplate CRDs in a language called rego. Constraints are then used to inform Gatekeeper that the admin wants a ConstraintTemplate to be enforced, and how.

To get a list of the constraints run:

kubectl get constraints

Or with the juju command:

juju run {unit_name} -m {model_name} list-violations

And then to get the violations for a specific constraint run:

juju run {unit_name} -m {model_name} get-violation constraint-template={constraint_template} constraint={constraint}

Configuration

Not much needs to be configured when running OPA gatekeeper. All configurations available are related to optimising the auditting:

audit-chunk-size:
  default: 500
  description: |
    Lower chunk size can reduce memory consumption of the auditing Pod but
    can increase the number requests to the Kubernetes API server.
audit-interval:
  default: 60
  description: Interval between the audits, to disable the interval set `audit-interval=0`
constraint-violations-limit:
  default: 20
  description: |
    The number of violations that will be reported, If the number of current violations
    is greater than this cap, the excess violations will not be reported but they
    will be included in the totalViolations count

Metrics

Both charms provide out of the box integration with the prometheus-k8s and the grafana-agent-k8s charms.

If you have those two charms deployed, you can integrate them with gatekeeper simply by running:

juju integrate grafana-agent-k8s gatekeeper-controller-manager
juju integrate grafana-agent-k8s:send-remote-write prometheus-k8s:receive-remote-write

This will provide you with metrics such as how many requests were denied, how many were processed, how many violations exist in the cluster, etc.

Reconciliation

The gatekeeper charms manage the same Kubernetes resources(roles, crds, etc.). If for some reason you wish to delete one of the two charms while keeping the other you should be very careful, as it will cause all of the resources to be deleted.

In that scenario you will need to reconcile (recreate) the resources by running:

juju run {unit_name} -m {model_name} reconcile-resources

Test the Gatekeeper charm

To test the gatekeeper charms you can try applying the test policy available on the charms' repository:

kubectl apply -f https://raw.githubusercontent.com/charmed-kubernetes/opa-gatekeeper-operators/main/docs/policy-example.yaml
kubectl apply -f https://raw.githubusercontent.com/charmed-kubernetes/opa-gatekeeper-operators/main/docs/policy-spec-example.yaml

This policy will require all namespaces to have the label gatekeeper=True, creating a new ns without that should fail:

kubectl create ns test

...should return...

Error from server (Forbidden): admission webhook "validation.gatekeeper.sh" denied the request: [ns-must-have-gk] you must provide labels: {"gatekeeper"}

After a while you should also be able to see violations of the policy from the existing resources. For example:

kubectl get constraints

... will return something similar to:

NAME              ENFORCEMENT-ACTION   TOTAL-VIOLATIONS
ns-must-have-gk                                6

Useful links

• Gatekeeper Documentation
• OPA Documentation
• Rego Documentation
• Gatekeeper Audit Charm
• Gatekeeper Webhook Charm