From b692d4ef29c5d901c182cef47f0926c7ca8853f0 Mon Sep 17 00:00:00 2001 From: Mariam Fahmy Date: Mon, 28 Oct 2024 02:16:55 +0300 Subject: [PATCH 01/13] docs: add --dumpPatches flag (#1386) Signed-off-by: Mariam Fahmy --- content/en/docs/installation/customization.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/en/docs/installation/customization.md b/content/en/docs/installation/customization.md index a610105d6..aae4919ee 100644 --- a/content/en/docs/installation/customization.md +++ b/content/en/docs/installation/customization.md @@ -365,10 +365,11 @@ The following flags can be used to control the advanced behavior of the various | `cleanupServerPort` (C) | 9443 | Defines the port used by the cleanup server. Usually changed in tandem with `webhookServerPort`.| | `clientRateLimitBurst` (ABCR) | 300 | Configures the maximum burst for throttling. Uses the client default if zero. | | `clientRateLimitQPS` (ABCR) | 300 | Configures the maximum QPS to the API server from Kyverno. Uses the client default if zero. | -| `eventsRateLimitBurst` (ABCR) | 2000 | Configures the maximum burst for throttling for events. Uses the client default if zero. | -| `eventsRateLimitQPS` (ABCR) | 1000 | Configures the maximum QPS to the API server from Kyverno for events. Uses the client default if zero. | | `disableMetrics` (ABCR) | false | Specifies whether to enable exposing the metrics. | | `dumpPayload` (AC) | false | Toggles debug mode. When debug mode is enabled, the full AdmissionReview payload is logged. Additionally, resources of kind Secret are redacted. Should only be used in policy development or troubleshooting scenarios, not left perpetually enabled. | +| `dumpPatches` (A) | false | Toggles debug mode. When debug mode is enabled, the full patch payload is logged | +| `eventsRateLimitBurst` (ABCR) | 2000 | Configures the maximum burst for throttling for events. Uses the client default if zero. | +| `eventsRateLimitQPS` (ABCR) | 1000 | Configures the maximum QPS to the API server from Kyverno for events. Uses the client default if zero. | | `enableConfigMapCaching` (ABR) | true | Enables the ConfigMap caching feature. | | `enableDeferredLoading` (A) | true | Enables deferred (lazy) loading of variables (1.10.1+). Set to `false` to disable deferred loading of variables which was the default behavior in versions < 1.10.0. | | `enablePolicyException` (ABR) | true | Set to `true` to enable the [PolicyException capability](../writing-policies/exceptions.md). | From 1ba849a81fdbabffc2f561bbdd5ebcf29e5dc512 Mon Sep 17 00:00:00 2001 From: Vishal Choudhary Date: Mon, 28 Oct 2024 04:48:36 +0530 Subject: [PATCH 02/13] feat(docs): regexp support in cosign keyless verification (#1327) * feat(docs): regexp support in cosign keyless verification Signed-off-by: Vishal Choudhary * fix: grammatical errors Signed-off-by: Vishal Choudhary --------- Signed-off-by: Vishal Choudhary --- .../verify-images/sigstore/_index.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) 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..4703703b8 100644 --- a/content/en/docs/writing-policies/verify-images/sigstore/_index.md +++ b/content/en/docs/writing-policies/verify-images/sigstore/_index.md @@ -506,6 +506,35 @@ spec: url: https://rekor.sigstore.dev ``` +The following policy verifies an image signed using [keyless signing](https://docs.sigstore.dev/signing/overview/) with regular expressions for subject and issuer: + +```yaml +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: check-image-keyless +spec: + validationFailureAction: Enforce + webhookTimeoutSeconds: 30 + rules: + - name: check-image-keyless + match: + any: + - resources: + kinds: + - Pod + verifyImages: + - imageReferences: + - "ghcr.io/kyverno/test-verify-image:signed-keyless" + attestors: + - entries: + - keyless: + subjectRegExp: https://github\.com/.+ + issuerRegExp: https://token\.actions\.githubusercontent.+ + rekor: + url: https://rekor.sigstore.dev +``` + ### Keyless signing To sign images using the keyless flow, use the following cosign command: @@ -539,6 +568,7 @@ attestors: url: https://rekor.sigstore.dev ``` + ## Using a Key Management Service (KMS) Kyverno and Cosign support using Key Management Services (KMS) such as AWS, GCP, Azure, and HashiCorp Vault. This integration allows referencing public and private keys using a URI syntax, instead of embedding the key directly in the policy. From 6f1653f7c919c88fc94839b36b3201023f126d8c Mon Sep 17 00:00:00 2001 From: Mariam Fahmy Date: Mon, 28 Oct 2024 02:19:42 +0300 Subject: [PATCH 03/13] docs: add warning for the validationFailureAction deprecated field (#1345) 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 7472181e9..04b775050 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 51382bc27..08ddafe6b 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`, `mutate`, `generate` 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 8609aace9..e98a2dfbe 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. This field is deprecated as of 1.13. Scheduled to be removed in a future version. Use `generateExisting` under the generate rule instead. @@ -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 4b1ab639e..f77f75496 100644 --- a/content/en/docs/writing-policies/variables.md +++ b/content/en/docs/writing-policies/variables.md @@ -36,7 +36,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: @@ -45,6 +44,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 4703703b8..971dbdc09 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: @@ -645,10 +649,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: @@ -659,6 +663,7 @@ spec: verifyImages: - imageReferences: - ghcr.io/myorg/myimage* + failureAction: Enforce attestors: - entries: - keys: @@ -898,7 +903,6 @@ kind: ClusterPolicy metadata: name: signed-task-image spec: - validationFailureAction: Enforce rules: - name: check-signature match: @@ -915,6 +919,7 @@ spec: verifyImages: - imageReferences: - "*" + failureAction: Enforce required: false attestors: - entries: @@ -934,7 +939,6 @@ kind: ClusterPolicy metadata: name: signed-pipeline-bundle spec: - validationFailureAction: Enforce rules: - name: check-signature match: @@ -951,6 +955,7 @@ spec: verifyImages: - imageReferences: - "*" + failureAction: Enforce attestors: - entries: - keys: From 86cd83f0f88d2198d283f9363d9cd07a49424b16 Mon Sep 17 00:00:00 2001 From: Ammar Yasser Date: Mon, 28 Oct 2024 02:21:32 +0300 Subject: [PATCH 04/13] docs: Show an example for selecting targets with labels (#1373) Signed-off-by: aerosouund --- content/en/docs/writing-policies/mutate.md | 28 ++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/content/en/docs/writing-policies/mutate.md b/content/en/docs/writing-policies/mutate.md index bfd9e7403..7a7763b2c 100644 --- a/content/en/docs/writing-policies/mutate.md +++ b/content/en/docs/writing-policies/mutate.md @@ -498,6 +498,34 @@ Installation of a mutate existing policy affects the `ValidatingWebhookConfigura When defining a list of `targets[]`, the fields `name` and `namespace` are not strictly required but encouraged. If omitted, it implies a wildcard (`"*"`) for the omitted field which can have unintended impact on other resources. +Target resources can also be selected using label selectors. The below policy example shows a policy that matches `ConfigMaps` with a label `should-match=yes` on `Secret` events. + +```yaml +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: mutate-existing-configmap +spec: + rules: + - name: mutate-configmap-on-secret-event + match: + any: + - resources: + kinds: + - Secret + mutate: + targets: + - apiVersion: v1 + kind: ConfigMap + selector: + matchLabels: + should-match: 'yes' + patchStrategicMerge: + metadata: + labels: + foo: bar +``` + In order to more precisely control the target resources, mutate existing rules support both [context variables](external-data-sources.md) and [preconditions](preconditions.md). Preconditions which occur inside the `targets[]` array must use the target prefix as described [below](#variables-referencing-target-resources). This sample below illustrates how to combine preconditions and conditional anchors within `targets[]` to precisely select the desired existing resources for mutation. This policy restarts existing Deployments if they are consuming a Secret that has been updated assigned label `kyverno.io/watch: "true"` AND have a name beginning with `testing-`. From e2f15333b1b99f8ae5a46f1f4979bd38964e84f1 Mon Sep 17 00:00:00 2001 From: Arturo Borrero Gonzalez Date: Mon, 28 Oct 2024 00:22:14 +0100 Subject: [PATCH 05/13] =?UTF-8?q?docs:=20installation:=20scaling:=20mentio?= =?UTF-8?q?n=20kubernetes=20core=20components=20resou=E2=80=A6=20(#1295)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs: installation: scaling: mention kubernetes core components resources footprint Introduce a mention to how many kyverno resources may impact the kubernetes core components regarding their resources footprint. See also: https://github.com/kyverno/kyverno/issues/10458 Signed-off-by: Arturo Borrero Gonzalez Co-authored-by: Arturo Borrero Gonzalez Co-authored-by: Jim Bugwadia --- content/en/docs/installation/scaling.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/content/en/docs/installation/scaling.md b/content/en/docs/installation/scaling.md index a68d9b55a..219233e38 100644 --- a/content/en/docs/installation/scaling.md +++ b/content/en/docs/installation/scaling.md @@ -81,3 +81,10 @@ API requests, operations, and activities which match corresponding Kyverno rules | DELETE | ConfigMap | | 1 | These figures were captured using K3d v5.4.9 on Kubernetes v1.26.2 and Kyverno 1.10.0-alpha.2 with a 3-replica admission controller. When testing against KinD, there may be one less DELETE AdmissionReview for Pod-related operations. + +### Kubernetes api-server and etcd resource footprint + +In clusters with many Kyverno policy resources, the resource footprint of some core Kubernetes components may be affected, in particular the kube-apiserver and etcd. + +For example, if you create several thousand Kyverno policy resources, double check that the kube-apiserver pods have head room to increase its memory allocations, otherwise +the cluster may crash entirely. From 647765ba0381a4f8f08b511b9684d03826a1f520 Mon Sep 17 00:00:00 2001 From: Mariam Fahmy Date: Mon, 28 Oct 2024 02:23:04 +0300 Subject: [PATCH 06/13] docs: use v2 for cleanup policies and exceptions (#1372) Signed-off-by: Mariam Fahmy --- content/en/docs/kyverno-cli/usage/apply.md | 2 +- content/en/docs/kyverno-cli/usage/test.md | 2 +- content/en/docs/writing-policies/cleanup.md | 2 +- content/en/docs/writing-policies/exceptions.md | 8 ++++---- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/content/en/docs/kyverno-cli/usage/apply.md b/content/en/docs/kyverno-cli/usage/apply.md index 66bfe29f2..1e1bc1e5c 100644 --- a/content/en/docs/kyverno-cli/usage/apply.md +++ b/content/en/docs/kyverno-cli/usage/apply.md @@ -724,7 +724,7 @@ spec: Policy Exception manifest (`exception.yaml`): ```yaml -apiVersion: kyverno.io/v2beta1 +apiVersion: kyverno.io/v2 kind: PolicyException metadata: name: container-exception diff --git a/content/en/docs/kyverno-cli/usage/test.md b/content/en/docs/kyverno-cli/usage/test.md index 04b775050..f60590e49 100644 --- a/content/en/docs/kyverno-cli/usage/test.md +++ b/content/en/docs/kyverno-cli/usage/test.md @@ -568,7 +568,7 @@ spec: Policy Exception manifest (`delta-exception.yaml`): ```yaml -apiVersion: kyverno.io/v2beta1 +apiVersion: kyverno.io/v2 kind: PolicyException metadata: name: delta-exception diff --git a/content/en/docs/writing-policies/cleanup.md b/content/en/docs/writing-policies/cleanup.md index 8fba6ad83..ac858b68d 100644 --- a/content/en/docs/writing-policies/cleanup.md +++ b/content/en/docs/writing-policies/cleanup.md @@ -18,7 +18,7 @@ Since cleanup policies always operate against existing resources in a cluster, p An example ClusterCleanupPolicy is shown below. This cleanup policy removes Deployments which have the label `canremove: "true"` if they have less than two replicas on a schedule of every 5 minutes. ```yaml -apiVersion: kyverno.io/v2beta1 +apiVersion: kyverno.io/v2 kind: ClusterCleanupPolicy metadata: name: cleandeploy diff --git a/content/en/docs/writing-policies/exceptions.md b/content/en/docs/writing-policies/exceptions.md index 0b16c5989..fdb51aa02 100644 --- a/content/en/docs/writing-policies/exceptions.md +++ b/content/en/docs/writing-policies/exceptions.md @@ -59,7 +59,7 @@ Auto-generated rules for Pod controllers must be specified along with the Pod co {{% /alert %}} ```yaml -apiVersion: kyverno.io/v2beta1 +apiVersion: kyverno.io/v2 kind: PolicyException metadata: name: delta-exception @@ -198,7 +198,7 @@ spec: In this use case, all Pods in the `delta` Namespace need to run as a root. A PolicyException can be used to exempt all Pods whose Namespace is `delta` from the policy by excluding the `runAsNonRoot` control. ```yaml -apiVersion: kyverno.io/v2beta1 +apiVersion: kyverno.io/v2 kind: PolicyException metadata: name: pod-security-exception @@ -247,7 +247,7 @@ PolicyExceptions `podSecurity{}` block has the same functionality as the [valida For example, the following PolicyException exempts the containers running either the `nginx` or `redis` image from following the Capabilities control. ```yaml -apiVersion: kyverno.io/v2beta1 +apiVersion: kyverno.io/v2 kind: PolicyException metadata: name: pod-security-exception @@ -278,7 +278,7 @@ In this case, the `podSecurity.restrictedField` can be used to enforce the entir The following PolicyException grants an exemption to the `initContainers` that use Istio or Linkerd images, allowing them to bypass the `Capabilities` control. This is achieved by permitting the values of `NET_ADMIN` and `NET_RAW` in the `securityContext.capabilities.add` field. ```yaml -apiVersion: kyverno.io/v2beta1 +apiVersion: kyverno.io/v2 kind: PolicyException metadata: name: pod-security-exception From 9d433cea6924ab36de11d8489a2186fee5ab2701 Mon Sep 17 00:00:00 2001 From: Jim Bugwadia Date: Sun, 27 Oct 2024 23:01:52 -0700 Subject: [PATCH 07/13] update products (#1393) * update products Signed-off-by: Jim Bugwadia * fix link Signed-off-by: Jim Bugwadia --------- Signed-off-by: Jim Bugwadia --- .../verify-images/sigstore/_index.md | 2 +- content/en/support/aws/_index.md | 10 ---------- content/en/support/redhat/_index.md | 13 ------------- 3 files changed, 1 insertion(+), 24 deletions(-) delete mode 100644 content/en/support/aws/_index.md delete mode 100644 content/en/support/redhat/_index.md 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 971dbdc09..5886bdda8 100644 --- a/content/en/docs/writing-policies/verify-images/sigstore/_index.md +++ b/content/en/docs/writing-policies/verify-images/sigstore/_index.md @@ -510,7 +510,7 @@ spec: url: https://rekor.sigstore.dev ``` -The following policy verifies an image signed using [keyless signing](https://docs.sigstore.dev/signing/overview/) with regular expressions for subject and issuer: +The following policy verifies an image signed using [keyless signing](https://docs.sigstore.dev/cosign/signing/overview/) with regular expressions for subject and issuer: ```yaml apiVersion: kyverno.io/v1 diff --git a/content/en/support/aws/_index.md b/content/en/support/aws/_index.md deleted file mode 100644 index 399b5e3f0..000000000 --- a/content/en/support/aws/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Amazon EKS" -linkTitle: "Amazon EKS" -description: "Managed Kubernetes on Amazon Web Services" -type: docs ---- - -Amazon Elastic Kubernetes Service (Amazon EKS) is a managed service that makes it easy for you to run Kubernetes on Amazon Web Services (AWS) without needing to install and operate your own Kubernetes clusters. - -The Nirmata Kyverno enterprise distribution and Kubernetes governance platform are available in the [AWS Marketplace](https://aws.amazon.com/marketplace/seller-profile?id=e3783cfb-7d53-4c0d-a30e-b7e8c9d21ece). diff --git a/content/en/support/redhat/_index.md b/content/en/support/redhat/_index.md deleted file mode 100644 index a52115952..000000000 --- a/content/en/support/redhat/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Red Hat OpenShift" -linkTitle: "Red Hat OpenShift" -description: "Kubernetes management platform" -type: docs ---- - -OpenShift is a family of containerization software products developed by Red Hat. Its flagship product is the OpenShift Container Platform — a hybrid cloud platform as a service built around Linux containers orchestrated and managed by Kubernetes on a foundation of Red Hat Enterprise Linux. - -Kyverno policy sets are supported as part of [Red Hat Advanced Cluster Management](https://access.redhat.com/products/red-hat-advanced-cluster-management-for-kubernetes) and [Red Hat OpenShift Platform Plus](https://www.redhat.com/en/technologies/cloud-computing/openshift/platform-plus). - -Additional details: -* [Red Hat Drives Greater Consistency and Management Across the Hybrid Cloud with Latest Version of OpenShift Platform Plus](https://www.redhat.com/en/about/press-releases/red-hat-drives-greater-consistency-and-management-across-the-hybrid-cloud-with-latest-version-of-openshift-platform-plus) From 16d64e44b8baf473fcac4082e86858d6d6398abb Mon Sep 17 00:00:00 2001 From: Jim Bugwadia Date: Sun, 27 Oct 2024 23:02:46 -0700 Subject: [PATCH 08/13] Docs for 1.13 upgrade (#1394) * document breaking changes Signed-off-by: Jim Bugwadia * document breaking changes Signed-off-by: Jim Bugwadia --------- Signed-off-by: Jim Bugwadia --- content/en/docs/installation/customization.md | 2 +- content/en/docs/installation/methods.md | 2 +- content/en/docs/installation/upgrading.md | 59 ++++++++++++++++++- 3 files changed, 60 insertions(+), 3 deletions(-) diff --git a/content/en/docs/installation/customization.md b/content/en/docs/installation/customization.md index aae4919ee..55c022030 100644 --- a/content/en/docs/installation/customization.md +++ b/content/en/docs/installation/customization.md @@ -203,7 +203,7 @@ kyverno:reports-controller:core | -- | -- {{% alert title="Note" color="info" %}} -The Kyverno admission, background, and reports controller have a role binding to the built-in `view` role. This allows these Kyverno controllers view access to most namespaced resources. You can customize this role during Helm installation using variables like `admissionController.rbac.viewRoleName`. +The Kyverno admission, background, and reports controller have a role binding to the built-in `view` role. This allows these Kyverno controllers view access to most namespaced resources. You can customize this role during Helm installation using the variables `admissionController.rbac.viewRoleName`, `backgroundController.rbac.viewRoleName`, and `reportsController.rbac.viewRoleName`. {{% /alert %}} #### Customizing Permissions diff --git a/content/en/docs/installation/methods.md b/content/en/docs/installation/methods.md index 5d57e84e6..0f7c06895 100644 --- a/content/en/docs/installation/methods.md +++ b/content/en/docs/installation/methods.md @@ -51,7 +51,7 @@ reportsController: replicas: 3 ``` -For all of the available values and their defaults, please see the Helm chart [README](https://github.com/kyverno/kyverno/tree/release-1.10/charts/kyverno). You should carefully inspect all available chart values and their defaults to determine what overrides, if any, are necessary to meet the particular needs of your production environment. +For all of the available values and their defaults, please see the Helm chart [README](https://github.com/kyverno/kyverno/tree/release-1.13/charts/kyverno). You should carefully inspect all available chart values and their defaults to determine what overrides, if any, are necessary to meet the particular needs of your production environment. {{% alert title="Note" color="warning" %}} All Kyverno installations require the admission controller be among the controllers deployed. For a highly-available installation, at least 2 or more replicas are required. Based on scalability requirements, and cluster topology, additional replicas can be configured for each controller. diff --git a/content/en/docs/installation/upgrading.md b/content/en/docs/installation/upgrading.md index 52c2e1818..864c73332 100644 --- a/content/en/docs/installation/upgrading.md +++ b/content/en/docs/installation/upgrading.md @@ -16,4 +16,61 @@ Direct upgrades from previous versions are not supported when using the YAML man ### Upgrade Kyverno with Helm -An upgrade from versions prior to Kyverno 1.10 to versions at 1.10 or higher using Helm requires manual intervention and cannot be performed via a direct upgrade process. Please see the 1.10 migration guide [here](https://github.com/kyverno/kyverno/blob/release-1.10/charts/kyverno/README.md#migrating-from-v2-to-v3) for more complete information. +An upgrade from versions prior to Kyverno 1.10 to versions at 1.10 or higher using Helm requires manual intervention and cannot be performed via a direct upgrade process. Please see the 1.10 migration guide [here](https://githubviewRoleName.com/kyverno/kyverno/blob/release-1.13/charts/kyverno/README.md#migrating-from-v2-to-v3) for more complete information. + + +## Upgrading to Kyverno v1.13 + +Kyverno version 1.13 contains the following breaking configuration changes: + +1. **Removal of wildcard permissions**: prior versions contained wildcard view permissions, which allowed Kyverno controllers to view all resources including secrets and other sensitive information. In 1.13 the wildcard view permission was removed and a role binding to the default `view` role was added. See the documentation section on [Role Based Access Controls](./customization.md#role-based-access-controls) for more details. This change will not impact policies during admission controls but may impact reports, and may impact users with mutate and generate policies on custom resources as the these controller may no longer be able to view these custom resources. + +To upgrade to 1.13 and continue to allow wildcard view permissions for all Kyverno controllers, use a Helm values file that grants these permissions as specified below: + +```yaml +admissionController: + clusterRole: + extraResources: + - apiGroups: + - '*' + resources: + - '*' + verbs: + - get + - list + - watch +backgroundController: + clusterRole: + extraResources: + - apiGroups: + - '*' + resources: + - '*' + verbs: + - get + - list + - watch +reportsController: + clusterRole: + extraResources: + - apiGroups: + - '*' + resources: + - '*' + verbs: + - get + - list + - watch +``` + +**NOTE**: using wildcard permissions is not recommended. Use explicit permissions instead. + +2. **Default exception settings**: the Helm chart values of the prior versions enabled exceptions by default for all namespaces. This creates a potential security issue. See **CVE-2024-48921** for more details. This change will impact users who were relying on policy exceptions to be enabled in all namespaces. + +To maintain backwards compatibility, you can configure the Helm chart values to allow the same settings as the prior version. To upgrade to 1.13 and continue to allow configuring exceptions in all namespaces, set the Helm value `features.policyExceptions.namespace` to `*`: + +```sh +helm upgrade kyverno kyverno/kyverno -n kyverno --set features.policyExceptions.enabled=true --set features.policyExceptions.namespace="*" +``` + +**NOTE**: limiting exceptions to a specific namespace is recommended. From 66ad8540d0509662ddd12d23735c9ccd103347a3 Mon Sep 17 00:00:00 2001 From: Mariam Fahmy Date: Mon, 28 Oct 2024 14:21:17 +0300 Subject: [PATCH 09/13] chore: add docs for disabling exceptions by default (#1395) Signed-off-by: Mariam Fahmy --- content/en/docs/installation/customization.md | 4 ++-- content/en/docs/writing-policies/exceptions.md | 5 +++++ 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/content/en/docs/installation/customization.md b/content/en/docs/installation/customization.md index 55c022030..6f9965fb9 100644 --- a/content/en/docs/installation/customization.md +++ b/content/en/docs/installation/customization.md @@ -372,11 +372,11 @@ The following flags can be used to control the advanced behavior of the various | `eventsRateLimitQPS` (ABCR) | 1000 | Configures the maximum QPS to the API server from Kyverno for events. Uses the client default if zero. | | `enableConfigMapCaching` (ABR) | true | Enables the ConfigMap caching feature. | | `enableDeferredLoading` (A) | true | Enables deferred (lazy) loading of variables (1.10.1+). Set to `false` to disable deferred loading of variables which was the default behavior in versions < 1.10.0. | -| `enablePolicyException` (ABR) | true | Set to `true` to enable the [PolicyException capability](../writing-policies/exceptions.md). | +| `enablePolicyException` (ABR) | false | Set to `true` to enable the [PolicyException capability](../writing-policies/exceptions.md). | | `enableReporting` (ABCR) | validate,mutate,mutateExisting,generate,imageVerify | Comma separated list to enables reporting for different rule types. (validate,mutate,mutateExisting,generate,imageVerify) | | `enableTracing` (ABCR) | false | Set to enable exposing traces. | | `enableTuf` (AR) | | Enable tuf for private sigstore deployments. | -| `exceptionNamespace` (ABR) | | Set to the name of a Namespace where [PolicyExceptions](../writing-policies/exceptions.md) will only be permitted. PolicyExceptions created in any other Namespace will throw a warning. If not set, PolicyExceptions from all Namespaces will be considered. Implies the `enablePolicyException` flag is set to `true`. Neither wildcards nor multiple Namespaces are currently accepted. | +| `exceptionNamespace` (ABR) | | Set to the name of a Namespace where [PolicyExceptions](../writing-policies/exceptions.md) will only be permitted. PolicyExceptions created in any other Namespace will throw a warning. If set to "*", PolicyExceptions from all Namespaces will be accepted. Note that wildcards and multiple Namespace entries are not supported. It is required if the `enablePolicyException` flag is set to true. | | `forceFailurePolicyIgnore` (A) | false | Set to force Failure Policy to `Ignore`. | | `generateValidatingAdmissionPolicy` (A) | false | Specifies whether to enable generating Kubernetes ValidatingAdmissionPolicies. | | `genWorkers` (B) | 10 | The number of workers for processing generate policies concurrently. | diff --git a/content/en/docs/writing-policies/exceptions.md b/content/en/docs/writing-policies/exceptions.md index fdb51aa02..0d6dd868c 100644 --- a/content/en/docs/writing-policies/exceptions.md +++ b/content/en/docs/writing-policies/exceptions.md @@ -5,6 +5,11 @@ description: > weight: 80 --- +{{% alert title="Warning" color="warning" %}} +PolicyExceptions are disabled by default. To enable them, set the `enablePolicyException` flag to `true`. When enabling PolicyExceptions, you must also specify which namespaces they can be used in by setting the `exceptionNamespace` flag. +For more information, see [Container Flags](../installation/customization.md#container-flags). +{{% /alert %}} + Although Kyverno policies contain multiple methods to provide fine-grained control as to which resources they act upon in the form of [`match`/`exclude` blocks](match-exclude.md#match-statements), [preconditions](preconditions.md) at multiple hierarchies, [anchors](validate.md#anchors), and more, all these mechanisms have in common that the resources which they are intended to exclude must occur in the same rule definition. This may be limiting in situations where policies may not be directly editable, or doing so imposes an operational burden. For example, in organizations where multiple teams must interact with the same cluster, a team responsible for policy authoring and administration may not be the same team responsible for submission of resources. In these cases, it can be advantageous to decouple the policy definition from certain exclusions. Additionally, there are often times where an organization or team must allow certain exceptions which would violate otherwise valid rules but on a one-time basis if the risks are known and acceptable. From 85408591ff34a24a5c7ceec5b768edc64e7485f1 Mon Sep 17 00:00:00 2001 From: Vishal Choudhary Date: Mon, 28 Oct 2024 21:13:17 +0530 Subject: [PATCH 10/13] feat: Documentation for TSA cert chain support for cosign in verify images rules (#1396) Signed-off-by: Vishal Choudhary --- .../verify-images/sigstore/_index.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) 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 5886bdda8..d6bcdd461 100644 --- a/content/en/docs/writing-policies/verify-images/sigstore/_index.md +++ b/content/en/docs/writing-policies/verify-images/sigstore/_index.md @@ -886,6 +886,86 @@ verifyImages: -----END PUBLIC KEY----- ``` +## Using a Custom TSA cert chain +Cosign accepts custom timestamping authorities during image signing. To verify images signed with custom TSA, Use `ctlog.tsaCertChain` field to provide cert chain of the custom TSA. + +```yaml +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: keyed-tsa-policy +spec: + background: false + failurePolicy: Fail + rules: + - match: + any: + - resources: + kinds: + - Pod + name: keyed-tsa-rule + verifyImages: + - attestors: + - entries: + - keys: + publicKeys: |- + -----BEGIN PUBLIC KEY----- + MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEstG5Xl7UxkQsmLUxdmS85HLgYBFy + c/P/oQ22iazkKm8P0sNlaZiaZC4TSEea3oh2Pim0+wxSubhKoK+7jq9Egg== + -----END PUBLIC KEY----- + ctlog: + tsaCertChain: |- + -----BEGIN CERTIFICATE----- + MIIH/zCCBeegAwIBAgIJAMHphhYNqOmAMA0GCSqGSIb3DQEBDQUAMIGVMREwDwYD + VQQKEwhGcmVlIFRTQTEQMA4GA1UECxMHUm9vdCBDQTEYMBYGA1UEAxMPd3d3LmZy + ZWV0c2Eub3JnMSIwIAYJKoZIhvcNAQkBFhNidXNpbGV6YXNAZ21haWwuY29tMRIw + EAYDVQQHEwlXdWVyemJ1cmcxDzANBgNVBAgTBkJheWVybjELMAkGA1UEBhMCREUw + HhcNMTYwMzEzMDE1MjEzWhcNNDEwMzA3MDE1MjEzWjCBlTERMA8GA1UEChMIRnJl + ZSBUU0ExEDAOBgNVBAsTB1Jvb3QgQ0ExGDAWBgNVBAMTD3d3dy5mcmVldHNhLm9y + ZzEiMCAGCSqGSIb3DQEJARYTYnVzaWxlemFzQGdtYWlsLmNvbTESMBAGA1UEBxMJ + V3VlcnpidXJnMQ8wDQYDVQQIEwZCYXllcm4xCzAJBgNVBAYTAkRFMIICIjANBgkq + hkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAtgKODjAy8REQ2WTNqUudAnjhlCrpE6ql + mQfNppeTmVvZrH4zutn+NwTaHAGpjSGv4/WRpZ1wZ3BRZ5mPUBZyLgq0YrIfQ5Fx + 0s/MRZPzc1r3lKWrMR9sAQx4mN4z11xFEO529L0dFJjPF9MD8Gpd2feWzGyptlel + b+PqT+++fOa2oY0+NaMM7l/xcNHPOaMz0/2olk0i22hbKeVhvokPCqhFhzsuhKsm + q4Of/o+t6dI7sx5h0nPMm4gGSRhfq+z6BTRgCrqQG2FOLoVFgt6iIm/BnNffUr7V + DYd3zZmIwFOj/H3DKHoGik/xK3E82YA2ZulVOFRW/zj4ApjPa5OFbpIkd0pmzxzd + EcL479hSA9dFiyVmSxPtY5ze1P+BE9bMU1PScpRzw8MHFXxyKqW13Qv7LWw4sbk3 + SciB7GACbQiVGzgkvXG6y85HOuvWNvC5GLSiyP9GlPB0V68tbxz4JVTRdw/Xn/XT + FNzRBM3cq8lBOAVt/PAX5+uFcv1S9wFE8YjaBfWCP1jdBil+c4e+0tdywT2oJmYB + BF/kEt1wmGwMmHunNEuQNzh1FtJY54hbUfiWi38mASE7xMtMhfj/C4SvapiDN837 + gYaPfs8x3KZxbX7C3YAsFnJinlwAUss1fdKar8Q/YVs7H/nU4c4Ixxxz4f67fcVq + M2ITKentbCMCAwEAAaOCAk4wggJKMAwGA1UdEwQFMAMBAf8wDgYDVR0PAQH/BAQD + AgHGMB0GA1UdDgQWBBT6VQ2MNGZRQ0z357OnbJWveuaklzCBygYDVR0jBIHCMIG/ + gBT6VQ2MNGZRQ0z357OnbJWveuakl6GBm6SBmDCBlTERMA8GA1UEChMIRnJlZSBU + U0ExEDAOBgNVBAsTB1Jvb3QgQ0ExGDAWBgNVBAMTD3d3dy5mcmVldHNhLm9yZzEi + MCAGCSqGSIb3DQEJARYTYnVzaWxlemFzQGdtYWlsLmNvbTESMBAGA1UEBxMJV3Vl + cnpidXJnMQ8wDQYDVQQIEwZCYXllcm4xCzAJBgNVBAYTAkRFggkAwemGFg2o6YAw + MwYDVR0fBCwwKjAooCagJIYiaHR0cDovL3d3dy5mcmVldHNhLm9yZy9yb290X2Nh + LmNybDCBzwYDVR0gBIHHMIHEMIHBBgorBgEEAYHyJAEBMIGyMDMGCCsGAQUFBwIB + FidodHRwOi8vd3d3LmZyZWV0c2Eub3JnL2ZyZWV0c2FfY3BzLmh0bWwwMgYIKwYB + BQUHAgEWJmh0dHA6Ly93d3cuZnJlZXRzYS5vcmcvZnJlZXRzYV9jcHMucGRmMEcG + CCsGAQUFBwICMDsaOUZyZWVUU0EgdHJ1c3RlZCB0aW1lc3RhbXBpbmcgU29mdHdh + cmUgYXMgYSBTZXJ2aWNlIChTYWFTKTA3BggrBgEFBQcBAQQrMCkwJwYIKwYBBQUH + MAGGG2h0dHA6Ly93d3cuZnJlZXRzYS5vcmc6MjU2MDANBgkqhkiG9w0BAQ0FAAOC + AgEAaK9+v5OFYu9M6ztYC+L69sw1omdyli89lZAfpWMMh9CRmJhM6KBqM/ipwoLt + nxyxGsbCPhcQjuTvzm+ylN6VwTMmIlVyVSLKYZcdSjt/eCUN+41K7sD7GVmxZBAF + ILnBDmTGJmLkrU0KuuIpj8lI/E6Z6NnmuP2+RAQSHsfBQi6sssnXMo4HOW5gtPO7 + gDrUpVXID++1P4XndkoKn7Svw5n0zS9fv1hxBcYIHPPQUze2u30bAQt0n0iIyRLz + aWuhtpAtd7ffwEbASgzB7E+NGF4tpV37e8KiA2xiGSRqT5ndu28fgpOY87gD3ArZ + DctZvvTCfHdAS5kEO3gnGGeZEVLDmfEsv8TGJa3AljVa5E40IQDsUXpQLi8G+UC4 + 1DWZu8EVT4rnYaCw1VX7ShOR1PNCCvjb8S8tfdudd9zhU3gEB0rxdeTy1tVbNLXW + 99y90xcwr1ZIDUwM/xQ/noO8FRhm0LoPC73Ef+J4ZBdrvWwauF3zJe33d4ibxEcb + 8/pz5WzFkeixYM2nsHhqHsBKw7JPouKNXRnl5IAE1eFmqDyC7G/VT7OF669xM6hb + Ut5G21JE4cNK6NNucS+fzg1JPX0+3VhsYZjj7D5uljRvQXrJ8iHgr/M6j2oLHvTA + I2MLdq2qjZFDOCXsxBxJpbmLGBx9ow6ZerlUxzws2AWv2pk= + -----END CERTIFICATE----- + imageReferences: + - ghcr.io/kyverno/test-verify-image:* + validationFailureAction: Enforce + webhookTimeoutSeconds: 30 +``` + ## Using a custom TUF for custom Sigstore deployments If you want to have your own Sigstore infrastructure to be fully in control of the entire signing and verification stack, including the root key material, you can set up your own root of trust to use TUF. To configure Kyverno to use your TUF setup, use `--tufRoot` and `--tufMirror` flags for custom Sigstore deployments. From 904d8fa9ea12e5fcba18a2712cde28d459967e06 Mon Sep 17 00:00:00 2001 From: Vishal Choudhary Date: Mon, 28 Oct 2024 21:16:00 +0530 Subject: [PATCH 11/13] feat: add documentation for emit warning in mutate and validate (#1397) * feat: add documentation for emit warning in mutate and validate Signed-off-by: Vishal Choudhary * Update validate.md Co-authored-by: shuting Signed-off-by: Vishal Choudhary * Update mutate.md Co-authored-by: shuting Signed-off-by: Vishal Choudhary --------- Signed-off-by: Vishal Choudhary Signed-off-by: Vishal Choudhary Co-authored-by: shuting --- content/en/docs/writing-policies/mutate.md | 4 ++++ content/en/docs/writing-policies/validate.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/content/en/docs/writing-policies/mutate.md b/content/en/docs/writing-policies/mutate.md index 7a7763b2c..e2599c34d 100644 --- a/content/en/docs/writing-policies/mutate.md +++ b/content/en/docs/writing-policies/mutate.md @@ -415,6 +415,10 @@ spec: - <(emptyDir): {} ``` +{{% alert title="Note" color="info" %}} +Set `spec.emitWarning` to `true` to enable API response warnings for mutate policies upon resource's admission events. +{{% /alert %}} + ## Mutate Existing resources In addition to standard mutations, Kyverno also supports mutation on existing resources with `patchStrategicMerge` and `patchesJson6902`. Unlike regular mutate policies that are applied through the AdmissionReview process, mutate existing policies are applied in the background (via the background controller) which update existing resources in the cluster. These "mutate existing" policies, like traditional mutate policies, are still triggered via the AdmissionReview process but apply to existing resources. This decoupling also allows triggering on one resource and mutating a totally different one. They may also optionally be configured to apply upon updates to the policy itself. This has two important implications: diff --git a/content/en/docs/writing-policies/validate.md b/content/en/docs/writing-policies/validate.md index 1b3f4e9e8..72f37eaed 100644 --- a/content/en/docs/writing-policies/validate.md +++ b/content/en/docs/writing-policies/validate.md @@ -87,6 +87,10 @@ The `FailureAction` attribute controls admission control behaviors for resources The field `spec.validationFailureAction` is deprecated and will be removed in a future release. Instead, use `spec.rules[*].validate[*].failureAction`. {{% /alert %}} +{{% alert title="Note" color="info" %}} +When `spec.rules[*].validate[*].failureAction` is set to `Audit`, set `spec.emitWarning` to `true` to show audit policy violation in admission response warnings. +{{% /alert %}} + ## Failure Action Overrides Using `failureActionOverrides`, you can specify which actions to apply per Namespace. This attribute is only available for ClusterPolicies. From 051ad9813a7c4f1fde000e5a0dd9c7e312297ca3 Mon Sep 17 00:00:00 2001 From: Vishal Choudhary Date: Mon, 28 Oct 2024 21:40:27 +0530 Subject: [PATCH 12/13] feat: add documentation for auto webhook deletion feature (#1398) * feat: add documentation for auto webhook deletion feature Signed-off-by: Vishal Choudhary * fix: clarifications Signed-off-by: Vishal Choudhary --------- Signed-off-by: Vishal Choudhary --- content/en/docs/installation/uninstallation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/installation/uninstallation.md b/content/en/docs/installation/uninstallation.md index bf5449c6f..b7534727d 100644 --- a/content/en/docs/installation/uninstallation.md +++ b/content/en/docs/installation/uninstallation.md @@ -26,7 +26,7 @@ helm uninstall kyverno kyverno/kyverno -n kyverno ### Clean up Webhooks -Kyverno by default will try to clean up all its webhooks when terminated. But in cases where its RBAC resources are removed first, it will lose the permission to do so properly. +Kyverno by default will try to clean up all its webhooks when terminated for helm based installations. But in other cases where Kyverno's RBAC resources are removed first, it will lose the permission to do so properly. Kyverno supports deletion using finalizers to ensure resource deletion in right order. Use `--autoDeleteWebhooks` in admission-controller and cleanup-controller deployment to enable this feature, this feature will be enabled by default in future releases. If manual webhook removal is necessary, use the below commands. From 7451b092ab3257e23591e2288e6d2f8ed725fb39 Mon Sep 17 00:00:00 2001 From: Frank Jogeleit Date: Mon, 28 Oct 2024 23:16:05 +0100 Subject: [PATCH 13/13] [Enhancement] assert subrule documentation (#1329) add assert subrule documentation Signed-off-by: Frank Jogeleit Co-authored-by: Jim Bugwadia --- content/en/docs/writing-policies/validate.md | 118 +++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/content/en/docs/writing-policies/validate.md b/content/en/docs/writing-policies/validate.md index 72f37eaed..dfdf7d2b2 100644 --- a/content/en/docs/writing-policies/validate.md +++ b/content/en/docs/writing-policies/validate.md @@ -2037,3 +2037,121 @@ spec: policyName: disallow-host-path validationActions: [Audit, Warn] ``` + +## Kyverno JSON Assertion + +Starting in Kyverno 1.13, a new subrule type called `assert` is available. This subrule type allows users to use Kyverno JSON assertion trees for resource validation. Standard `match` and `exclude` processing is available just like with other rules. This subrule type is enabled when a validate rule is written with a `assert` object, detailed below. + +For example, this policy ensures that a pod does not use the default service account. + +```yaml +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: disallow-default-sa +spec: + validationFailureAction: Enforce + rules: + - match: + any: + - resources: + kinds: + - Pod + name: disallow-default-sa + validate: + message: default ServiceAccount should not be used + assert: + object: + spec: + (serviceAccountName == 'default'): false +``` + +The `assert.object` contains an assertion tree to validate the applied resource. If an assertion evaluates to false, the validation check is enforced according to the `spec.validationFailureAction` field. + +When trying to create a Deployment with the "default" ServiceAccount, the creation of the Deployment will be blocked. + +``` +Error from server: admission webhook "validate.kyverno.svc-fail" denied the request: + +resource Pod/default/nginx was blocked due to the following policies + +disallow-default-sa: + disallow-default-sa: 'object.spec.(serviceAccountName == ''default''): Invalid value: + true: Expected value: false' +``` + +assertions have access to the contents of the Admission request/response, organized as seperared trees as well as some other useful variables: + +- `object` - The object from the incoming request. The value is null for DELETE requests. +- `oldObject` - The existing object. The value is null for CREATE requests. +- `admissionInfo` - Additional admission information. Contains user information like `roles`, `clusterRoles` and `username`. +- `operation` - Admission Operation. +- `namespaceLabels` - Map of labels of the target namespace, not available for cluster scoped objects. +- `admissionOperation` - Bool value which indicates if the policy was triggered from an admission request. + +`validate.assert` subrules also supports autogen rules for higher-level controllers that directly or indirectly manage Pods: Deployment, DaemonSet, StatefulSet, Job, and CronJob resources. Check the [autogen](autogen.md) section for more information. + +```yaml +status: + autogen: + rules: + - exclude: + resources: {} + generate: + clone: {} + cloneList: {} + match: + all: + - resources: + kinds: + - DaemonSet + - Deployment + - Job + - ReplicaSet + - ReplicationController + - StatefulSet + operations: + - CREATE + - UPDATE + resources: {} + mutate: {} + name: autogen-disallow-default-sa + skipBackgroundRequests: true + validate: + assert: + object: + spec: + template: + spec: + (serviceAccountName == 'default'): false + message: default ServiceAccount should not be used + validationFailureAction: Audit + - exclude: + resources: {} + generate: + clone: {} + cloneList: {} + match: + all: + - resources: + kinds: + - CronJob + operations: + - CREATE + - UPDATE + resources: {} + mutate: {} + name: autogen-cronjob-disallow-default-sa + skipBackgroundRequests: true + validate: + assert: + object: + spec: + jobTemplate: + spec: + template: + spec: + (serviceAccountName == 'default'): false + message: default ServiceAccount should not be used + validationFailureAction: Audit +``` \ No newline at end of file