From 0b3b53d990f9c34d08fab8a521af80a775c96fea Mon Sep 17 00:00:00 2001 From: aerosouund Date: Sun, 24 Nov 2024 16:00:24 +0200 Subject: [PATCH] chore: Add docs for mutate existing with the CLI Signed-off-by: aerosouund --- .../kyverno-cli/reference/kyverno_apply.md | 48 +++--- content/en/docs/kyverno-cli/usage/apply.md | 41 +++++ content/en/docs/kyverno-cli/usage/test.md | 158 +++++++++++++++++- 3 files changed, 222 insertions(+), 25 deletions(-) diff --git a/content/en/docs/kyverno-cli/reference/kyverno_apply.md b/content/en/docs/kyverno-cli/reference/kyverno_apply.md index 76ac4830c..320f6577d 100644 --- a/content/en/docs/kyverno-cli/reference/kyverno_apply.md +++ b/content/en/docs/kyverno-cli/reference/kyverno_apply.md @@ -42,29 +42,31 @@ kyverno apply [flags] ### Options ``` - --audit-warn If set to true, will flag audit policies as warnings instead of failures - -c, --cluster Checks if policies should be applied to cluster in the current context - --context string The name of the kubeconfig context to use - --detailed-results If set to true, display detailed results - -e, --exception strings Policy exception to be considered when evaluating policies against resources - --exceptions strings Policy exception to be considered when evaluating policies against resources - -b, --git-branch string test git repository branch - -h, --help help for apply - --kubeconfig string path to kubeconfig file with authorization and master location information - -n, --namespace string Optional Policy parameter passed with cluster flag - -o, --output string Prints the mutated resources in provided file/directory - -p, --policy-report Generates policy report when passed (default policyviolation) - --registry If set to true, access the image registry using local docker credentials to populate external data - --remove-color Remove any color from output - -r, --resource strings Path to resource files - --resources strings Path to resource files - -s, --set strings Variables that are required - -i, --stdin Optional mutate policy parameter to pipe directly through to kubectl - -t, --table Show results in table format - -u, --userinfo string Admission Info including Roles, Cluster Roles and Subjects - -f, --values-file string File containing values for policy variables - --warn-exit-code int Set the exit code for warnings; if failures or errors are found, will exit 1 - --warn-no-pass Specify if warning exit code should be raised if no objects satisfied a policy; can be used together with --warn-exit-code flag + --audit-warn If set to true, will flag audit policies as warnings instead of failures + -c, --cluster Checks if policies should be applied to cluster in the current context + --context string The name of the kubeconfig context to use + --detailed-results If set to true, display detailed results + -e, --exception strings Policy exception to be considered when evaluating policies against resources + --exceptions strings Policy exception to be considered when evaluating policies against resources + -b, --git-branch string test git repository branch + -h, --help help for apply + --kubeconfig string path to kubeconfig file with authorization and master location information + -n, --namespace string Optional Policy parameter passed with cluster flag + -o, --output string Prints the mutated resources in provided file/directory + -p, --policy-report Generates policy report when passed (default policyviolation) + --registry If set to true, access the image registry using local docker credentials to populate external data + --remove-color Remove any color from output + -r, --resource strings Path to resource files + --resources strings Path to resource files + --target-resource strings Path to target resources files for policies that have mutate existing + --target-resources strings Path to target resources files for policies that have mutate existing + -s, --set strings Variables that are required + -i, --stdin Optional mutate policy parameter to pipe directly through to kubectl + -t, --table Show results in table format + -u, --userinfo string Admission Info including Roles, Cluster Roles and Subjects + -f, --values-file string File containing values for policy variables + --warn-exit-code int Set the exit code for warnings; if failures or errors are found, will exit 1 + --warn-no-pass Specify if warning exit code should be raised if no objects satisfied a policy; can be used together with --warn-exit-code flag ``` ### Options inherited from parent commands diff --git a/content/en/docs/kyverno-cli/usage/apply.md b/content/en/docs/kyverno-cli/usage/apply.md index 07a2596bf..f6332dd34 100644 --- a/content/en/docs/kyverno-cli/usage/apply.md +++ b/content/en/docs/kyverno-cli/usage/apply.md @@ -74,6 +74,47 @@ Save the mutated resource to a directory: kyverno apply /path/to/policy.yaml --resource /path/to/resource.yaml -o foo/ ``` +Run a policy with a mutate existing rule on a group of target resources: + +```sh +kyverno apply /path/to/policy.yaml --resource /path/to/resource.yaml --target-resource /path/to/target1.yaml --target-resource /path/to/target2.yaml + +Applying 1 policy rule(s) to 1 resource(s)... + +mutate policy applied to : + +--- +patched targets: + + + +--- + + + +--- + +pass: 2, fail: 0, warn: 0, error: 0, skip: 0 +``` + +Run a policy with a mutate existing rule on target resources from a directory: + +```sh +kyverno apply /path/to/policy.yaml --resource /path/to/resource.yaml --target-resources /path/to/targets/ + +Applying 1 policy rule(s) to 1 resource(s)... + +mutate policy applied to : + +--- +patched targets: + + + +pass: 5, fail: 0, warn: 0, error: 0, skip: 0 +``` + + Apply a policy containing variables using the `--set` or `-s` flag to pass in the values. Variables that begin with `{{request.object}}` normally do not need to be specified as these will be read from the resource. ```sh diff --git a/content/en/docs/kyverno-cli/usage/test.md b/content/en/docs/kyverno-cli/usage/test.md index f60590e49..14ce1095b 100644 --- a/content/en/docs/kyverno-cli/usage/test.md +++ b/content/en/docs/kyverno-cli/usage/test.md @@ -37,6 +37,9 @@ policies: resources: - - +targetResources: # optional key for specifying target resources when testing for mutate existing rules + - + - exceptions: # optional files for specifying exceptions. See below for an example. - - @@ -49,10 +52,10 @@ results: resources: # optional, primarily for `validate` rules. - - - patchedResources: # when testing a mutate rule this field is required. + patchedResources: # when testing a mutate rule this field is required. File may contain one or more resources separated by --- generatedResource: # when testing a generate rule this field is required. cloneSourceResource: # when testing a generate rule that uses `clone` object this field is required. - kind: + kind: # optional result: pass checks: - match: @@ -446,6 +449,157 @@ skipped mutate policy add-default-resources -> resource default/Pod/nginx-demo2 Test Summary: 2 tests passed and 0 tests failed ``` +In this scenario, a `mutate` policy which adds a label to `Secrets` based on requests made on a particular `ConfigMap`, +note the use of the `targetResources` field + +Test manifest (`kyverno-test.yaml`): +```yaml +apiVersion: cli.kyverno.io/v1alpha1 +kind: Test +metadata: + name: kyverno-test.yaml +policies: +- policy.yaml +resources: +- trigger-cm.yaml +targetResources: +- raw-secret.yaml +results: +- patchedResource: mutated-secret.yaml + policy: mutate-existing-secret + resources: + - secret-1 + result: pass + rule: mutate-secret-on-configmap-create +``` + +Policy (`policy.yaml`): +```yaml +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: mutate-existing-secret +spec: + rules: + - match: + any: + - resources: + kinds: + - ConfigMap + names: + - dictionary-1 + namespaces: + - staging + mutate: + mutateExistingOnPolicyUpdate: false + patchStrategicMerge: + metadata: + labels: + foo: bar + targets: + - apiVersion: v1 + kind: Secret + name: '*' + namespace: staging + name: mutate-secret-on-configmap-create +``` + +Trigger (`trigger-cm.yaml`): + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: dictionary-1 + namespace: staging +``` + +Target (`raw-secret.yaml`): + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: secret-1 + namespace: staging +``` + +Mutated target (`mutated-secret.yaml`): + +```yaml +apiVersion: v1 +kind: Secret +metadata: + labels: + foo: bar + name: secret-1 + namespace: staging +``` + +```sh +$ kyverno test . +Loading test ( 3-test/kyverno-test.yaml ) ... + Loading values/variables ... + Loading policies ... + Loading resources ... + Loading exceptions ... + Applying 1 policy to 1 resource ... + Checking results ... + +│────│────────────────────────│───────────────────────────────────│────────────────────────────│────────│────────│ +│ ID │ POLICY │ RULE │ RESOURCE │ RESULT │ REASON │ +│────│────────────────────────│───────────────────────────────────│────────────────────────────│────────│────────│ +│ 1 │ mutate-existing-secret │ mutate-secret-on-configmap-create │ v1/Secret/staging/secret-1 │ Pass │ Ok │ +│────│────────────────────────│───────────────────────────────────│────────────────────────────│────────│────────│ + + +Test Summary: 1 tests passed and 0 tests failed +``` + + +If you don't specify an entry in the `resources` field in the results the CLI will check results for all trigger and target resources involved in the test and will match them against the resources specified in the `patchedResources` file: + +Patched resources (`mutated-resources.yaml`): + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: dictionary-1 + namespace: staging +--- +apiVersion: v1 +kind: Secret +metadata: + labels: + foo: bar + name: secret-1 + namespace: staging +--- + +``` + +``` +Loading test ( 5-test-with-selection/kyverno-test.yaml ) ... + Loading values/variables ... + Loading policies ... + Loading resources ... + Loading exceptions ... + Applying 1 policy to 1 resource ... + Checking results ... + +│────│────────────────────────│───────────────────────────────────│───────────────────────────────────│────────│────────│ +│ ID │ POLICY │ RULE │ RESOURCE │ RESULT │ REASON │ +│────│────────────────────────│───────────────────────────────────│───────────────────────────────────│────────│────────│ +│ 1 │ mutate-existing-secret │ mutate-secret-on-configmap-create │ v1/Secret/staging/secret-1 │ Pass │ Ok │ +│ 2 │ mutate-existing-secret │ mutate-secret-on-configmap-create │ v1/ConfigMap/staging/dictionary-1 │ Pass │ Ok │ +│────│────────────────────────│───────────────────────────────────│───────────────────────────────────│────────│────────│ + + +Test Summary: 2 tests passed and 0 tests failed +``` + + In the following policy test, a `generate` policy rule is applied which generates a new resource from an existing resource present in `resource.yaml`. To test the `generate` policy, the addition of a `generatedResource` field in the `results[]` array is required which is used to test against the resource generated by the policy. Policy manifest (`add_network_policy.yaml`):