diff --git a/config/_default/params.toml b/config/_default/params.toml index 51a3d13b7..d4cf7ca2c 100644 --- a/config/_default/params.toml +++ b/config/_default/params.toml @@ -9,7 +9,7 @@ showLineNumbers = false # Menu title if your navbar has a versions selector to access old versions of your site. # This menu appears only if you have at least one [versions] set. -version_menu = "main" +version_menu = "v1.13.0" # Flag used in the "version-banner" partial to decide whether to display a # banner on every page indicating that this is an archived version of the docs. @@ -19,7 +19,7 @@ archived_version = false # The version number for the version of the docs represented in this doc set. # Used in the "version-banner" partial to display a version number for the # current doc set. -version = "main" +version = "v1.13.0" # A link to latest version of the docs. Used in the "version-banner" partial to # point people to the main doc site. @@ -143,9 +143,13 @@ js = [ # version_menu = "Versions" # Add your release versions here [[versions]] - version = "v1.12.0" + version = "v1.13.0" url = "https://kyverno.io" +[[versions]] + version = "v1.12.0" + url = "https://release-1-12-0.kyverno.io" + [[versions]] version = "v1.11.0" url = "https://release-1-11-0.kyverno.io" diff --git a/content/en/blog/releases/1-13-0/index.md b/content/en/blog/releases/1-13-0/index.md new file mode 100644 index 000000000..9f3b5fcfc --- /dev/null +++ b/content/en/blog/releases/1-13-0/index.md @@ -0,0 +1,645 @@ +--- +date: 2024-10-30 +title: "Announcing Kyverno Release 1.13!" +linkTitle: "Kyverno 1.13" +description: "Kyverno 1.13 released with Sigstore bundle verification, exceptions for validatingAdmissionPolicies, new assertion trees, generate enhancments, enhanced ValidatingAdmissionPolicy and PolicyException support, and tons more!" +draft: false +--- + +Kyverno 1.13 contains [over 700 changes from 39 contributors](https://github.com/kyverno/kyverno/compare/release-1.12...v1.13.0-rc.3)! In this blog, we will highlight some of the major changes and enhancements for the release. + +![kyverno](kyverno.png) + +## Major Features + +### Sigstore Bundle Verification + +Kyverno 1.13 introduces support for verifying container images signatures that use the [sigstore bundle format](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto). This enables seamless support for [GitHub Artifact Attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations) to be verified using verification type `SigstoreBundle`.  + +The following example verifies images containing SLSA Provenance created and signed using GitHub Artifact Attestation. + +Here is an example policy: + +```yaml +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: sigstore-image-verification +spec: + validationFailureAction: Enforce + webhookTimeoutSeconds: 30 + rules: + - match: + any: + - resources: + kinds: + - Pod + name: sigstore-image-verification + verifyImages: + - imageReferences: + - "*" + type: SigstoreBundle + attestations: + - type: https://slsa.dev/provenance/v1 + attestors: + - entries: + - keyless: + issuer: https://token.actions.githubusercontent.com + subject: https://github.com/nirmata/github-signing-demo/.github/workflows/build-attested-image.yaml@refs/heads/main + rekor: + url: https://rekor.sigstore.dev + additionalExtensions: + githubWorkflowTrigger: push + githubWorkflowName: build-attested-image + githubWorkflowRepository: nirmata/github-signing-demo + conditions: + - all: + - key: "{{ buildDefinition.buildType }}" + operator: Equals + value: "https://actions.github.io/buildtypes/workflow/v1" + - key: "{{ buildDefinition.externalParameters.workflow.repository }}" + operator: Equals + value: "https://github.com/nirmata/github-signing-demo" +``` + +The demo repository is available at: https://github.com/nirmata/github-signing-demo. + + +### Exceptions for ValidatingAdmissionPolicies + +Kyverno 1.13 introduces the ability to leverage PolicyException declarations while auto-generating Kubernetes ValidatingAdmissionPolicies directly from Kyverno policies that use the `validate.cel` subrule. + +The resources specified within the PolicyException are then used to populate the `matchConstraints.excludeResourceRules` field of the generated ValidatingAdmissionPolicy, effectively creating exclusions for those resources. This functionality is illustrated below with an example of a Kyverno ClusterPolicy and a PolicyException, along with the resulting ValidatingAdmissionPolicy. + +Kyverno policy: + +```yaml +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: disallow-host-path +spec: + background: false + rules: + - name: host-path + match: + any: + - resources: + kinds: + - Deployment + - StatefulSet + operations: + - CREATE + - UPDATE + namespaceSelector: + matchExpressions: + - key: type + operator: In + values: + - connector + validate: + failureAction: Audit + cel: + expressions: + - expression: "!has(object.spec.template.spec.volumes) || object.spec.template.spec.volumes.all(volume, !has(volume.hostPath))" + message: "HostPath volumes are forbidden. The field spec.template.spec.volumes[*].hostPath must be unset." +``` + +PolicyException: + +```yaml +apiVersion: kyverno.io/v2 +kind: PolicyException +metadata: + name: policy-exception +spec: + exceptions: + - policyName: disallow-host-path + ruleNames: + - host-path + match: + any: + - resources: + kinds: + - Deployment + names: + - important-tool + operations: + - CREATE + - UPDATE +``` + +The generated ValidatingAdmissionPolicy and its binding are as follows: + +```yaml +apiVersion: admissionregistration.k8s.io/v1 +kind: ValidatingAdmissionPolicy +metadata: + labels: + app.kubernetes.io/managed-by: kyverno + name: disallow-host-path + ownerReferences: + - apiVersion: kyverno.io/v1 + kind: ClusterPolicy + name: disallow-host-path +spec: + failurePolicy: Fail + matchConstraints: + resourceRules: + - apiGroups: + - apps + apiVersions: + - v1 + operations: + - CREATE + - UPDATE + resources: + - deployments + - statefulsets + namespaceSelector: + matchExpressions: + - key: type + operator: In + values: + - connector + excludeResourceRules: + - apiGroups: + - apps + apiVersions: + - v1 + operations: + - CREATE + - UPDATE + resourceNames: + - important-tool + resources: + - deployments + validations: + - expression: '!has(object.spec.template.spec.volumes) || object.spec.template.spec.volumes.all(volume, + !has(volume.hostPath))' + message: HostPath volumes are forbidden. The field spec.template.spec.volumes[*].hostPath + must be unset. +--- +apiVersion: admissionregistration.k8s.io/v1 +kind: ValidatingAdmissionPolicyBinding +metadata: + labels: + app.kubernetes.io/managed-by: kyverno + name: disallow-host-path-binding + ownerReferences: + - apiVersion: kyverno.io/v1 + kind: ClusterPolicy + name: disallow-host-path +spec: + policyName: disallow-host-path + validationActions: [Audit, Warn] +``` + +In addition, Kyverno policies targeting resources within a specific namespace will now generate a ValidatingAdmissionPolicy that utilizes the `matchConstraints.namespaceSelector` field to scope its enforcement to that namespace. + +Policy snippet: + +```yaml +match: + any: + - resources: + kinds: + - Deployment + operations: + - CREATE + - UPDATE + namespaces: + - production + - staging +``` + +The generated ValidatingAdmissionPolicy: + +```yaml +matchConstraints: + namespaceSelector: + matchExpressions: + - key: kubernetes.io/metadata.name + operator: In + values: + - production + - staging + resourceRules: + - apiGroups: + - apps + apiVersions: + - v1 + operations: + - CREATE + - UPDATE + resources: + - deployments +``` + +### Validation Rules with Assertion Trees + +Kyverno-JSON allows Kyverno policies to be used anywhere, even for non-Kubernetes workloads. It introduces the powerful concept of [assertion trees](https://kyverno.io/blog/2023/12/13/kyverno-chainsaw-exploring-the-power-of-assertion-trees/). + +Previously the [Kyverno CLI added support for assertion trees](https://kyverno.io/docs/kyverno-cli/assertion-trees/), and now in Release 1.13 assertion trees can also be used in validation rules as a sub-type. + +Here is an example of a policy that uses an assertion tree to deny pods from using 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 +``` + +## Other Features and Enhancements + +### Generate Changes + +The `foreach` declaration allows the generation of multiple target resources of sub-elements in resource declarations. Each `foreach` entry must contain a list attribute, written as a JMESPath expression without braces, that defines sub-elements it processes. + +Here is an example of creating networkpolicies for a list of Namespaces, the namespaces are stored in a ConfigMap which can be easily configured dynamically. + +```yaml +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: foreach-generate-data +spec: + rules: + - match: + any: + - resources: + kinds: + - ConfigMap + name: k-kafka-address + generate: + generateExisting: false + synchronize: true + orphanDownstreamOnPolicyDelete: false + foreach: + - list: request.object.data.namespaces | split(@, ‘,’) + apiVersion: networking.k8s.io/v1 + kind: NetworkPolicy + name: my-networkpolicy-{{element}}-{{ elementIndex }} + namespace: ‘{{ element }}’ + data: + metadata: + labels: + request.namespace: ‘{{ request.object.metadata.name }}’ + element: ‘{{ element }}’ + elementIndex: ‘{{ elementIndex }}’ + spec: + podSelector: {} + policyTypes: + - Ingress + - Egress +``` + +The triggering ConfigMap is defined as follows, the data contains a namespaces field that defines multiple namespaces. + +```yaml +kind: ConfigMap +apiVersion: v1 +metadata: + name: default-deny + namespace: default +data: + namespaces: foreach-ns-1,foreach-ns-2 +``` + +Similarly, below is an example of a clone source type of `foreach` declaration that clones the source Secret into a list of matching existing namespaces which is stored in the same ConfigMap as above. + +```yaml +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: foreach-clone +spec: + rules: + - match: + any: + - resources: + kinds: + - ConfigMap + namespaces: + - default + name: k-kafka-address + generate: + generateExisting: false + synchronize: true + foreach: + - list: request.object.data.namespaces | split(@, ',') + apiVersion: v1 + kind: Secret + name: cloned-secret-{{ elementIndex }}-{{ element }} + namespace: '{{ element }}' + clone: + namespace: default + name: source-secret +``` + +In addition, each `foreach` declaration supports the following declarations: Contex and Preconditions. For more information please see [Kyverno documentation](https://kyverno.io/docs/writing-policies/generate/#foreach). + +This release also allows updates to the generate rule pattern. In addition to deletion, if the triggering resource is altered in a way such that it no longer matches the definition in the rule, that too will cause the removal of the downstream resource. + +### API call enhancements + +#### Default Values + +In the case where the API server returns an error, `apiCall.default` can be used to provide a fallback value for the API call context entry. + +The following example shows how to add default value to context entries: + +```yaml + context: + - name: currentnamespace + apiCall: + urlPath: “/api/v1/namespaces/{{ request.namespace }}” + jmesPath: metadata.name + default: default +``` +#### Custom Headers + +Kyverno Service API calls now also support custom headers. This can be useful for authentication or adding other HTTP request headers. Here is an example of adding a token in the HTTP Authorization header: + +```yaml + context: + - name: result + apiCall: + method: POST + data: + - key: foo + value: bar + - key: namespace + value: "{{ `{{ request.namespace }}` }}" + service: + url: http://my-service.svc.cluster.local/validation + headers: + - key: "UserAgent" + value: "Kyverno Policy XYZ" + - key: "Authorization" + value: "Bearer {{ MY_SECRET }}" +``` + +### Policy Report Enhancements + +#### Reports for Mutate and Generate rules + +In addition to validate and verifyImages rules, Kyverno 1.13 supports reporting for generate and mutate, including mutate existing policies, to record policy results. The container flag `--enableReporting` can be used to enable or disable reports for specific rule types. It allows the comma-separated values, validate, mutate, mutateExisting, generate, and imageVerify. See details [here](https://main.kyverno.io/docs/installation/customization/#container-flags). + +A result entry will be audited in the policy report for rule decision: + +```yaml +apiVersion: wgpolicyk8s.io/v1alpha2 +kind: PolicyReport +metadata: + labels: + app.kubernetes.io/managed-by: kyverno + namespace: default +results: +- message: mutated Pod/good-pod in namespace default + policy: add-labels + result: pass + rule: add-labels + scored: true + source: kyverno +scope: + apiVersion: v1 + kind: Pod + name: good-pod + namespace: default +... +``` + +Note that the proper permissions need to be granted to the reports controller, a warning message will be returned upon policy admission if no RBAC permission is configured. + +#### Custom Data in Reports + +A new field `reportProperties` is introduced to custom data in policy reports. For example, a validate rule below adds two additional entries operation and objName to the policy reports: + +```yaml +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: require-owner +spec: + background: false + rules: + - match: + any: + - resources: + kinds: + - Namespace + name: check-owner + context: + - name: objName + variable: + jmesPath: request.object.metadata.name + reportProperties: + operation: ‘{{ request.operation }}’ + objName: ‘{{ objName }}’ + validate: + validationFailureAction: Audit + message: The `owner` label is required for all Namespaces. + pattern: + metadata: + labels: + owner: ?* +``` + +You can find the two custom entries added to `results.properties`: + +```yaml +apiVersion: wgpolicyk8s.io/v1alpha2 +kind: ClusterPolicyReport +metadata: + ownerReferences: + - apiVersion: v1 + kind: Namespace + name: bar +results: +- message: validation rule ‘check-owner’ passed. + policy: require-owner + result: pass + rule: check-owner + scored: true + source: kyverno + properties: + objName: bar + operation: CREATE +scope: + apiVersion: v1 + kind: Namespace + name: bar +``` + +### GlobalContextEntries Enhancements + +#### API Call Retry + +Kyverno’s GlobalContextEntry provides a powerful mechanism to fetch external data and use it within policies. When leveraging the apiCall feature to retrieve data from an API, transient network issues can sometimes hinder successful retrieval. + +To address this, Kyverno now offers built-in retry logic for API calls within GlobalContextEntry. You can now optionally specify a retryLimit for your API calls: + +```yaml +apiVersion: kyverno.io/v2alpha1 +kind: GlobalContextEntry +metadata: + name: gctxentry-apicall-correct +spec: + apiCall: + urlPath: "/apis/apps/v1/namespaces/test-globalcontext-apicall-correct/deployments" + refreshInterval: 1h + retryLimit: 3 +``` + +The `retryLimit` field determines the number of times Kyverno will attempt to make the API call if it initially fails. This field is optional and defaults to 3, ensuring a reasonable level of resilience against temporary network hiccups. + +By incorporating this retry mechanism, Kyverno further strengthens its ability to reliably fetch external data, ensuring your policies can function smoothly even in the face of occasional connectivity issues. This enhancement improves the overall robustness and dependability of your Kubernetes policy enforcement framework. + +#### CLI-based Injection of Global Context Entries + +Kyverno CLI now allows you to dynamically inject global context entries using a Values file. This feature facilitates flexible policy testing and execution by simulating different scenarios without modifying GlobalContextEntry resources in your cluster. + +You can now define global values and rule-specific values within the Values file, providing greater control over policy evaluation during testing. + +```yaml +apiVersion: cli.kyverno.io/v1alpha1 +kind: Value +metadata: + name: values +globalValues: + request.operation: CREATE +policies: + - name: gctx + rules: + - name: main-deployment-exists + values: + deploymentCount: 1 +``` + +In this example, `request.operation` is set as a global value, and deploymentCount is set for a specific rule in the gctx policy. When using the Kyverno CLI, you can reference this Values file to inject these global context entries into your policy evaluation. + +### Security Hardening + +The Kyverno project strives to be secure and production-ready, while providing ease of use. This release contains important changes to further enhance the security of the project. + +#### Removal of wildcard roles + +Prior versions of Kyverno included wildcard view permissions. These have been removed in 1.13 and replaced with a role binding to the system view role. + +This change does not impact policy behaviors during admission controls, but may impact users with mutate and generate policies for custom resources, and may impact reporting of policy results for validation rules on custom resources A Helm option was added to upgrade Kyverno without breaking existing policies, see the upgrade guidance [here](https://main.kyverno.io/docs/installation/upgrading/#upgrading-to-kyverno-v113). + +#### Removal of insecure configuration for exceptions + +In prior versions, policy exceptions were allowed in all namespaces. This creates a potential security issue, as any user with permission to create a policy exception can bypass policies, even in other namespaces. See [CVE-2024-48921](https://github.com/kyverno/kyverno/security/advisories/GHSA-qjvc-p88j-j9rm) for more details. + +This release changes the defaults to disable the policy exceptions and only allows exceptions to be created in a specified namespace. To maintain backward compatibility follow the [upgrade guidance](https://main.kyverno.io/docs/installation/upgrading/#upgrading-to-kyverno-v113). + +### Warnings for Policy Violations and Mutations + +A warning message can now be returned along with admission responses by the policy setting `spec.emitWarning`, this can be used to report policy violations as well as mutations upon admission events. + +### Shallow evaluation of Variables + +Kyverno performs nested variable substitution by default, this may not be desirable in certain situations. Take the following ConfigMap as an example, it defines a `.hcl` string content using the same `{{ }}` notation which is used in Kyverno for variable syntax. In this case, Kyverno needs to be instructed to not attempt to resolve variables in the HCL, this can be achieved by `{{- ... }}` notation for shallow (one time only) substitution of variables. + +```yaml +apiVersion: v1 +data: + config: |- + from_string + {{ some hcl tempalte }} +kind: ConfigMap +metadata: + annotations: + labels: + argocd.development.cpl..co.at/app: corp-tech-ap-team-ping-ep + name: vault-injector-config-http-echo + namespace: corp-tech-ap-team-ping-ep +``` + +To only substitute the rule data with the HCL, and not perform nested substitutions, the following policy uses the declaration `{{- hcl }}` for shallow substitution. + +```yaml +apiVersion: cli.kyverno.io/v1alphaapiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: vault-auth-backend +spec: + validationFailureAction: Audit + background: true + mutateExistingOnPolicyUpdate: true + rules: + - name: vault-injector-config-blue-to-green-auth-backend + context: + - name: hcl + variable: + jmesPath: replace_all( ‘{{ request.object.data.config }}’, ‘from_string’,‘to_string’) + match: + any: + - resources: + kinds: + - ConfigMap + names: + - test-* + namespaces: + - corp-tech-ap-team-ping-ep + mutate: + patchStrategicMerge: + data: + config: ‘{{- hcl }}’ + targets: + - apiVersion: v1 + kind: ConfigMap + name: ‘{{ request.object.metadata.name }}’ + namespace: ‘{{ request.object.metadata.namespace }}’ + name: vault-injector-config-blue-to-green-auth-backend +``` + +### Improved ArgoCD Integration + +Kyverno-managed webhook configurations are auto-cleaned up upon uninstallation. This behavior could be broken if Kyverno loses RBAC permissions to do so given the random resources deletion order. This release introduces a finalizer-based cleanup solution to ensure webhooks are removed successfully. + +This feature is in [beta stage](https://main.kyverno.io/docs/installation/uninstallation/#clean-up-webhooks) and will be used as the default cleanup strategy in the future. + +### API Version Management + +Kyverno 1.13 introduces new changes in the policy CRDs: + +* Both Policy Exceptions and Cleanup Policies have graduated to a stable version (v2). +* Several policy settings are deprecated: + * spec.validationFailureAction + * spec.validationFailureActionOverrides + * spec.mutateExistingOnPolicyUpdate + * spec.generateExisting + +* These are replaced by more granular controls within the rule itself: + * spec.rules[*].validate.failureAction + * spec.rules[*].validate.failureActionOverrides + * spec.rules[*].verifyImages[*].failureAction + * spec.rules[*].mutate.mutateExisting + * spec.rules[*].generate.generateExisting + +Note that the deprecated fields will be removed in a future release, so migration to the new settings is recommended. + +## Conclusion + +Kyverno 1.13 promises to be a great release, with many new features, enhancements, and fixes. To get started with Kyverno try the [quick start guides](https://kyverno.io/docs/introduction/quick-start/) or head to the [installation](https://kyverno.io/docs/installation/methods/) section of the docs. + +To get the most value out of Kyverno, and check out the [available enterprise solutions](/support)! \ No newline at end of file diff --git a/content/en/blog/releases/1-13-0/kyverno.png b/content/en/blog/releases/1-13-0/kyverno.png new file mode 100644 index 000000000..3695f1b26 Binary files /dev/null and b/content/en/blog/releases/1-13-0/kyverno.png differ diff --git a/content/en/docs/installation/scaling.md b/content/en/docs/installation/scaling.md index 219233e38..a12776666 100644 --- a/content/en/docs/installation/scaling.md +++ b/content/en/docs/installation/scaling.md @@ -32,17 +32,17 @@ Testing was performed using KinD on an Ubuntu 20.04 system with an AMD EPYC 7502 The following table shows the resource consumption (memory and CPU) and latency as a result of increased virtual users and iterations defined in [k6](https://k6.io/open-source/). k6 is an open-source load testing tool for performance testing. k6 has multiple executors, the most popular of which is the shared-iterations executor. This executor creates a number of concurrent connections called virtual users. The total number of iterations is then distributed among these virtual users. -The test was conducted where we installed Kyverno policies to enforce the Kubernetes pod security standards using 17 policies. Subsequently, we developed a compatible Pod test to measure how long Kyverno takes to admit the admission request. For more details on these tests, refer to the load testing documentation [here](https://github.com/kyverno/load-testing/tree/main/k6). +The test was conducted where we installed Kyverno policies to enforce the Kubernetes pod security standards using 17 policies. Subsequently, we developed a compatible Pod test to measure how long Kyverno takes to admit the admission request. For more details on these tests, refer to the load testing documentation [here](https://github.com/kyverno/load-testing/blob/main/README.md). -| replicas | # policies | Rule Type | Mode | Subject | Virtual Users/Iterations | Latency (avg/max) | Memory (max) | CPU (max) | -|----------|------------|-----------|---------|---------|--------------------------|-------------------|--------------|-----------| -| 1 | 17 | Validate | Enforce | Pods | 100/1,000 | 42.89ms / 155.77ms | 115Mi | 211m | -| 1 | 17 | Validate | Enforce | Pods | 200/5,000 | 73.37ms / 432.37ms | 136Mi | 1148m | -| 1 | 17 | Validate | Enforce | Pods | 500/10,000 | 210.56ms / 1.54s | 315Mi | 1470m | -| 3 | 17 | Validate | Enforce | Pods | 100/1,000 | 31.06ms / 111.42ms | 110Mi | 96m | -| 3 | 17 | Validate | Enforce | Pods | 200/5,000 | 56.56ms / 248.38ms | 116Mi | 315m | -| 3 | 17 | Validate | Enforce | Pods | 500/10,000 | 136.77ms / 666.04ms | 167Mi | 524m | +| replicas | # policies | Rule Type | Mode | Subject | Virtual Users/Iterations | Latency (avg/max) | Memory (max) | CPU (max) | Memory Limit | +|----------|------------|-----------|---------|---------|--------------------------|--------------------|--------------|------------|-----------------| +| 1 | 17 | Validate | Enforce | Pods | 100/1,000 | 42.67ms / 141.24ms | 114Mi | 148m | default (384Mi) | +| 1 | 17 | Validate | Enforce | Pods | 200/5,000 | 80.74ms / 409.35ms | 215Mi | 3237m | default (384Mi) | +| 1 | 17 | Validate | Enforce | Pods | 500/10,000 | 203.86ms / 1.5s | 471Mi | 4851m | 512Mi | +| 3 | 17 | Validate | Enforce | Pods | 100/1,000 | 35.61ms / 92.61ms | 104Mi | 289m | default (384Mi) | +| 3 | 17 | Validate | Enforce | Pods | 200/5,000 | 67.37ms / 327.12ms | 122Mi | 1336m | default (384Mi) | +| 3 | 17 | Validate | Enforce | Pods | 500/10,000 | 163.08ms / 3.02s | 239Mi | 2769m | 512Mi | #### Reports Controller diff --git a/content/en/docs/installation/upgrading.md b/content/en/docs/installation/upgrading.md index 2fb72a121..9fd79b988 100644 --- a/content/en/docs/installation/upgrading.md +++ b/content/en/docs/installation/upgrading.md @@ -23,49 +23,52 @@ An upgrade from versions prior to Kyverno 1.10 to versions at 1.10 or higher usi 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. +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 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: +To upgrade to 1.13 and continue to allow wildcard view permissions for all Kyverno controllers, use a [Helm values file](https://github.com/kyverno/kyverno/blob/v1.13.0/charts/kyverno/values.yaml) that grants these permissions as specified below: ```yaml admissionController: - clusterRole: - extraResources: - - apiGroups: - - '*' - resources: - - '*' - verbs: - - get - - list - - watch + rbac: + clusterRole: + extraResources: + - apiGroups: + - '*' + resources: + - '*' + verbs: + - get + - list + - watch backgroundController: - clusterRole: - extraResources: - - apiGroups: - - '*' - resources: - - '*' - verbs: - - get - - list - - watch + rbac: + clusterRole: + extraResources: + - apiGroups: + - '*' + resources: + - '*' + verbs: + - get + - list + - watch reportsController: - clusterRole: - extraResources: - - apiGroups: - - '*' - resources: - - '*' - verbs: - - get - - list - - watch + rbac: + 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. +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](https://github.com/kyverno/kyverno/security/advisories/GHSA-qjvc-p88j-j9rm) 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 `*`: diff --git a/content/en/docs/introduction/_index.md b/content/en/docs/introduction/_index.md index 492177616..8024d6f9e 100644 --- a/content/en/docs/introduction/_index.md +++ b/content/en/docs/introduction/_index.md @@ -10,7 +10,7 @@ description: > Kyverno (Greek for "govern") is a cloud native policy engine. It was originally built for Kubernetes and now can also be used outside of Kubernetes clusters as a unified policy language. -Kyverno allows platform engineers to automate security, complianace, and best practices validation and deliver secure self-service to application teams. +Kyverno allows platform engineers to automate security, compliance, and best practices validation and deliver secure self-service to application teams. Some of its many features include: @@ -18,7 +18,7 @@ Some of its many features include: * enforce policies as a Kubernetes admission controller, CLI-based scanner, and at runtime * validate, mutate, generate, or cleanup (remove) any Kubernetes resource * verify container images and metadata for software supply chain security -* policies for any JSON payload including Terraform resources, cloud resources, and service authoriation +* policies for any JSON payload including Terraform resources, cloud resources, and service authorization * policy reporting using the open reporting format from the CNCF Policy WG * flexible policy exception management * tooling for comprehensive unit and e2e testing of policies diff --git a/content/en/docs/introduction/quick-start.md b/content/en/docs/introduction/quick-start.md index c1f6bba62..e663db342 100644 --- a/content/en/docs/introduction/quick-start.md +++ b/content/en/docs/introduction/quick-start.md @@ -13,7 +13,7 @@ These guides are intended for proof-of-concept or lab demonstrations only and no First, install Kyverno from the latest release manifest. ```sh -kubectl create -f https://github.com/kyverno/kyverno/releases/download/v1.12.0/install.yaml +kubectl create -f https://github.com/kyverno/kyverno/releases/download/v1.13.0/install.yaml ``` Next, select the quick start guide in which you are interested. Alternatively, start at the top and work your way down. @@ -212,7 +212,25 @@ kubectl -n default create secret docker-registry regcred \ By default, Kyverno is [configured with minimal permissions](../installation/customization.md#role-based-access-controls) and does not have access to security sensitive resources like Secrets. You can provide additional permissions using cluster role aggregation. The following role permits the Kyverno background-controller to create (clone) secrets. ```yaml -kubectl create -f- << EOF +kubectl apply -f- << EOF +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: kyverno:secrets:view + labels: + rbac.kyverno.io/aggregate-to-admission-controller: "true" + rbac.kyverno.io/aggregate-to-reports-controller: "true" + rbac.kyverno.io/aggregate-to-background-controller: "true" +rules: +- apiGroups: + - '' + resources: + - secrets + verbs: + - get + - list + - watch +--- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: @@ -226,6 +244,8 @@ rules: - secrets verbs: - create + - update + - delete EOF ``` @@ -250,7 +270,7 @@ spec: kind: Secret name: regcred namespace: "{{request.object.metadata.name}}" - synchronize: false + synchronize: true clone: namespace: default name: regcred diff --git a/content/en/docs/kyverno-cli/usage/apply.md b/content/en/docs/kyverno-cli/usage/apply.md index 1e1bc1e5c..07a2596bf 100644 --- a/content/en/docs/kyverno-cli/usage/apply.md +++ b/content/en/docs/kyverno-cli/usage/apply.md @@ -45,6 +45,11 @@ Apply multiple policies to multiple resources with exceptions: ```sh kyverno apply /path/to/policy1.yaml /path/to/folderFullOfPolicies --resource /path/to/resource1.yaml --resource /path/to/resource2.yaml --exception /path/to/exception1.yaml --exception /path/to/exception2.yaml ``` +Apply multiple policies to multiple resources where exceptions are evaluated from the provided resources: + +```sh +kyverno apply /path/to/policy1.yaml /path/to/folderFullOfPolicies --resource /path/to/resource1.yaml --resource /path/to/resource2.yaml --exceptions-with-resources +``` Apply a mutation policy to a specific resource: @@ -75,7 +80,7 @@ Apply a policy containing variables using the `--set` or `-s` flag to pass in th kyverno apply /path/to/policy.yaml --resource /path/to/resource.yaml --set =,= ``` -Use `-f` or `--values-file` for applying multiple policies to multiple resources while passing a file containing variables and their values. Variables specified can be of various types include AdmissionReview fields, ConfigMap context data, and API call context data. +Use `-f` or `--values-file` for applying multiple policies to multiple resources while passing a file containing variables and their values. Variables specified can be of various types include AdmissionReview fields, ConfigMap context data, API call context data, and Global Context Entries. Use `-u` or `--userinfo` for applying policies while passing an optional user_info.yaml file which contains necessary admission request data made during the request. @@ -494,6 +499,25 @@ policies: dictionary.data.env: dev1 ``` +You can also inject global context entries using variables. Here's an example of a Values file that injects a global context entry: + +```yaml +apiVersion: cli.kyverno.io/v1alpha1 +kind: Value +metadata: + name: values +globalValues: + request.operation: CREATE +policies: + - name: gctx + rules: + - name: main-deployment-exists + values: + deploymentCount: 1 +``` + +In this example, `request.operation` is set as a global value, and `deploymentCount` is set for a specific rule in the `gctx` policy. + 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 diff --git a/content/en/docs/policy-reports/_index.md b/content/en/docs/policy-reports/_index.md index 08ddafe6b..6e69cb76c 100644 --- a/content/en/docs/policy-reports/_index.md +++ b/content/en/docs/policy-reports/_index.md @@ -90,6 +90,10 @@ To configure Kyverno to generate reports for Kubernetes ValidatingAdmissionPolic Reporting can be enabled or disabled for rule types by modifying the value of the flag `--enableReporting=validate,mutate,mutateExisting,generate,imageVerify`. {{% /alert %}} +{{% alert title="Note" color="info" %}} +Creating reports for a resource require permissions to `get`, `list` and `watch` the resource in Kyverno reports controller. +{{% /alert %}} + ## Report result logic Entries in a policy report contain a `result` field which can be either `pass`, `skip`, `warn`, `error`, or `fail`. diff --git a/content/en/docs/writing-policies/external-data-sources.md b/content/en/docs/writing-policies/external-data-sources.md index 0aec61627..e305735c2 100644 --- a/content/en/docs/writing-policies/external-data-sources.md +++ b/content/en/docs/writing-policies/external-data-sources.md @@ -710,6 +710,8 @@ context: The data returned by GlobalContextEntries may vary depending on whether it is a Kubernetes resource or an API call. Consequently, the JMESPath expression used to manipulate the data may differ as well. Ensure you use the appropriate JMESPath expression based on the type of data being accessed to ensure accurate processing within policies. +To use Global Contexts with the Kyverno CLI, you can use the Values file to inject these global context entries into your policy evaluation. This allows you to simulate different scenarios and test your policies with various global context values without modifying the actual `GlobalContextEntry` resources in your cluster. Refer to it here: [kyverno apply](../kyverno-cli/usage/apply.md). + {{% alert title="Warning" color="warning" %}} GlobalContextEntries must be in a healthy state (i.e., there is a response received from the remote endpoint) in order for the policies which reference them to be considered healthy. A GlobalContextEntry which is in a `not ready` state will cause any/all referenced policies to also be in a similar state and therefore will not be processed. Creation of a policy referencing a GlobalContextEntry which either does not exist or is not ready will print a warning notifying users. {{% /alert %}}