https://github.com/kubewarden/gatekeeper-policy-template
A template repository to quickly port a Gatekeeper policy to Kubewarden
https://github.com/kubewarden/gatekeeper-policy-template
gatekeeper gatekeeper-policies gatekeeper-v2 hacktoberfest kubernetes kubernetes-security kubewarden-policy-template policy-as-code rego webassembly
Last synced: 11 months ago
JSON representation
A template repository to quickly port a Gatekeeper policy to Kubewarden
- Host: GitHub
- URL: https://github.com/kubewarden/gatekeeper-policy-template
- Owner: kubewarden
- Created: 2021-09-22T14:01:27.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-08-11T10:28:44.000Z (11 months ago)
- Last Synced: 2025-08-11T12:24:47.286Z (11 months ago)
- Topics: gatekeeper, gatekeeper-policies, gatekeeper-v2, hacktoberfest, kubernetes, kubernetes-security, kubewarden-policy-template, policy-as-code, rego, webassembly
- Language: Makefile
- Homepage: https://kubewarden.io
- Size: 117 KB
- Stars: 1
- Watchers: 5
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](https://github.com/kubewarden/community/blob/main/REPOSITORIES.md#stable)
# 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](https://docs.kubewarden.io)
for more information about writing policies.
## Requirements
To fully use this template, you'll need the following tools:
- [opa](https://github.com/open-policy-agent/opa/releases): tool
to build the code into wasm. The version expected is `v1.0.0` or later
- [kwctl](https://github.com/kubewarden/kwctl/releases): tool you use to
prepare and run Kubewarden web assembly module
- [bats](https://github.com/bats-core/bats-core): 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.
1. The policy must be compiled into a WebAssembly module using the `opa` cli tool.
1. 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](https://github.com/open-policy-agent/opa/releases/tag/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](https://github.com/open-policy-agent/gatekeeper/releases/tag/v3.19.0).
- 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](https://open-policy-agent.github.io/gatekeeper/website/docs/constrainttemplates/#enable-opa-rego-v1-syntax-in-constrainttemplates)
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:
```shell
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](https://github.com/bats-core/bats-core):
the Bash Automated Testing System. The WebAssembly runtime is provided by the
[kwctl](https://github.com/kubewarden/kwctl) cli tool.
The end-to-end tests are defined inside of the `e2e.bats` file and can
be run via this command:
```shell
make e2e-tests
```
## Automation
This project contains [GitHub Actions](https://docs.github.com/en/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
`:` tag.