feat: Gatekeeper policy migration guide. #627
Conversation
Adds a how to guide showing how users can migrate a Gatekeeper policy into Kubewarden policy. Signed-off-by: José Guilherme Vanz <[email protected]>
✅ Deploy Preview for docs-kubewarden-io ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Looks good, but I think we should come up with a better approach (something automated).
I would try to clean this page as much as possible and publish that. This is better than nothing and, most important of all, provides clear instructions to whoever is going to create some automation around that.
docs/howtos/gatekeeper-migration.md
Outdated
| [catalog](https://artifacthub.io/packages/search?kind=13). Some of the | ||
| [policies](https://github.com/kubewarden/rego-policies-library) are public | ||
| available OPA and Gatekeeper policies migrated migrated to Kubewarden |
There was a problem hiding this comment.
| [catalog](https://artifacthub.io/packages/search?kind=13). Some of the | |
| [policies](https://github.com/kubewarden/rego-policies-library) are public | |
| available OPA and Gatekeeper policies migrated migrated to Kubewarden | |
| [catalog](https://artifacthub.io/packages/search?kind=13). |
I think that's enough, all the policies are already exposed in a nice way by ArtifactHub
There was a problem hiding this comment.
I've added the link to the repository to give users examples on how they can migrate their gatekeeper policies. I think is always nice to see other examples.
docs/howtos/gatekeeper-migration.md
Outdated
| Attempting to build the code after this change might reveal new compilation errors: | ||
|
|
||
| ``` | ||
| opa build -t wasm -e policy/violation -o bundle.tar.gz policy.rego | ||
| error: load error: 2 errors occurred during loading: | ||
| policy.rego:3: rego_parse_error: `if` keyword is required before rule body | ||
| policy.rego:3: rego_parse_error: `contains` keyword is required for partial set rules | ||
| make: *** [Makefile:4: policy.wasm] Error 1 | ||
| ``` | ||
|
|
||
| The policy author must fix these errors to allow the `opa` CLI to build the code | ||
| successfully. The specific changes may vary depending on the `opa` version and | ||
| the original policy code. For this example, the final `policy.rego` code looks | ||
| like this: | ||
|
|
||
| ```rego | ||
| package policy | ||
|
|
||
| violation contains {"msg": msg, "details": {"missing_labels": missing}} if { | ||
| provided := {label | input.review.object.metadata.labels[label]} | ||
| required := {label | label := input.parameters.labels[_]} | ||
| missing := required - provided | ||
| count(missing) > 0 | ||
| msg = sprintf("you must provide labels: %v", [missing]) | ||
| } | ||
| ``` |
There was a problem hiding this comment.
I would rewrite this section and put that into a warning box. We also have to update the README of our templates (both Gatekeeper and OPA).
This is the information we need to distill, I did some research.
OPA graduated to version 1.0.0 on Dec 2024. Link. The 1.0.0 introduces a potentially breaking change:
Using if for all rule definitions and contains for multi-value rules is now mandatory, not just when using the rego.v1 import.
This is breaks the majority of the old policies.
It's still possible to build old policies that do not use this syntax by providing the --v0-compatible flag to the opa build command. (I've tested it against our template policy).
Gatekeeper has updated to OPA v1.0.0 with the v3.19.0 release.
From the release notes, the link this section of their docs.
Based on what is written there, and looking deep into the code, Gatekeeper assumes v0 is used unless the template is explicit about that:
...
targets:
- target: admission.k8s.gatekeeper.sh
code:
- engine: Rego
source:
version: "v1"
rego: |
<v1-rego-code>
...Hence, to summarize:
- The user has to check which version of Rego is mentioned
- If no version is mentioned ->
v0is used -> theopa buildmust use the special "--v0-compatible" flag OR, they must use an old version of OPA (a pre 1.0.0 - but I would not mention that) - If v1 is mentioned -> they must have a recent version of OPA, no special build flag has to be passed to the
opa buildcommand
I'm starting to wonder if we shouldn't create a new kwctl scaffold program that deals with this conversion... there are many steps and things to take into account 🤔
There was a problem hiding this comment.
I've added a new section about compatibility that users may face. ;)
| ::: | ||
|
|
||
| ## Step 4: Prepare `metadata.yml` for Distribution | ||
|
|
There was a problem hiding this comment.
Also for these steps... we could automate them with kwctl scaffold
There was a problem hiding this comment.
Yes, we can. I agree.However, there is no such automation now. Thus, the documentation needs to be written. ;)
Updates the Gatekeeper migration documentationg adding missing links, fixing typos and adding usefull command to copy rego code. Co-authored-by: Flavio Castelli <[email protected]> Signed-off-by: José Guilherme Vanz <[email protected]>
jvanz
force-pushed
the
gatekeeper-migration
branch
from
0232c0b to
b057603
Compare
Adds a documentation section about compatibility issues that users may face when migrating policies. Signed-off-by: José Guilherme Vanz <[email protected]>
Updates the Gatekeeper migration documentation to make clear that the test updates are an optional step. And, the user can reuse the tests from the migrated Gatekeeper policy, if they exist. Signed-off-by: José Guilherme Vanz <[email protected]>
Updates the Gatekeeper migration docs removing the long AdmissionRequest json used in the tests and point to users that they can use kwctl scaffold command to generate those file for tests. Signed-off-by: José Guilherme Vanz <[email protected]>
Updates the Gatekeeper migration documentation to consider the OPA_V0_COMPATIBLE variable when build the policy. This variable allow users to compile policy with written before opa v1.0.0. Signed-off-by: José Guilherme Vanz <[email protected]>
| - If your Rego policy template does NOT specify a `version` (or implies `v0`): You | ||
| must either call the `Makefile` target with the `OPA_V0_COMPATIBLE=true` variable | ||
| (e.g., `make OPA_V0_COMPATIBLE=true`) to ensure `opa` commands are called with the | ||
| `--v0-compatible` flag, or update your policy to the new `v1.0.0` syntax. |
There was a problem hiding this comment.
This consider that we apply the changes from this PR
Description
Adds a how to guide showing how users can migrate a Gatekeeper policy into Kubewarden policy.
Fix #621