From 5c2c955f1bcd162609dd4e5da0289472d81fc479 Mon Sep 17 00:00:00 2001 From: Mariam Fahmy Date: Thu, 12 Sep 2024 16:14:53 +0300 Subject: [PATCH] docs: add warning for the validationFailureAction deprecated field Signed-off-by: Mariam Fahmy --- content/en/docs/applying-policies/_index.md | 2 +- content/en/docs/introduction/quick-start.md | 4 +- content/en/docs/kyverno-cli/usage/apply.md | 11 +-- content/en/docs/kyverno-cli/usage/test.md | 5 +- content/en/docs/policy-reports/_index.md | 2 +- content/en/docs/policy-reports/background.md | 10 +- content/en/docs/policy-reports/examples.md | 4 +- content/en/docs/troubleshooting/_index.md | 2 +- content/en/docs/writing-policies/autogen.md | 6 +- .../en/docs/writing-policies/exceptions.md | 6 +- .../writing-policies/external-data-sources.md | 8 +- content/en/docs/writing-policies/jmespath.md | 55 +++++------ .../en/docs/writing-policies/match-exclude.md | 11 +-- .../docs/writing-policies/policy-settings.md | 8 +- .../en/docs/writing-policies/preconditions.md | 5 +- content/en/docs/writing-policies/tips.md | 4 +- content/en/docs/writing-policies/validate.md | 96 ++++++++++--------- content/en/docs/writing-policies/variables.md | 2 +- .../verify-images/notary/_index.md | 14 +-- .../verify-images/sigstore/_index.md | 41 ++++---- 20 files changed, 152 insertions(+), 144 deletions(-) diff --git a/content/en/docs/applying-policies/_index.md b/content/en/docs/applying-policies/_index.md index e80ad376a..70acaae65 100644 --- a/content/en/docs/applying-policies/_index.md +++ b/content/en/docs/applying-policies/_index.md @@ -13,7 +13,7 @@ The [Kyverno Policies](/policies/) repository contains several policies you can On installation, Kyverno runs as a [dynamic admission controller](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/) in a Kubernetes cluster. Kyverno receives validating and mutating admission webhook HTTP callbacks from the Kubernetes API server and applies matching policies to return results that enforce admission policies or reject requests. -Policies with validation rules can be used to block insecure or non-compliant configurations by setting the [`validationFailureAction`](../writing-policies/validate.md#validation-failure-action) to `Enforce`. Or, validation rules can be applied using periodic scans with results available as [policy reports](../policy-reports/). +Policies with validation rules can be used to block insecure or non-compliant configurations by setting the [`failureAction`](../writing-policies/validate.md#failure-action) to `Enforce`. Or, validation rules can be applied using periodic scans with results available as [policy reports](../policy-reports/). Rules in a policy are applied in the order of definition. During [admission control](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/), mutation rules are applied before validation rules. This allows validation of changes made during mutation. Note that **all** mutation rules are applied first across all policies before any validation rules are applied. diff --git a/content/en/docs/introduction/quick-start.md b/content/en/docs/introduction/quick-start.md index a1fb7ba39..c1f6bba62 100644 --- a/content/en/docs/introduction/quick-start.md +++ b/content/en/docs/introduction/quick-start.md @@ -22,7 +22,7 @@ Next, select the quick start guide in which you are interested. Alternatively, s In the validation guide, you will see how simple an example Kyverno policy can be which ensures a label called `team` is present on every Pod. Validation is the most common use case for policy and functions as a "yes" or "no" decision making process. Resources which are compliant with the policy are allowed to pass ("yes, this is allowed") and those which are not compliant may not be allowed to pass ("no, this is not allowed"). An additional effect of these validate policies is to produce Policy Reports. A [Policy Report](../policy-reports/_index.md) is a custom Kubernetes resource, produced and managed by Kyverno, which shows the results of policy decisions upon allowed resources in a user-friendly way. -Add the policy below to your cluster. It contains a single validation rule that requires that all Pods have the `team` label. Kyverno supports different rule types to validate, mutate, generate, cleanup, and verify image configurations. The field `validationFailureAction` is set to `Enforce` to block Pods that are non-compliant. Using the default value `Audit` will report violations but not block requests. +Add the policy below to your cluster. It contains a single validation rule that requires that all Pods have the `team` label. Kyverno supports different rule types to validate, mutate, generate, cleanup, and verify image configurations. The field `failureAction` is set to `Enforce` to block Pods that are non-compliant. Using the default value `Audit` will report violations but not block requests. ```yaml kubectl create -f- << EOF @@ -31,7 +31,6 @@ kind: ClusterPolicy metadata: name: require-labels spec: - validationFailureAction: Enforce rules: - name: check-team match: @@ -40,6 +39,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: "label 'team' is required" pattern: metadata: diff --git a/content/en/docs/kyverno-cli/usage/apply.md b/content/en/docs/kyverno-cli/usage/apply.md index 07e30f0a4..66bfe29f2 100644 --- a/content/en/docs/kyverno-cli/usage/apply.md +++ b/content/en/docs/kyverno-cli/usage/apply.md @@ -264,7 +264,6 @@ kind: ClusterPolicy metadata: name: cm-globalval-example spec: - validationFailureAction: Enforce background: false rules: - name: validate-mode @@ -274,6 +273,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: "The value {{ request.mode }} for val1 is not equal to 'dev'." deny: conditions: @@ -362,7 +362,6 @@ kind: ClusterPolicy metadata: name: enforce-pod-name spec: - validationFailureAction: Audit background: true rules: - name: validate-name @@ -378,6 +377,7 @@ spec: values: - managed validate: + failureAction: Audit message: "The Pod must end with -nginx" pattern: metadata: @@ -446,7 +446,6 @@ metadata: annotations: pod-policies.kyverno.io/autogen-controllers: DaemonSet,Deployment,StatefulSet spec: - validationFailureAction: Enforce background: false rules: - name: example-configmap-lookup @@ -495,7 +494,7 @@ policies: dictionary.data.env: dev1 ``` -Policies that have their validationFailureAction set to `Audit` can be set to produce a warning instead of a failure using the `--audit-warn` flag. This will also cause a non-zero exit code if no enforcing policies failed. +Policies that have their failureAction set to `Audit` can be set to produce a warning instead of a failure using the `--audit-warn` flag. This will also cause a non-zero exit code if no enforcing policies failed. ```sh kyverno apply /path/to/policy.yaml --resource /path/to/resource.yaml --audit-warn @@ -551,7 +550,6 @@ kind: ClusterPolicy metadata: name: require-pod-requests-limits spec: - validationFailureAction: Audit rules: - name: validate-resources match: @@ -560,6 +558,7 @@ spec: kinds: - Pod validate: + failureAction: Audit message: "CPU and memory resource requests and limits are required" pattern: spec: @@ -703,7 +702,6 @@ kind: ClusterPolicy metadata: name: max-containers spec: - validationFailureAction: Enforce background: false rules: - name: max-two-containers @@ -713,6 +711,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: "A maximum of 2 containers are allowed inside a Pod." deny: conditions: diff --git a/content/en/docs/kyverno-cli/usage/test.md b/content/en/docs/kyverno-cli/usage/test.md index 1ebd7d6e6..3b9ca3829 100644 --- a/content/en/docs/kyverno-cli/usage/test.md +++ b/content/en/docs/kyverno-cli/usage/test.md @@ -228,7 +228,6 @@ kind: ClusterPolicy metadata: name: disallow-latest-tag spec: - validationFailureAction: Audit rules: - name: require-image-tag match: @@ -237,6 +236,7 @@ spec: kinds: - Pod validate: + failureAction: Audit message: "An image tag is required." pattern: spec: @@ -249,6 +249,7 @@ spec: kinds: - Pod validate: + failureAction: Audit message: "Using a mutable image tag e.g. 'latest' is not allowed." pattern: spec: @@ -544,7 +545,6 @@ kind: ClusterPolicy metadata: name: disallow-host-namespaces spec: - validationFailureAction: Enforce background: false rules: - name: host-namespaces @@ -554,6 +554,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: >- Sharing the host namespaces is disallowed. The fields spec.hostNetwork, spec.hostIPC, and spec.hostPID must be unset or set to `false`. diff --git a/content/en/docs/policy-reports/_index.md b/content/en/docs/policy-reports/_index.md index 04db46c78..c79cbc0b2 100644 --- a/content/en/docs/policy-reports/_index.md +++ b/content/en/docs/policy-reports/_index.md @@ -7,7 +7,7 @@ weight: 60 Policy reports are Kubernetes Custom Resources, generated and managed automatically by Kyverno, which contain the results of applying matching Kubernetes resources to Kyverno ClusterPolicy or Policy resources. They are created for `validate` and `verifyImages` rules when a resource is matched by one or more rules according to the policy definition. If resources violate multiple rules, there will be multiple entries. When resources are deleted, their entry will be removed from the report. Reports, therefore, always represent the current state of the cluster and do not record historical information. -For example, if a validate policy in `Audit` mode exists containing a single rule which requires that all resources set the label `team` and a user creates a Pod which does not set the `team` label, Kyverno will allow the Pod's creation but record it as a `fail` result in a policy report due to the Pod being in violation of the policy and rule. Policies configured with `spec.validationFailureAction: Enforce` immediately block violating resources and results will only be reported for `pass` evaluations. Policy reports are an ideal way to observe the impact a Kyverno policy may have in a cluster without causing disruption. The insights gained from these policy reports may be used to provide valuable feedback to both users/developers so they may take appropriate action to bring offending resources into alignment, and to policy authors or cluster operators to help them refine policies prior to changing them to `Enforce` mode. Because reports are decoupled from policies, standard Kubernetes RBAC can then be applied to separate those who can see and manipulate policies from those who can view reports. +For example, if a validate policy in `Audit` mode exists containing a single rule which requires that all resources set the label `team` and a user creates a Pod which does not set the `team` label, Kyverno will allow the Pod's creation but record it as a `fail` result in a policy report due to the Pod being in violation of the policy and rule. Policies configured with `spec.rules[*].validate[*].failureAction: Enforce` immediately block violating resources and results will only be reported for `pass` evaluations. Policy reports are an ideal way to observe the impact a Kyverno policy may have in a cluster without causing disruption. The insights gained from these policy reports may be used to provide valuable feedback to both users/developers so they may take appropriate action to bring offending resources into alignment, and to policy authors or cluster operators to help them refine policies prior to changing them to `Enforce` mode. Because reports are decoupled from policies, standard Kubernetes RBAC can then be applied to separate those who can see and manipulate policies from those who can view reports. Policy reports are created based on two different triggers: an admission event (a `CREATE`, `UPDATE`, or `DELETE` action performed against a resource) or the result of a background scan discovering existing resources. Policy reports, like Kyverno policies, have both Namespaced and cluster-scoped variants; a `PolicyReport` is a Namespaced resource while a `ClusterPolicyReport` is a cluster-scoped resource. Reports are stored in the cluster on a per resource basis. Every namespaced resource will (eventually) have an associated `PolicyReport` and every clustered resource will (eventually) have an associated `ClusterPolicyReport`. diff --git a/content/en/docs/policy-reports/background.md b/content/en/docs/policy-reports/background.md index 0d0dd1510..e1a66ca6e 100644 --- a/content/en/docs/policy-reports/background.md +++ b/content/en/docs/policy-reports/background.md @@ -22,20 +22,20 @@ Background scanning, enabled by default in a `Policy` or `ClusterPolicy` object Background scanning occurs on a periodic basis (one hour by default) and offers some configuration options via [container flags](../installation/customization.md#container-flags). -When background scanning is enabled, regardless of whether the policy's `validationFailureAction` is set to `Enforce` or `Audit`, the results will be recorded in a report. To see the specifics of how reporting works with background scans, refer to the tables below. +When background scanning is enabled, regardless of whether the policy's `failureAction` is set to `Enforce` or `Audit`, the results will be recorded in a report. To see the specifics of how reporting works with background scans, refer to the tables below. **Reporting behavior when `background: true`** | | New Resource | Existing Resource | |----------------------------------|--------------|-------------------| -| `validationFailureAction: Enforce` | Pass only | Report | -| `validationFailureAction: Audit` | Report | Report | +| `failureAction: Enforce` | Pass only | Report | +| `failureAction: Audit` | Report | Report | **Reporting behavior when `background: false`** | | New Resource | Existing Resource | |----------------------------------|--------------|-------------------| -| `validationFailureAction: Enforce` | Pass only | None | -| `validationFailureAction: Audit` | Report | None | +| `failureAction: Enforce` | Pass only | None | +| `failureAction: Audit` | Report | None | Also, policy rules that are written using either certain variables from [AdmissionReview](../writing-policies/variables.md#variables-from-admission-review-requests) request information (e.g. `request.userInfo`), or fields like Roles, ClusterRoles, and Subjects in `match` and `exclude` statements, cannot be applied to existing resources in the background scanning mode since that information must come from an AdmissionReview request and is not available if the resource exists. Hence, these rules must set `background` to `false` to disable background scanning. The exceptions to this are `request.object` and `request.namespace` variables as these will be translated from the current state of the resource. diff --git a/content/en/docs/policy-reports/examples.md b/content/en/docs/policy-reports/examples.md index ef48b331f..50445f2b8 100644 --- a/content/en/docs/policy-reports/examples.md +++ b/content/en/docs/policy-reports/examples.md @@ -18,7 +18,6 @@ metadata: name: secrets-not-from-env-vars spec: background: true - validationFailureAction: Audit rules: - name: secrets-not-from-env-vars match: @@ -27,6 +26,7 @@ spec: kinds: - Pod validate: + failureAction: Audit message: "Secrets must be mounted as volumes, not as environment variables." pattern: spec: @@ -76,7 +76,7 @@ summary: warn: 0 ``` -Create another Pod which violates the rule in the sample policy. Because the rule is written with `validationFailureAction: Audit`, resources are allowed to be created which violate the rule. If this occurs, another entry will be created in the PolicyReport which denotes this condition as a FAIL. By contrast, if `validationFailureAction: Enforce` and an offending resource was attempted creation, it would be immediately blocked and therefore would not generate another entry in the report. However, if the resource passed then a PASS result would be created in the report. +Create another Pod which violates the rule in the sample policy. Because the rule is written with `failureAction: Audit`, resources are allowed to be created which violate the rule. If this occurs, another entry will be created in the PolicyReport which denotes this condition as a FAIL. By contrast, if `failureAction: Enforce` and an offending resource was attempted creation, it would be immediately blocked and therefore would not generate another entry in the report. However, if the resource passed then a PASS result would be created in the report. ```yaml apiVersion: v1 diff --git a/content/en/docs/troubleshooting/_index.md b/content/en/docs/troubleshooting/_index.md index c5e7c6285..427546bcb 100644 --- a/content/en/docs/troubleshooting/_index.md +++ b/content/en/docs/troubleshooting/_index.md @@ -82,7 +82,7 @@ Use [Namespace selectors](../installation/customization.md#namespace-selectors) pod "busybox" deleted ``` -5. For `validate` policies, ensure that `validationFailureAction` is set to `Enforce` if your expectation is that applicable resources should be blocked. Most policies in the samples library are purposefully set to `Audit` mode so they don't have any unintended consequences for new users. It could be that, if the prior steps check out, Kyverno is working fine only that your policy is configured to not immediately block resources. +5. For `validate` policies, ensure that `failureAction` is set to `Enforce` if your expectation is that applicable resources should be blocked. Most policies in the samples library are purposefully set to `Audit` mode so they don't have any unintended consequences for new users. It could be that, if the prior steps check out, Kyverno is working fine only that your policy is configured to not immediately block resources. 6. Check and ensure you aren't creating a resource that is either excluded from Kyverno's processing by default, or that it hasn't been created in an excluded Namespace. Kyverno uses a ConfigMap by default called `kyverno` in the Kyverno Namespace to filter out some of these things. The key name is `resourceFilters` and more details can be found [here](../installation/customization.md#resource-filters). diff --git a/content/en/docs/writing-policies/autogen.md b/content/en/docs/writing-policies/autogen.md index 9ac6ae785..06922ee1c 100644 --- a/content/en/docs/writing-policies/autogen.md +++ b/content/en/docs/writing-policies/autogen.md @@ -15,7 +15,6 @@ kind: ClusterPolicy metadata: name: restrict-image-registries spec: - validationFailureAction: Enforce rules: - name: validate-registries match: @@ -24,6 +23,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: "Images may only come from our internal enterprise registry." pattern: spec: @@ -56,6 +56,7 @@ status: mutate: {} name: autogen-validate-registries validate: + failureAction: Enforce message: Images may only come from our internal enterprise registry. pattern: spec: @@ -77,6 +78,7 @@ status: mutate: {} name: autogen-cronjob-validate-registries validate: + failureAction: Enforce message: Images may only come from our internal enterprise registry. pattern: spec: @@ -139,7 +141,6 @@ kind: ClusterPolicy metadata: name: require-requests-limits spec: - validationFailureAction: Enforce background: true rules: - name: validate-resources @@ -154,6 +155,7 @@ spec: operator: NotEquals value: skip validate: + failureAction: Enforce message: "CPU and memory resource requests and limits are required." pattern: spec: diff --git a/content/en/docs/writing-policies/exceptions.md b/content/en/docs/writing-policies/exceptions.md index 8ec57660d..0b16c5989 100644 --- a/content/en/docs/writing-policies/exceptions.md +++ b/content/en/docs/writing-policies/exceptions.md @@ -32,7 +32,6 @@ kind: ClusterPolicy metadata: name: disallow-host-namespaces spec: - validationFailureAction: Enforce background: false rules: - name: host-namespaces @@ -42,6 +41,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: >- Sharing the host namespaces is disallowed. The fields spec.hostNetwork, spec.hostIPC, and spec.hostPID must be unset or set to `false`. @@ -145,7 +145,6 @@ kind: ClusterPolicy metadata: name: policy-for-exceptions spec: - validationFailureAction: Enforce background: false rules: - name: require-match-name @@ -155,6 +154,7 @@ spec: kinds: - PolicyException validate: + failureAction: Enforce message: >- An exception must explicitly specify a name for a resource match. pattern: @@ -181,7 +181,6 @@ metadata: name: psa spec: background: true - validationFailureAction: Enforce rules: - name: restricted match: @@ -190,6 +189,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce podSecurity: level: restricted version: latest diff --git a/content/en/docs/writing-policies/external-data-sources.md b/content/en/docs/writing-policies/external-data-sources.md index 3d64e9153..0aec61627 100644 --- a/content/en/docs/writing-policies/external-data-sources.md +++ b/content/en/docs/writing-policies/external-data-sources.md @@ -120,7 +120,6 @@ kind: ClusterPolicy metadata: name: cm-array-example spec: - validationFailureAction: Enforce background: false rules: - name: validate-role-annotation @@ -135,6 +134,7 @@ spec: kinds: - Deployment validate: + failureAction: Enforce message: "The role {{ request.object.metadata.annotations.role }} is not in the allowed list of roles: {{ \"roles-dictionary\".data.\"allowed-roles\" }}." deny: conditions: @@ -517,7 +517,6 @@ kind: ClusterPolicy metadata: name: limits spec: - validationFailureAction: Enforce rules: - name: limit-lb-svc match: @@ -533,6 +532,7 @@ spec: urlPath: "/api/v1/namespaces/{{ request.namespace }}/services" jmesPath: "items[?spec.type == 'LoadBalancer'] | length(@)" validate: + failureAction: Enforce message: "Only one LoadBalancer service is allowed per namespace" deny: conditions: @@ -558,7 +558,6 @@ kind: ClusterPolicy metadata: name: check-namespaces spec: - validationFailureAction: Enforce rules: - name: call-extension match: @@ -580,6 +579,7 @@ spec: -----END CERTIFICATE----- validate: + failureAction: Enforce message: "namespace {{request.namespace}} is not allowed" deny: conditions: @@ -831,7 +831,6 @@ kind: ClusterPolicy metadata: name: imageref-demo spec: - validationFailureAction: Enforce rules: - name: no-root-images match: @@ -843,6 +842,7 @@ spec: - CREATE - UPDATE validate: + failureAction: Enforce message: "Images run as root are not allowed." foreach: - list: "request.object.spec.containers" diff --git a/content/en/docs/writing-policies/jmespath.md b/content/en/docs/writing-policies/jmespath.md index 2ec5d2744..92be54ea3 100644 --- a/content/en/docs/writing-policies/jmespath.md +++ b/content/en/docs/writing-policies/jmespath.md @@ -319,7 +319,6 @@ kind: ClusterPolicy metadata: name: restrict-ingress-wildcard spec: - validationFailureAction: Enforce rules: - name: block-ingress-wildcard match: @@ -328,6 +327,7 @@ spec: kinds: - Ingress validate: + failureAction: Enforce message: "Wildcards are not permitted as hosts." foreach: - list: "request.object.spec.rules" @@ -383,7 +383,6 @@ kind: ClusterPolicy metadata: name: add-demo spec: - validationFailureAction: Enforce background: false rules: - name: add-demo @@ -396,6 +395,7 @@ spec: - CREATE - UPDATE validate: + failureAction: Enforce message: "The total memory defined in requests and limits must not exceed 200Mi." foreach: - list: "request.object.spec.containers" @@ -438,7 +438,6 @@ metadata: name: base64-decode-demo spec: background: false - validationFailureAction: Enforce rules: - name: base64-decode-demo match: @@ -455,6 +454,7 @@ spec: operator: NotEquals value: DELETE validate: + failureAction: Enforce message: This license key may not be consumed by a Secret. foreach: - list: "request.object.spec.[containers, initContainers, ephemeralContainers][].env[].valueFrom.secretKeyRef" @@ -587,7 +587,6 @@ kind: ClusterPolicy metadata: name: enforce-resources-as-ratio spec: - validationFailureAction: Audit rules: - name: check-memory-requests-limits match: @@ -599,6 +598,7 @@ spec: - CREATE - UPDATE validate: + failureAction: Enforce message: Limits may not exceed 2.5x the requests. foreach: - list: "request.object.spec.containers" @@ -637,7 +637,6 @@ kind: ClusterPolicy metadata: name: equal-fold-demo spec: - validationFailureAction: Enforce background: false rules: - name: validate-dept-label-data @@ -647,6 +646,7 @@ spec: kinds: - ConfigMap validate: + failureAction: Enforce message: The dept label must equal the data.dept value aside from case. deny: conditions: @@ -719,7 +719,6 @@ kind: ClusterPolicy metadata: name: check-external-url-in-configmap spec: - validationFailureAction: Enforce background: false rules: - name: validate-external-url @@ -729,6 +728,7 @@ spec: kinds: - ConfigMap validate: + failureAction: Enforce message: "ConfigMap contains an external URL." deny: conditions: @@ -971,7 +971,6 @@ kind: ClusterPolicy metadata: name: require-pdb spec: - validationFailureAction: Audit background: false rules: - name: require-pdb @@ -988,6 +987,7 @@ spec: urlPath: "/apis/policy/v1beta1/namespaces/{{request.namespace}}/poddisruptionbudgets" jmesPath: "items[?label_match(spec.selector.matchLabels, `{{request.object.spec.template.metadata.labels}}`)] | length(@)" validate: + failureAction: Audit message: "There is no corresponding PodDisruptionBudget found for this Deployment." deny: conditions: @@ -1115,7 +1115,6 @@ kind: ClusterPolicy metadata: name: modulo-demo spec: - validationFailureAction: Audit rules: - name: check-memory-requests-limits match: @@ -1127,6 +1126,7 @@ spec: - CREATE - UPDATE validate: + failureAction: Audit message: Limits must be evenly divisible by the requests. foreach: - list: "request.object.spec.containers" @@ -1388,7 +1388,6 @@ kind: ClusterPolicy metadata: name: parse-yaml-demo spec: - validationFailureAction: Enforce background: false rules: - name: check-goodbois @@ -1398,6 +1397,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: "Only good bois allowed." deny: conditions: @@ -1455,7 +1455,6 @@ kind: ClusterPolicy metadata: name: path-canonicalize-demo spec: - validationFailureAction: Enforce background: false rules: - name: disallow-mount-containerd-sock @@ -1465,6 +1464,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce foreach: - list: "request.object.spec.volumes[]" deny: @@ -1498,7 +1498,6 @@ kind: ClusterPolicy metadata: name: pattern-match-demo spec: - validationFailureAction: Enforce background: false rules: - match: @@ -1513,6 +1512,7 @@ spec: name: deptbillingcodes namespace: default validate: + failureAction: Enforce message: The department {{request.object.metadata.labels.dept}} must supply a matching billing code. deny: conditions: @@ -1621,7 +1621,6 @@ metadata: name: regex-match-demo spec: background: true - validationFailureAction: Enforce rules: - name: validate-backup-schedule-annotation-cron match: @@ -1630,6 +1629,7 @@ spec: kinds: - PersistentVolumeClaim validate: + failureAction: Enforce message: The annotation `backup-schedule` must be present and in cron format. deny: conditions: @@ -1831,7 +1831,6 @@ kind: ClusterPolicy metadata: name: round-demo spec: - validationFailureAction: Enforce rules: - name: round-input match: @@ -1844,6 +1843,7 @@ spec: variable: value: 10.123456 validate: + failureAction: Enforce message: The rounded value is {{ round(input, `2`) }}. deny: {} ``` @@ -1870,7 +1870,6 @@ kind: ClusterPolicy metadata: name: semver-compare-demo spec: - validationFailureAction: Enforce background: false rules: - name: check-sbom @@ -1881,6 +1880,7 @@ spec: - Pod verifyImages: - image: "ghcr.io/kyverno/test-verify-image*" + failureAction: Enforce key: |- -----BEGIN PUBLIC KEY----- MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEHMmDjK65krAyDaGaeyWNzgvIu155 @@ -1955,7 +1955,6 @@ kind: ClusterPolicy metadata: name: split-demo spec: - validationFailureAction: Audit background: false rules: - name: check-path @@ -1978,6 +1977,7 @@ spec: urlPath: "/apis/networking.k8s.io/v1/namespaces/{{request.object.metadata.namespace}}/ingresses" jmesPath: "items[].spec.rules[].http.paths[].path" validate: + failureAction: Audit message: >- The root path /{{request.object.spec.rules[].http.paths[].path | to_string(@) | split(@, '/') | [1]}}/ exists in another Ingress rule elsewhere in the cluster. @@ -2077,7 +2077,6 @@ kind: ClusterPolicy metadata: name: sum-demo spec: - validationFailureAction: Enforce rules: - name: memory-requests-check match: @@ -2086,6 +2085,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: The sum of all memory requests in a Pod cannot exceed 1 gibibyte. deny: conditions: @@ -2119,7 +2119,6 @@ kind: ClusterPolicy metadata: name: automate-cleanup spec: - validationFailureAction: Enforce background: false rules: - name: cleanup @@ -2177,7 +2176,6 @@ metadata: name: decommission-policy spec: background: false - validationFailureAction: Enforce rules: - name: decomm-jan-12 match: @@ -2186,6 +2184,7 @@ spec: kinds: - ConfigMap validate: + failureAction: Enforce message: "This cluster is being decommissioned and no further resources may be created after January 12th." deny: conditions: @@ -2220,7 +2219,6 @@ metadata: name: expiration spec: background: false - validationFailureAction: Enforce rules: - name: expire-jan-31 match: @@ -2234,6 +2232,7 @@ spec: operator: Equals value: true validate: + failureAction: Enforce message: "The foo label must be set." pattern: metadata: @@ -2266,7 +2265,6 @@ metadata: name: expiration spec: background: false - validationFailureAction: Enforce rules: - name: expire-jan-31 match: @@ -2280,6 +2278,7 @@ spec: operator: Equals value: true validate: + failureAction: Enforce message: "The foo label must be set." pattern: metadata: @@ -2311,9 +2310,9 @@ kind: ClusterPolicy metadata: name: require-vulnerability-scan spec: - validationFailureAction: Enforce - webhookTimeoutSeconds: 20 - failurePolicy: Fail + webhookConfiguration: + failurePolicy: Fail + timeoutSeconds: 20 rules: - name: scan-not-older-than-one-day match: @@ -2324,6 +2323,7 @@ spec: verifyImages: - imageReferences: - "ghcr.io/myorg/myrepo:*" + failureAction: Enforce attestations: - predicateType: cosign.sigstore.dev/attestation/vuln/v1 attestors: @@ -2364,7 +2364,6 @@ kind: ClusterPolicy metadata: name: automate-cleanup spec: - validationFailureAction: Enforce background: false rules: - name: cleanup @@ -2421,7 +2420,6 @@ kind: ClusterPolicy metadata: name: automate-cleanup spec: - validationFailureAction: Enforce background: false rules: - name: cleanup @@ -2520,7 +2518,6 @@ kind: ClusterPolicy metadata: name: time-since-demo spec: - validationFailureAction: Audit rules: - name: block-stale-images match: @@ -2529,6 +2526,7 @@ spec: kinds: - Pod validate: + failureAction: Audit message: "Images built more than 6 months ago are prohibited." foreach: - list: "request.object.spec.containers" @@ -2568,7 +2566,6 @@ kind: ClusterPolicy metadata: name: automate-cleanup spec: - validationFailureAction: Enforce background: false rules: - name: cleanup @@ -2852,7 +2849,6 @@ metadata: name: verify-data-volume-image spec: background: false - validationFailureAction: Enforce rules: - name: verify-data-volume-image match: @@ -2867,6 +2863,7 @@ spec: verifyImages: - imageReferences: - "*" + failureAction: Enforce mutateDigest: true verifyDigest: true attestors: @@ -3063,7 +3060,6 @@ kind: ClusterPolicy metadata: name: test-x509-decode spec: - validationFailureAction: Audit background: true rules: - name: test-x509-decode @@ -3074,6 +3070,7 @@ spec: - ValidatingWebhookConfiguration - MutatingWebhookConfiguration validate: + failureAction: Audit message: "Certificate will expire in less than a week." deny: conditions: diff --git a/content/en/docs/writing-policies/match-exclude.md b/content/en/docs/writing-policies/match-exclude.md index d365e0547..33a227908 100644 --- a/content/en/docs/writing-policies/match-exclude.md +++ b/content/en/docs/writing-policies/match-exclude.md @@ -151,7 +151,6 @@ kind: ClusterPolicy metadata: name: require-labels spec: - validationFailureAction: Audit background: false rules: - name: check-for-labels @@ -163,6 +162,7 @@ spec: operations: - CREATE validate: + failureAction: Audit message: "The label `app.kubernetes.io/name` is required." pattern: metadata: @@ -239,11 +239,6 @@ This pattern can be leveraged to produce very fine-grained control over the sele ```yaml spec: - # validationFailureAction controls admission control behaviors, - # when a policy rule fails: - # - use 'Enforce' to block resource creation or modification - # - use 'Audit' to allow resource updates and report policy violations - validationFailureAction: Enforce # Each policy has a list of rules applied in declaration order rules: # Rules must have a unique name @@ -403,7 +398,6 @@ A variation on the above sample, this snippet uses `any` and `all` statements to ```yaml spec: - validationFailureAction: Enforce background: false rules: - name: match-criticals-except-given-users @@ -461,7 +455,6 @@ metadata: annotations: pod-policies.kyverno.io/autogen-controllers: none spec: - validationFailureAction: Audit background: false rules: - name: require-team @@ -473,6 +466,7 @@ spec: operations: - CREATE validate: + failureAction: Audit message: 'The label `team` is required.' pattern: metadata: @@ -487,6 +481,7 @@ spec: operations: - UPDATE validate: + failureAction: Audit message: 'The label `match` is required.' pattern: metadata: diff --git a/content/en/docs/writing-policies/policy-settings.md b/content/en/docs/writing-policies/policy-settings.md index a42f936b3..58123952e 100644 --- a/content/en/docs/writing-policies/policy-settings.md +++ b/content/en/docs/writing-policies/policy-settings.md @@ -13,7 +13,7 @@ A [policy](../kyverno-policies) contains one or more rules, and the following co * **background**: controls scanning of existing resources to find potential violations and generating Policy Reports. See the documentation [here](../policy-reports/background.md). Defaults to "true". -* **failurePolicy**: defines the API server behavior if the webhook fails to respond. Allowed values are "Ignore" or "Fail". Defaults to "Fail". Additionally, if set to "Ignore" will allow failing calls to image registries to be ignored. This allows for rule types like verifyImages or others which use image data to not block if the registry is temporarily down, useful in situations where images already exist on the nodes. +* **failurePolicy**: defines the API server behavior if the webhook fails to respond. Allowed values are "Ignore" or "Fail". Defaults to "Fail". Additionally, if set to "Ignore" will allow failing calls to image registries to be ignored. This allows for rule types like verifyImages or others which use image data to not block if the registry is temporarily down, useful in situations where images already exist on the nodes. This field is deprecated as of 1.13. Scheduled to be removed in a future version. Use `webhookConfiguration.failurePolicy` instead. * **generateExisting**: applicable to generate rules only. Controls whether Kyverno should evaluate the policy the moment it is created. @@ -25,11 +25,11 @@ A [policy](../kyverno-policies) contains one or more rules, and the following co * **useServerSideApply**: controls whether to use server-side apply for generate rules. Defaults to `false`. If set to `true`, Kyverno will use server-side apply when generating resources allowing other controllers to know which fields Kyverno owns. -* **validationFailureAction**: controls if a validation policy rule failure should block the admission review request (`Enforce`) or allow (`Audit`) the admission review request and report the policy failure in a policy report. Defaults to `Audit`. +* **validationFailureAction**: controls if a validation policy rule failure should block the admission review request (`Enforce`) or allow (`Audit`) the admission review request and report the policy failure in a policy report. Defaults to `Audit`. This field is deprecated as of 1.13. Scheduled to be removed in a future version. Use `failureAction` under the validate rule instead. -* **validationFailureActionOverrides**: a ClusterPolicy attribute that specifies `validationFailureAction` Namespace-wise. It overrides `validationFailureAction` for the specified Namespaces. +* **validationFailureActionOverrides**: a ClusterPolicy attribute that specifies `validationFailureAction` Namespace-wise. It overrides `validationFailureAction` for the specified Namespaces. This field is deprecated as of 1.13. Scheduled to be removed in a future version. Use `failureActionOverrides` under the validate rule instead. -* **webhookTimeoutSeconds**: specifies the maximum time in seconds allowed to apply this policy. The default timeout is 10s. The value must be between 1 and 30 seconds. +* **webhookTimeoutSeconds**: specifies the maximum time in seconds allowed to apply this policy. The default timeout is 10s. The value must be between 1 and 30 seconds. This field is deprecated as of 1.13. Scheduled to be removed in a future version. Use `webhookConfiguration.timeoutSeconds` instead. {{% alert title="Tip" color="info" %}} Use `kubectl explain policy.spec` for command-line help on the policy schema. diff --git a/content/en/docs/writing-policies/preconditions.md b/content/en/docs/writing-policies/preconditions.md index cb1b6c3be..a4539b33c 100644 --- a/content/en/docs/writing-policies/preconditions.md +++ b/content/en/docs/writing-policies/preconditions.md @@ -101,7 +101,6 @@ kind: ClusterPolicy metadata: name: any-all-preconditions spec: - validationFailureAction: Enforce background: false rules: - name: any-all-rule @@ -119,6 +118,7 @@ spec: operator: Equals value: busybox validate: + failureAction: Enforce message: "Busybox must be used based on this label combination." pattern: spec: @@ -140,7 +140,6 @@ kind: ClusterPolicy metadata: name: any-all-preconditions spec: - validationFailureAction: Enforce background: false rules: - name: any-all-rule @@ -165,6 +164,7 @@ spec: operator: Equals value: qa validate: + failureAction: Enforce message: "Foxes must be used based on this label combination." pattern: spec: @@ -214,7 +214,6 @@ kind: ClusterPolicy metadata: name: resource-quantities spec: - validationFailureAction: Enforce background: false rules: - name: memory-limit diff --git a/content/en/docs/writing-policies/tips.md b/content/en/docs/writing-policies/tips.md index c51a5b5ad..ab87cf1b9 100644 --- a/content/en/docs/writing-policies/tips.md +++ b/content/en/docs/writing-policies/tips.md @@ -59,9 +59,9 @@ Depending on the level of detail needed, you may need to increase the log level. ## Validate -* When developing your `validate` policies, it's easiest to set `validationFailureAction: Enforce` so when testing you can see the results immediately without having to look at a report. +* When developing your `validate` policies, it's easiest to set `failureAction: Enforce` so when testing you can see the results immediately without having to look at a report. -* Before deploying into production, ensure you have `validationFailureAction: Audit` so the policy doesn't have unintended consequences. +* Before deploying into production, ensure you have `failureAction: Audit` so the policy doesn't have unintended consequences. * `validate` rules cannot counteract the other. For example, a rule written to ensure all images come from registry `reg.corp.com` and another rule written to ensure they do **not** come from `reg.corp.com` will effectively render all image pulls impossible and nothing will run. Where the rule is defined is irrelevant. diff --git a/content/en/docs/writing-policies/validate.md b/content/en/docs/writing-policies/validate.md index 8ec815eb9..1b3f4e9e8 100644 --- a/content/en/docs/writing-policies/validate.md +++ b/content/en/docs/writing-policies/validate.md @@ -5,7 +5,7 @@ description: > weight: 30 --- -Validation rules are probably the most common and practical types of rules you will be working with, and the main use case for admission controllers such as Kyverno. In a typical validation rule, one defines the mandatory properties with which a given resource should be created. When a new resource is created by a user or process, the properties of that resource are checked by Kyverno against the validate rule. If those properties are validated, meaning there is agreement, the resource is allowed to be created. If those properties are different, the creation is blocked. The behavior of how Kyverno responds to a failed validation check is determined by the `validationFailureAction` field. It can either be blocked (`Enforce`) or allowed yet recorded in a [policy report](../policy-reports/) (`Audit`). Validation rules in `Audit` mode can also be used to get a report on matching resources which violate the rule(s), both upon initial creation and when Kyverno initiates periodic scans of Kubernetes resources. Resources in violation of an existing rule placed in `Audit` mode will also surface in an event on the resource in question. +Validation rules are probably the most common and practical types of rules you will be working with, and the main use case for admission controllers such as Kyverno. In a typical validation rule, one defines the mandatory properties with which a given resource should be created. When a new resource is created by a user or process, the properties of that resource are checked by Kyverno against the validate rule. If those properties are validated, meaning there is agreement, the resource is allowed to be created. If those properties are different, the creation is blocked. The behavior of how Kyverno responds to a failed validation check is determined by the `failureAction` field. It can either be blocked (`Enforce`) or allowed yet recorded in a [policy report](../policy-reports/) (`Audit`). Validation rules in `Audit` mode can also be used to get a report on matching resources which violate the rule(s), both upon initial creation and when Kyverno initiates periodic scans of Kubernetes resources. Resources in violation of an existing rule placed in `Audit` mode will also surface in an event on the resource in question. To validate resource data, define a [pattern](#patterns) in the validation rule. For more advanced processing using tripartite expressions (key-operator-value), define a [deny](#deny-rules) element in the validation rule along with a set of conditions that control when to allow or deny the request. @@ -21,8 +21,6 @@ metadata: name: require-ns-purpose-label # The `spec` defines properties of the policy. spec: - # The `validationFailureAction` tells Kyverno if the resource being validated should be allowed but reported (`Audit`) or blocked (`Enforce`). - validationFailureAction: Enforce # The `rules` is one or more rules which must be true. rules: - name: require-ns-purpose-label @@ -34,6 +32,8 @@ spec: - Namespace # The `validate` statement tries to positively check what is defined. If the statement, when compared with the requested resource, is true, it is allowed. If false, it is blocked. validate: + # The `failureAction` tells Kyverno if the resource being validated should be allowed but reported (`Audit`) or blocked (`Enforce`). + failureAction: Enforce # The `message` is what gets displayed to a user if this rule fails validation. message: "You must have label `purpose` with value `production` set on all new namespaces." # The `pattern` object defines what pattern will be checked in the resource. In this case, it is looking for `metadata.labels` with `purpose=production`. @@ -79,13 +79,17 @@ require-ns-purpose-label: Change the `development` value to `production` and try again. Kyverno permits creation of your new Namespace resource. -## Validation Failure Action +## Failure Action -The `validationFailureAction` attribute controls admission control behaviors for resources that are not compliant with a policy. If the value is set to `Enforce`, resource creation or updates are blocked when the resource does not comply. When the value is set to `Audit`, a policy violation is logged in a `PolicyReport` or `ClusterPolicyReport` but the resource creation or update is allowed. For preexisting resources which violate a newly-created policy set to `Enforce` mode, Kyverno will allow subsequent updates to those resources which continue to violate the policy as a way to ensure no existing resources are impacted. However, should a subsequent update to the violating resource(s) make them compliant, any further updates which would produce a violation are blocked. This behaviour can be disabled using `validate.allowExistingViolations`, when `validate.allowExistingViolations` is set to `false` in an `Enforce` mode validate rule, updates to preexisting resources which violate that rule will be blocked. +The `FailureAction` attribute controls admission control behaviors for resources that are not compliant with a policy. If the value is set to `Enforce`, resource creation or updates are blocked when the resource does not comply. When the value is set to `Audit`, a policy violation is logged in a `PolicyReport` or `ClusterPolicyReport` but the resource creation or update is allowed. For preexisting resources which violate a newly-created policy set to `Enforce` mode, Kyverno will allow subsequent updates to those resources which continue to violate the policy as a way to ensure no existing resources are impacted. However, should a subsequent update to the violating resource(s) make them compliant, any further updates which would produce a violation are blocked. This behaviour can be disabled using `validate.allowExistingViolations`, when `validate.allowExistingViolations` is set to `false` in an `Enforce` mode validate rule, updates to preexisting resources which violate that rule will be blocked. -## Validation Failure Action Overrides +{{% alert title="Warning" color="warning" %}} +The field `spec.validationFailureAction` is deprecated and will be removed in a future release. Instead, use `spec.rules[*].validate[*].failureAction`. +{{% /alert %}} -Using `validationFailureActionOverrides`, you can specify which actions to apply per Namespace. This attribute is only available for ClusterPolicies. +## Failure Action Overrides + +Using `failureActionOverrides`, you can specify which actions to apply per Namespace. This attribute is only available for ClusterPolicies. ```yaml apiVersion: kyverno.io/v1 @@ -93,14 +97,6 @@ kind: ClusterPolicy metadata: name: check-label-app spec: - validationFailureAction: Audit - validationFailureActionOverrides: - - action: Enforce # Action to apply - namespaces: # List of affected namespaces - - default - - action: Audit - namespaces: - - test rules: - name: check-label-app match: @@ -109,6 +105,14 @@ spec: kinds: - Pod validate: + failureAction: Audit + failureActionOverrides: + - action: Enforce # Action to apply + namespaces: # List of affected namespaces + - default + - action: Audit + namespaces: + - test message: "The label `app` is required." pattern: metadata: @@ -116,7 +120,11 @@ spec: app: "?*" ``` -In the above policy, for Namespace `default`, `validationFailureAction` is set to `Enforce` and for Namespace `test`, it's set to `Audit`. For all other Namespaces, the action defaults to the `validationFailureAction` field. +In the above policy, for Namespace `default`, `failureAction` is set to `Enforce` and for Namespace `test`, it's set to `Audit`. For all other Namespaces, the action defaults to the `failureAction` field. + +{{% alert title="Warning" color="warning" %}} +The field `spec.validationFailureActionOverrides` is deprecated and will be removed in a future release. Instead, use `spec.rules[*].validate[*].failureActionOverrides`. +{{% /alert %}} ## Patterns @@ -146,7 +154,6 @@ kind: ClusterPolicy metadata: name: all-containers-need-requests-and-limits spec: - validationFailureAction: Enforce rules: - name: check-container-resources match: @@ -155,6 +162,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: "All containers must have CPU and memory resource requests and limits defined." pattern: spec: @@ -181,7 +189,6 @@ kind: ClusterPolicy metadata: name: check-label-app spec: - validationFailureAction: Enforce rules: - name: check-label-app match: @@ -192,6 +199,7 @@ spec: - StatefulSet - DaemonSet validate: + failureAction: Enforce message: "The label `app` is required." pattern: spec: @@ -235,7 +243,6 @@ kind: ClusterPolicy metadata: name: validate spec: - validationFailureAction: Enforce rules: - name: validate-replica-count match: @@ -244,6 +251,7 @@ spec: kinds: - Deployment validate: + failureAction: Enforce message: "Replica count for a Deployment must be greater than or equal to 2." pattern: spec: @@ -274,7 +282,6 @@ kind: ClusterPolicy metadata: name: conditional-anchor-dockersock spec: - validationFailureAction: Enforce background: false rules: - name: conditional-anchor-dockersock @@ -284,6 +291,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: "If a hostPath volume exists and is set to `/var/run/docker.sock`, the label `allow-docker` must equal `true`." pattern: metadata: @@ -305,7 +313,6 @@ kind: ClusterPolicy metadata: name: equality-anchor-no-dockersock spec: - validationFailureAction: Enforce background: false rules: - name: equality-anchor-no-dockersock @@ -315,6 +322,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: "If a hostPath volume exists, it must not be set to `/var/run/docker.sock`." pattern: =(spec): @@ -341,7 +349,6 @@ kind: ClusterPolicy metadata: name: existence-anchor-at-least-one-nginx spec: - validationFailureAction: Enforce rules: - name: existence-anchor-at-least-one-nginx match: @@ -350,6 +357,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: "At least one container must use the image `nginx:latest`." pattern: spec: @@ -381,7 +389,6 @@ kind: ClusterPolicy metadata: name: sample spec: - validationFailureAction: Enforce rules: - name: check-container-image match: @@ -390,6 +397,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: Images coming from corp.reg.com must use the correct imagePullSecret. pattern: spec: @@ -438,7 +446,6 @@ metadata: name: require-run-as-non-root spec: background: true - validationFailureAction: Enforce rules: - name: check-containers match: @@ -447,6 +454,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce message: >- Running as root is not allowed. The fields spec.securityContext.runAsNonRoot, spec.containers[*].securityContext.runAsNonRoot, and @@ -542,7 +550,6 @@ kind: ClusterPolicy metadata: name: deny-deletes spec: - validationFailureAction: Enforce background: false rules: - name: block-deletes-for-kyverno-resources @@ -557,6 +564,7 @@ spec: - clusterRoles: - cluster-admin validate: + failureAction: Enforce message: "Deleting {{request.oldObject.kind}}/{{request.oldObject.metadata.name}} is not allowed" deny: conditions: @@ -576,7 +584,6 @@ kind: ClusterPolicy metadata: name: block-updates-to-custom-resource spec: - validationFailureAction: Enforce background: false rules: - name: block-updates-to-custom-resource @@ -594,6 +601,7 @@ spec: - custom-controller:* - cluster-admin validate: + failureAction: Enforce message: "Modifying or deleting this custom resource is forbidden." deny: {} ``` @@ -608,7 +616,6 @@ kind: ClusterPolicy metadata: name: deny-netpol-changes spec: - validationFailureAction: Enforce background: false rules: - name: deny-netpol-changes @@ -624,6 +631,7 @@ spec: - clusterRoles: - cluster-admin validate: + failureAction: Enforce message: "Changing default network policies is not allowed." deny: {} ``` @@ -664,7 +672,6 @@ kind: ClusterPolicy metadata: name: check-images spec: - validationFailureAction: Enforce background: false rules: - name: check-registry @@ -679,6 +686,7 @@ spec: operator: NotEquals value: DELETE validate: + failureAction: Enforce message: "unknown registry" foreach: - list: "request.object.spec.initContainers" @@ -703,7 +711,6 @@ kind: ClusterPolicy metadata: name: check-ingress spec: - validationFailureAction: Enforce background: false rules: - name: check-tls-secret-host @@ -713,6 +720,7 @@ spec: kinds: - Ingress validate: + failureAction: Enforce message: "All TLS hosts must use a domain of old.com." foreach: - list: request.object.spec.tls[] @@ -816,7 +824,6 @@ kind: ClusterPolicy metadata: name: validate-secrets spec: - validationFailureAction: Enforce background: true rules: - name: validate-secrets @@ -826,6 +833,7 @@ spec: kinds: - Secret validate: + failureAction: Enforce manifests: attestors: - count: 1 @@ -873,7 +881,6 @@ kind: ClusterPolicy metadata: name: validate-deployment spec: - validationFailureAction: Enforce background: true rules: - name: validate-deployment @@ -883,6 +890,7 @@ spec: kinds: - Deployment validate: + failureAction: Enforce manifests: attestors: - count: 1 @@ -937,7 +945,6 @@ metadata: name: psa spec: background: true - validationFailureAction: Enforce rules: - name: baseline match: @@ -946,6 +953,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce podSecurity: level: baseline version: latest @@ -990,7 +998,6 @@ metadata: name: psa spec: background: true - validationFailureAction: Enforce rules: - name: restricted match: @@ -999,6 +1006,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce podSecurity: level: restricted version: latest @@ -1045,7 +1053,6 @@ metadata: name: psa spec: background: true - validationFailureAction: Enforce rules: - name: baseline match: @@ -1054,6 +1061,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce podSecurity: level: baseline version: latest @@ -1086,7 +1094,6 @@ metadata: name: psa spec: background: true - validationFailureAction: Enforce rules: - name: restricted match: @@ -1095,6 +1102,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce podSecurity: level: restricted version: latest @@ -1156,7 +1164,6 @@ metadata: name: psa spec: background: true - validationFailureAction: Enforce rules: - name: restricted match: @@ -1165,6 +1172,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce podSecurity: level: restricted version: latest @@ -1214,7 +1222,6 @@ metadata: name: psa spec: background: true - validationFailureAction: Enforce rules: - name: baseline match: @@ -1223,6 +1230,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce podSecurity: level: baseline version: latest @@ -1279,7 +1287,6 @@ metadata: name: psa spec: background: true - validationFailureAction: Enforce rules: - name: baseline match: @@ -1288,6 +1295,7 @@ spec: kinds: - Pod validate: + failureAction: Enforce podSecurity: level: baseline version: latest @@ -1388,7 +1396,6 @@ kind: ClusterPolicy metadata: name: check-deployment-replicas spec: - validationFailureAction: Enforce background: false rules: - name: check-deployment-replicas @@ -1398,13 +1405,14 @@ spec: kinds: - Deployment validate: + failureAction: Enforce cel: expressions: - expression: "object.spec.replicas < 4" message: "Deployment spec.replicas must be less than 4." ``` -The `cel.expressions` contains CEL expressions which use the [Common Expression Language (CEL)](https://github.com/google/cel-spec) to validate the request. If an expression evaluates to false, the validation check is enforced according to the `spec.validationFailureAction` field. +The `cel.expressions` contains CEL expressions which use the [Common Expression Language (CEL)](https://github.com/google/cel-spec) to validate the request. If an expression evaluates to false, the validation check is enforced according to the `validate[*].failureAction` field. {{% alert title="Note" color="info" %}} You can quickly test CEL expressions in the [CEL Playground](https://playcel.undistro.io/). @@ -1429,7 +1437,6 @@ kind: ClusterPolicy metadata: name: check-statefulset-namespace spec: - validationFailureAction: Enforce background: false rules: - name: statefulset-namespace @@ -1439,6 +1446,7 @@ spec: kinds: - StatefulSet validate: + failureAction: Enforce cel: expressions: - expression: "namespaceObject.metadata.name == 'production'" @@ -1530,7 +1538,6 @@ kind: ClusterPolicy metadata: name: check-deployment-replicas spec: - validationFailureAction: Enforce background: false rules: - name: check-deployment-replicas @@ -1540,6 +1547,7 @@ spec: kinds: - Deployment validate: + failureAction: Enforce cel: paramKind: apiVersion: rules.example.com/v1 @@ -1643,7 +1651,6 @@ kind: ClusterPolicy metadata: name: image-matches-namespace-environment.policy.example.com spec: - validationFailureAction: Enforce background: false rules: - name: image-matches-namespace-environment @@ -1653,6 +1660,7 @@ spec: kinds: - Deployment validate: + failureAction: Enforce cel: variables: - name: environment @@ -1765,7 +1773,6 @@ kind: ClusterPolicy metadata: name: disallow-host-path spec: - validationFailureAction: Enforce background: false rules: - name: host-path @@ -1775,6 +1782,7 @@ spec: kinds: - Deployment validate: + failureAction: Enforce cel: expressions: - expression: "!has(object.spec.template.spec.volumes) || object.spec.template.spec.volumes.all(volume, !has(volume.hostPath))" diff --git a/content/en/docs/writing-policies/variables.md b/content/en/docs/writing-policies/variables.md index 657fc00ea..0b8369ed4 100644 --- a/content/en/docs/writing-policies/variables.md +++ b/content/en/docs/writing-policies/variables.md @@ -34,7 +34,6 @@ Kyverno policy definitions can refer to other fields in the policy definition as In order for Kyverno to refer to these existing values in a manifest, it uses the notation `$(./../key_1/key_2)`. This may look familiar as it is essentially the same way Linux/Unix systems refer to relative paths. For example, consider the policy manifest snippet below. ```yaml -validationFailureAction: Enforce rules: - name: check-tcpSocket match: @@ -43,6 +42,7 @@ rules: kinds: - Pod validate: + failureAction: Enforce message: "Port number for the livenessProbe must be less than that of the readinessProbe." pattern: spec: diff --git a/content/en/docs/writing-policies/verify-images/notary/_index.md b/content/en/docs/writing-policies/verify-images/notary/_index.md index 1d1e816e4..d3832233a 100644 --- a/content/en/docs/writing-policies/verify-images/notary/_index.md +++ b/content/en/docs/writing-policies/verify-images/notary/_index.md @@ -78,9 +78,9 @@ kind: ClusterPolicy metadata: name: check-image-notary spec: - validationFailureAction: Enforce - webhookTimeoutSeconds: 30 - failurePolicy: Fail + webhookConfiguration: + failurePolicy: Fail + timeoutSeconds: 30 rules: - name: verify-signature-notary match: @@ -92,6 +92,7 @@ spec: - type: Notary imageReferences: - "ghcr.io/kyverno/test-verify-image*" + failureAction: Enforce attestors: - count: 1 entries: @@ -200,9 +201,9 @@ kind: ClusterPolicy metadata: name: check-image-attestation spec: - validationFailureAction: Enforce - webhookTimeoutSeconds: 30 - failurePolicy: Fail + webhookConfiguration: + failurePolicy: Fail + timeoutSeconds: 30 rules: - name: verify-attestation-notary match: @@ -219,6 +220,7 @@ spec: - type: Notary imageReferences: - "ghcr.io/kyverno/test-verify-image*" + failureAction: Enforce attestations: - type: sbom/cyclone-dx attestors: diff --git a/content/en/docs/writing-policies/verify-images/sigstore/_index.md b/content/en/docs/writing-policies/verify-images/sigstore/_index.md index 01dfc66d3..5828bf6b5 100644 --- a/content/en/docs/writing-policies/verify-images/sigstore/_index.md +++ b/content/en/docs/writing-policies/verify-images/sigstore/_index.md @@ -23,10 +23,10 @@ kind: ClusterPolicy metadata: name: check-image spec: - validationFailureAction: Enforce + webhookConfiguration: + failurePolicy: Fail + timeoutSeconds: 30 background: false - webhookTimeoutSeconds: 30 - failurePolicy: Fail rules: - name: check-image match: @@ -37,6 +37,7 @@ spec: verifyImages: - imageReferences: - "ghcr.io/kyverno/test-verify-image*" + failureAction: Enforce attestors: - count: 1 entries: @@ -142,9 +143,9 @@ kind: ClusterPolicy metadata: name: exclude-refs spec: - validationFailureAction: Enforce - webhookTimeoutSeconds: 30 - failurePolicy: Fail + webhookConfiguration: + failurePolicy: Fail + timeoutSeconds: 30 rules: - name: exclude-refs match: @@ -157,6 +158,7 @@ spec: - "ghcr.io/*" skipImageReferences: - "ghcr.io/trusted/*" + failureAction: Enforce attestors: - count: 1 entries: @@ -242,10 +244,10 @@ kind: ClusterPolicy metadata: name: attest-code-review spec: - validationFailureAction: Enforce + webhookConfiguration: + failurePolicy: Fail + timeoutSeconds: 30 background: false - webhookTimeoutSeconds: 30 - failurePolicy: Fail rules: - name: attest match: @@ -256,6 +258,7 @@ spec: verifyImages: - imageReferences: - "registry.io/org/app*" + failureAction: Enforce attestations: - predicateType: https://example.com/CodeReview/v1 attestors: @@ -345,7 +348,6 @@ kind: ClusterPolicy metadata: name: check-image spec: - validationFailureAction: Enforce rules: - name: verify-signature match: @@ -356,6 +358,7 @@ spec: verifyImages: - imageReferences: - "ghcr.io/kyverno/test-verify-image:signed-cert" + failureAction: Enforce attestors: - entries: - certificates: @@ -416,7 +419,6 @@ kind: ClusterPolicy metadata: name: check-image spec: - validationFailureAction: Enforce rules: - name: verify-signature match: @@ -427,6 +429,7 @@ spec: verifyImages: - imageReferences: - "ghcr.io/kyverno/test-verify-image:signed-cert" + failureAction: Enforce attestors: - entries: - certificates: @@ -485,8 +488,8 @@ kind: ClusterPolicy metadata: name: check-image-keyless spec: - validationFailureAction: Enforce - webhookTimeoutSeconds: 30 + webhookConfiguration: + timeoutSeconds: 30 rules: - name: check-image-keyless match: @@ -497,6 +500,7 @@ spec: verifyImages: - imageReferences: - "ghcr.io/kyverno/test-verify-image:signed-keyless" + failureAction: Enforce attestors: - entries: - keyless: @@ -615,10 +619,10 @@ kind: ClusterPolicy metadata: name: check-image spec: - validationFailureAction: Enforce background: false - webhookTimeoutSeconds: 30 - failurePolicy: Fail + webhookConfiguration: + failurePolicy: Fail + timeoutSeconds: 30 rules: - name: check-image match: @@ -629,6 +633,7 @@ spec: verifyImages: - imageReferences: - ghcr.io/myorg/myimage* + failureAction: Enforce attestors: - entries: - keys: @@ -868,7 +873,6 @@ kind: ClusterPolicy metadata: name: signed-task-image spec: - validationFailureAction: Enforce rules: - name: check-signature match: @@ -885,6 +889,7 @@ spec: verifyImages: - imageReferences: - "*" + failureAction: Enforce required: false attestors: - entries: @@ -904,7 +909,6 @@ kind: ClusterPolicy metadata: name: signed-pipeline-bundle spec: - validationFailureAction: Enforce rules: - name: check-signature match: @@ -921,6 +925,7 @@ spec: verifyImages: - imageReferences: - "*" + failureAction: Enforce attestors: - entries: - keys: