gatekeeper-policy-template

This is a template repository that can be used to easily convert an existing Rego policy targeting the Gatekeeper framework into a Kubewarden policy.

Don't forget to checkout Kubewarden's official documentation for more information about writing policies.

Requirements

To fully use this template, you'll need the following tools:

• opa: tool to build the code into wasm. The version expected is v1.0.0 or later
• kwctl: tool you use to prepare and run Kubewarden web assembly module
• bats: tool used to run end-to-end tests. If you decided to write such kind of tests

Introduction

Note well: the existing Rego code should not need to be rewritten.

These are the only requirements you have to fulfill:

1. The policy evaluation must return a violation response object. This is already a requirement for all the Gatekeeper policies.
2. The policy must be compiled into a WebAssembly module using the opa cli tool.
3. The policy must be annotated via kwctl annotate.

This template repository contains an example policy that can be used as foundation for your policies, plus all the automation needed to implement the 2nd and 3rd points.

Implementation details

The actual policy is defined inside of the policy.rego file. This file defines a violation object.

Rego Policy code and OPA v1.0.0 compatibility

With the release of OPA (Open Policy Agent) v1.0.0 in December 2024, a breaking change was introduced regarding Rego policy syntax.

Previously, if for all rule definitions and contains for multi-value rules were optional; now, they're mandatory. This change affects most older policies.

Here's a summary of what you need to know:

• OPA v1.0.0 Syntax: OPA v1.0.0 mandates the use of if for all rule definitions and contains for multi-value rules. Policies not adhering to this syntax will break.
• Backward Compatibility: If you need to build older policies that don't use the new v1.0.0 syntax, you must provide the --v0-compatible flag to the opa build command.
• Gatekeeper integration: Gatekeeper updated its OPA dependency to v1.0.0 in its v3.19.0 release.
• Rego version in Gatekeeper templates: Gatekeeper assumes v0 syntax is used unless the template explicitly specifies version: "v1" within the source field under code.engine: Rego.

Checkout this section of Gatekeeper's docs for more details about how v0 and v1 versions of Rego are handled.

What this means for you:

• If the Gatekeeper CR doesn't specify a Rego version, it implies v0 is going to be used. You must build the policy using the OPA_V0_COMPATIBLE=true make command.
• If the Gatekeeper CR explicitly specifies version: "v1", you must build the policy without any environment variable set.

Testing

The policy has some unit tests written using Rego, they can be found inside of the file policy_test.rego. The unit tests can be executed via the following command:

make test

The repository provides also a way to run end-to-end tests against the WebAssembly module produced by the compilation. These tests execute the policy using the WebAssembly runtime of Kubewarden.

The e2e tests are implemented using bats: the Bash Automated Testing System. The WebAssembly runtime is provided by the kwctl cli tool.

The end-to-end tests are defined inside of the e2e.bats file and can be run via this command:

make e2e-tests

Automation

This project contains GitHub Actions workflows.

They take care of the following automations:

• Execute the Rego test suite
• Build the Rego files into a single WebAssembly module
• Annotate the WebAssembly module with Kubewarden's metadata
• Execute end-to-end tests
• Push events on the main branch lead the:
  • Push the annotated WebAssembly module to the GitHub Container Registry using the :latest tag.
• The creation of git tags lead to:
  • Creation of the GitHub Release, holding the annotated WebAssembly module
  • Push the annotated WebAssembly module to the GitHub Container Registry using the :<git tag> tag.