-- -The **Webhook** is the server which handles incoming AdmissionReview requests from the Kubernetes API server and sends them to the **Engine** for processing. It is dynamically configured by the **Webhook Controller** which watches the installed policies and modifies the webhooks to request only the resources matched by those policies. The **Cert Renewer** is responsible for watching and renewing the certificates, stored as Kubernetes Secrets, needed by the webhook. The **Background Controller** handles all generate and mutate-existing policies by reconciling UpdateRequests, an intermediary resource. And the **Report Controllers** handle creation and reconciliation of Policy Reports from their intermediary resources, Admission Reports and Background Scan Reports. - -Kyverno also supports high availability. A highly-available installation of Kyverno is one in which the controllers selected for installation are configured to run with multiple replicas. Depending on the controller, the additional replicas may also serve the purpose of increasing the scalability of Kyverno. See the [high availability page](../high-availability/_index.md) for more details on the various Kyverno controllers, their components, and how availability is handled in each one. - -## Quick Start Guides - -This section is intended to provide you with some quick guides on how to get Kyverno up and running and demonstrate a few of Kyverno's seminal features. There are quick start guides which focus on validation, mutation, as well as generation allowing you to select the one (or all) which is most relevant to your use case. - -These guides are intended for proof-of-concept or lab demonstrations only and not recommended as a guide for production. Please see the [installation page](../installation/_index.md) for more complete information on how to install Kyverno in production. - -First, install Kyverno from the latest release manifest. - -```sh -kubectl create -f https://github.com/kyverno/kyverno/releases/download/v1.12.0/install.yaml -``` - -Next, select the quick start guide in which you are interested. Alternatively, start at the top and work your way down. - -### Validation - -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. - -```yaml -kubectl create -f- << EOF -apiVersion: kyverno.io/v1 -kind: ClusterPolicy -metadata: - name: require-labels -spec: - validationFailureAction: Enforce - rules: - - name: check-team - match: - any: - - resources: - kinds: - - Pod - validate: - message: "label 'team' is required" - pattern: - metadata: - labels: - team: "?*" -EOF -``` - -Try creating a Deployment without the required label. - -```sh -kubectl create deployment nginx --image=nginx -``` - -You should see an error. - -```sh -error: failed to create deployment: admission webhook "validate.kyverno.svc-fail" denied the request: - -resource Deployment/default/nginx was blocked due to the following policies: - -require-labels: - autogen-check-team: 'validation error: label ''team'' is - required. Rule autogen-check-team failed at path /spec/template/metadata/labels/team/' -``` - -In addition to the error returned, Kyverno also produces an Event in the same Namespace which contains this information. - -{{% alert title="Note" color="info" %}} -Kyverno may be configured to exclude system Namespaces like `kube-system` and `kyverno`. Make sure you create the Deployment in a user-defined Namespace or the `default` Namespace (for testing only). -{{% /alert %}} - -Note that how although the policy matches on Pods, Kyverno blocked the Deployment you just created. This is because Kyverno intelligently applies policies written exclusively for Pods, using its [rule auto-generation](../writing-policies/autogen.md) feature, to all standard Kubernetes Pod controllers including the Deployment above. - -Now, create a Pod with the required label. - -```sh -kubectl run nginx --image nginx --labels team=backend -``` - -This Pod configuration is compliant with the policy and is allowed. - -Now that the Pod exists, wait just a few seconds longer and see what other action Kyverno took. Run the following command to retrieve the Policy Report that Kyverno just created. - -```sh -kubectl get policyreport -o wide -``` - -Notice that there is a single Policy Report with just one result listed under the "PASS" column. This result is due to the Pod we just created having passed the policy. - -```sh -NAME KIND NAME PASS FAIL WARN ERROR SKIP AGE -89044d72-8a1e-4af0-877b-9be727dc3ec4 Pod nginx 1 0 0 0 0 15s -``` - -If you were to describe the above policy report you would see more information about the policy and resource. - -```yaml -Results: - Message: validation rule 'check-team' passed. - Policy: require-labels - Resources: - API Version: v1 - Kind: Pod - Name: nginx - Namespace: default - UID: 07d04dc0-fbb4-479a-b049-a3d63342b354 - Result: pass - Rule: check-team - Scored: true - Source: kyverno - Timestamp: - Nanos: 0 - Seconds: 1683759146 -``` - -Policy reports are helpful in that they are both user- and tool-friendly, based upon an open standard, and separated from the policies which produced them. This separation has the benefit of report access being easy to grant and manage for other users who may not need or have access to Kyverno policies. - -Now that you've experienced validate policies and seen a bit about policy reports, clean up by deleting the policy you created above. - -```sh -kubectl delete clusterpolicy require-labels -``` - -Congratulations, you've just implemented a validation policy in your Kubernetes cluster! For more details on validation policies, see the [validate section](../writing-policies/validate.md). - -### Mutation - -Mutation is the ability to change or "mutate" a resource in some way prior to it being admitted into the cluster. A mutate rule is similar to a validate rule in that it selects some type of resource (like Pods or ConfigMaps) and defines what the desired state should look like. - -Add this Kyverno mutate policy to your cluster. This policy will add the label `team` to any new Pod and give it the value of `bravo` but only if a Pod does not already have this label assigned. Kyverno has the ability to perform basic "if-then" logical decisions in a very easy way making policies trivial to write and read. The `+(team)` notation uses a Kyverno anchor to define the behavior Kyverno should take if the label key is not found. - -```yaml -kubectl create -f- << EOF -apiVersion: kyverno.io/v1 -kind: ClusterPolicy -metadata: - name: add-labels -spec: - rules: - - name: add-team - match: - any: - - resources: - kinds: - - Pod - mutate: - patchStrategicMerge: - metadata: - labels: - +(team): bravo -EOF -``` - -Let's now create a new Pod which does not have the desired label defined. - -```sh -kubectl run redis --image redis -``` - -{{% alert title="Note" color="info" %}} -Kyverno may be configured to exclude system Namespaces like `kube-system` and `kyverno`. Make sure you create the Pod in a user-defined Namespace or the `default` Namespace (for testing only). -{{% /alert %}} - -Once the Pod has been created, get the Pod to see if the `team` label was added. - -```sh -kubectl get pod redis --show-labels -``` - -You should see that the label `team=bravo` has been added by Kyverno. - -Try one more Pod, this time one which does already define the `team` label. - -```sh -kubectl run newredis --image redis -l team=alpha -``` - -Get this Pod back and check once again for labels. - -```sh -kubectl get pod newredis --show-labels -``` - -This time, you should see Kyverno did not add the `team` label with the value defined in the policy since one was already found on the Pod. - -Now that you've experienced mutate policies and seen how logic can be written easily, clean up by deleting the policy you created above. - -```sh -kubectl delete clusterpolicy add-labels -``` - -Congratulations, you've just implemented a mutation policy in your Kubernetes cluster! For more details on mutate policies, see the [mutate section](../writing-policies/mutate.md). - -### Generation - -Kyverno has the ability to generate (i.e., create) a new Kubernetes resource based upon a definition stored in a policy. Like both validate and mutate rules, Kyverno generate rules use similar concepts and structures to express policy. The generation ability is both powerful and flexible with one of its most useful aspects being, in addition to the initial generation, it has the ability to continually synchronize the resources it has generated. Generate rules can be a powerful automation tool and can solve many common challenges faced by Kubernetes operators. Let's look at one such use case in this guide. - -We will use a Kyverno generate policy to generate an image pull secret in a new Namespace. - -First, create this Kubernetes Secret in your cluster which will simulate a real image pull secret. - -```sh -kubectl -n default create secret docker-registry regcred \ - --docker-server=myinternalreg.corp.com \ - --docker-username=john.doe \ - --docker-password=Passw0rd123! \ - --docker-email=john.doe@corp.com -``` - -Next, create the following Kyverno policy. The `sync-secrets` policy will match on any newly-created Namespace and will clone the Secret we just created earlier into that new Namespace. - -```yaml -kubectl create -f- << EOF -apiVersion: kyverno.io/v1 -kind: ClusterPolicy -metadata: - name: sync-secrets -spec: - rules: - - name: sync-image-pull-secret - match: - any: - - resources: - kinds: - - Namespace - generate: - apiVersion: v1 - kind: Secret - name: regcred - namespace: "{{request.object.metadata.name}}" - synchronize: true - clone: - namespace: default - name: regcred -EOF -``` - -Create a new Namespace to test the policy. - -```sh -kubectl create ns mytestns -``` - -Get the Secrets in this new Namespace and see if `regcred` is present. - -```sh -kubectl -n mytestns get secret -``` - -You should see that Kyverno has generated the `regcred` Secret using the source Secret from the `default` Namespace as the template. If you wish, you may also modify the source Secret and watch as Kyverno synchronizes those changes down to wherever it has generated it. - -With a basic understanding of generate policies, clean up by deleting the policy you created above. - -```sh -kubectl delete clusterpolicy sync-secrets -``` - -Congratulations, you've just implemented a generation policy in your Kubernetes cluster! For more details on generate policies, see the [generate section](../writing-policies/generate.md). diff --git a/content/en/docs/introduction/admission-controllers.md b/content/en/docs/introduction/admission-controllers.md index acf06d586..c0914252d 100644 --- a/content/en/docs/introduction/admission-controllers.md +++ b/content/en/docs/introduction/admission-controllers.md @@ -99,7 +99,7 @@ In this example, the API server has been instructed to send any creation request The controller is the other half of the dynamic admission controller story. Something must be listening for the requests sent by the API server and be prepared to respond. This is typically implemented by a controller running in the same cluster as a Pod. This controller, like the API server with the webhook, must have some instruction for how to respond to requests. This instruction is provided to it in the form of a **policy**. A policy is typically another Kubernetes resource, but this time a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/), which the controller uses to determine that response. Once the controller examines the policy it is prepared to make a decision for resources it receives. -For example, as you may have learned in the [validation quick start section](../introduction/_index.md#validation), a policy such as `require-labels` can be used to instruct the controller how to respond in the case where it receives a matching request. If the Pod has a label named `team` then its creation will be allowed. If it does not, it will be prevented. +For example, as you may have learned in the [validation quick start section](../introduction/quick-start.md#validate-resources), a policy such as `require-labels` can be used to instruct the controller how to respond in the case where it receives a matching request. If the Pod has a label named `team` then its creation will be allowed. If it does not, it will be prevented. Controllers receiving requests from the Kubernetes API server do so over HTTP/REST. The contents of that request are a "packaging" or "wrapping" of the resource, which has been defined via the webhook, in addition to other pertinent information about who or what made the request. This package is called an `AdmissionReview`. More details on this packaging format along with an example can be seen [here](../writing-policies/jmespath.md#admissionreview). diff --git a/content/en/docs/introduction/how-kyverno-works.md b/content/en/docs/introduction/how-kyverno-works.md new file mode 100644 index 000000000..a5a88fdf4 --- /dev/null +++ b/content/en/docs/introduction/how-kyverno-works.md @@ -0,0 +1,31 @@ + +--- +title: How Kyverno Works +linkTitle: How Kyverno Works +weight: 10 +description: > + An overview of how Kyverno works +--- + + +## Kubernetes Admission Controls + +Kyverno runs as a [dynamic admission controller](./admission-controllers.md) 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. + +Kyverno policies can match resources using the resource kind, name, label selectors, and much more. + +Mutating policies can be written as overlays (similar to [Kustomize](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/#bases-and-overlays)) or as a [RFC 6902 JSON Patch](http://jsonpatch.com/). Validating policies also use an overlay style syntax, with support for pattern matching and conditional (if-then-else) processing. + +Policy enforcement is captured using Kubernetes events. For requests that are either allowed or existed prior to introduction of a Kyverno policy, Kyverno creates Policy Reports in the cluster which contain a running list of resources matched by a policy, their status, and more. + +The diagram below shows the high-level logical architecture of Kyverno. + +
++ +The **Webhook** is the server which handles incoming AdmissionReview requests from the Kubernetes API server and sends them to the **Engine** for processing. It is dynamically configured by the **Webhook Controller** which watches the installed policies and modifies the webhooks to request only the resources matched by those policies. The **Cert Renewer** is responsible for watching and renewing the certificates, stored as Kubernetes Secrets, needed by the webhook. The **Background Controller** handles all generate and mutate-existing policies by reconciling UpdateRequests, an intermediary resource. And the **Report Controllers** handle creation and reconciliation of Policy Reports from their intermediary resources, Admission Reports and Background Scan Reports. + +Kyverno also supports high availability. A highly-available installation of Kyverno is one in which the controllers selected for installation are configured to run with multiple replicas. Depending on the controller, the additional replicas may also serve the purpose of increasing the scalability of Kyverno. See the [high availability page](../high-availability/_index.md) for more details on the various Kyverno controllers, their components, and how availability is handled in each one. + + + diff --git a/content/en/docs/introduction/quick-start.md b/content/en/docs/introduction/quick-start.md new file mode 100644 index 000000000..a1fb7ba39 --- /dev/null +++ b/content/en/docs/introduction/quick-start.md @@ -0,0 +1,282 @@ +--- +title: Quick Start Guides +linkTitle: Quick Start Guides +weight: 20 +description: > + An introduction to Kyverno policy and rule types +--- + +This section is intended to provide you with some quick guides on how to get Kyverno up and running and demonstrate a few of Kyverno's seminal features. There are quick start guides which focus on validation, mutation, as well as generation allowing you to select the one (or all) which is most relevant to your use case. + +These guides are intended for proof-of-concept or lab demonstrations only and not recommended as a guide for production. Please see the [installation page](../installation/_index.md) for more complete information on how to install Kyverno in production. + +First, install Kyverno from the latest release manifest. + +```sh +kubectl create -f https://github.com/kyverno/kyverno/releases/download/v1.12.0/install.yaml +``` + +Next, select the quick start guide in which you are interested. Alternatively, start at the top and work your way down. + +## Validate Resources + +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. + +```yaml +kubectl create -f- << EOF +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: require-labels +spec: + validationFailureAction: Enforce + rules: + - name: check-team + match: + any: + - resources: + kinds: + - Pod + validate: + message: "label 'team' is required" + pattern: + metadata: + labels: + team: "?*" +EOF +``` + +Try creating a Deployment without the required label. + +```sh +kubectl create deployment nginx --image=nginx +``` + +You should see an error. + +```sh +error: failed to create deployment: admission webhook "validate.kyverno.svc-fail" denied the request: + +resource Deployment/default/nginx was blocked due to the following policies: + +require-labels: + autogen-check-team: 'validation error: label ''team'' is + required. Rule autogen-check-team failed at path /spec/template/metadata/labels/team/' +``` + +In addition to the error returned, Kyverno also produces an Event in the same Namespace which contains this information. + +{{% alert title="Note" color="info" %}} +Kyverno may be configured to exclude system Namespaces like `kube-system` and `kyverno`. Make sure you create the Deployment in a user-defined Namespace or the `default` Namespace (for testing only). +{{% /alert %}} + +Note that how although the policy matches on Pods, Kyverno blocked the Deployment you just created. This is because Kyverno intelligently applies policies written exclusively for Pods, using its [rule auto-generation](../writing-policies/autogen.md) feature, to all standard Kubernetes Pod controllers including the Deployment above. + +Now, create a Pod with the required label. + +```sh +kubectl run nginx --image nginx --labels team=backend +``` + +This Pod configuration is compliant with the policy and is allowed. + +Now that the Pod exists, wait just a few seconds longer and see what other action Kyverno took. Run the following command to retrieve the Policy Report that Kyverno just created. + +```sh +kubectl get policyreport -o wide +``` + +Notice that there is a single Policy Report with just one result listed under the "PASS" column. This result is due to the Pod we just created having passed the policy. + +```sh +NAME KIND NAME PASS FAIL WARN ERROR SKIP AGE +89044d72-8a1e-4af0-877b-9be727dc3ec4 Pod nginx 1 0 0 0 0 15s +``` + +If you were to describe the above policy report you would see more information about the policy and resource. + +```yaml +Results: + Message: validation rule 'check-team' passed. + Policy: require-labels + Resources: + API Version: v1 + Kind: Pod + Name: nginx + Namespace: default + UID: 07d04dc0-fbb4-479a-b049-a3d63342b354 + Result: pass + Rule: check-team + Scored: true + Source: kyverno + Timestamp: + Nanos: 0 + Seconds: 1683759146 +``` + +Policy reports are helpful in that they are both user- and tool-friendly, based upon an open standard, and separated from the policies which produced them. This separation has the benefit of report access being easy to grant and manage for other users who may not need or have access to Kyverno policies. + +Now that you've experienced validate policies and seen a bit about policy reports, clean up by deleting the policy you created above. + +```sh +kubectl delete clusterpolicy require-labels +``` + +Congratulations, you've just implemented a validation policy in your Kubernetes cluster! For more details on validation policies, see the [validate section](../writing-policies/validate.md). + +## Mutate Resources + +Mutation is the ability to change or "mutate" a resource in some way prior to it being admitted into the cluster. A mutate rule is similar to a validate rule in that it selects some type of resource (like Pods or ConfigMaps) and defines what the desired state should look like. + +Add this Kyverno mutate policy to your cluster. This policy will add the label `team` to any new Pod and give it the value of `bravo` but only if a Pod does not already have this label assigned. Kyverno has the ability to perform basic "if-then" logical decisions in a very easy way making policies trivial to write and read. The `+(team)` notation uses a Kyverno anchor to define the behavior Kyverno should take if the label key is not found. + +```yaml +kubectl create -f- << EOF +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: add-labels +spec: + rules: + - name: add-team + match: + any: + - resources: + kinds: + - Pod + mutate: + patchStrategicMerge: + metadata: + labels: + +(team): bravo +EOF +``` + +Let's now create a new Pod which does not have the desired label defined. + +```sh +kubectl run redis --image redis +``` + +{{% alert title="Note" color="info" %}} +Kyverno may be configured to exclude system Namespaces like `kube-system` and `kyverno`. Make sure you create the Pod in a user-defined Namespace or the `default` Namespace (for testing only). +{{% /alert %}} + +Once the Pod has been created, get the Pod to see if the `team` label was added. + +```sh +kubectl get pod redis --show-labels +``` + +You should see that the label `team=bravo` has been added by Kyverno. + +Try one more Pod, this time one which does already define the `team` label. + +```sh +kubectl run newredis --image redis -l team=alpha +``` + +Get this Pod back and check once again for labels. + +```sh +kubectl get pod newredis --show-labels +``` + +This time, you should see Kyverno did not add the `team` label with the value defined in the policy since one was already found on the Pod. + +Now that you've experienced mutate policies and seen how logic can be written easily, clean up by deleting the policy you created above. + +```sh +kubectl delete clusterpolicy add-labels +``` + +Congratulations, you've just implemented a mutation policy in your Kubernetes cluster! For more details on mutate policies, see the [mutate section](../writing-policies/mutate.md). + +## Generate Resources + +Kyverno has the ability to generate (i.e., create) a new Kubernetes resource based upon a definition stored in a policy. Like both validate and mutate rules, Kyverno generate rules use similar concepts and structures to express policy. The generation ability is both powerful and flexible with one of its most useful aspects being, in addition to the initial generation, it has the ability to continually synchronize the resources it has generated. Generate rules can be a powerful automation tool and can solve many common challenges faced by Kubernetes operators. Let's look at one such use case in this guide. + +We will use a Kyverno generate policy to generate an image pull secret in a new Namespace. + +First, create this Kubernetes Secret in your cluster which will simulate a real image pull secret. + +```sh +kubectl -n default create secret docker-registry regcred \ + --docker-server=myinternalreg.corp.com \ + --docker-username=john.doe \ + --docker-password=Passw0rd123! \ + --docker-email=john.doe@corp.com +``` +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 +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: kyverno:secrets:manage + labels: + rbac.kyverno.io/aggregate-to-background-controller: "true" +rules: +- apiGroups: + - '' + resources: + - secrets + verbs: + - create +EOF +``` + +Next, create the following Kyverno policy. The `sync-secrets` policy will match on any newly-created Namespace and will clone the Secret we just created earlier into that new Namespace. + +```yaml +kubectl create -f- << EOF +apiVersion: kyverno.io/v1 +kind: ClusterPolicy +metadata: + name: sync-secrets +spec: + rules: + - name: sync-image-pull-secret + match: + any: + - resources: + kinds: + - Namespace + generate: + apiVersion: v1 + kind: Secret + name: regcred + namespace: "{{request.object.metadata.name}}" + synchronize: false + clone: + namespace: default + name: regcred +EOF +``` + +Create a new Namespace to test the policy. + +```sh +kubectl create ns mytestns +``` + +Get the Secrets in this new Namespace and see if `regcred` is present. + +```sh +kubectl -n mytestns get secret +``` + +You should see that Kyverno has generated the `regcred` Secret using the source Secret from the `default` Namespace as the template. If you wish, you may also modify the source Secret and watch as Kyverno synchronizes those changes down to wherever it has generated it. + +With a basic understanding of generate policies, clean up by deleting the policy you created above. + +```sh +kubectl delete clusterpolicy sync-secrets +``` + +Congratulations, you've just implemented a generation policy in your Kubernetes cluster! For more details on generate policies, see the [generate section](../writing-policies/generate.md). + + diff --git a/content/en/docs/kyverno-chainsaw/_index.md b/content/en/docs/kyverno-chainsaw/_index.md new file mode 100644 index 000000000..e121b2d70 --- /dev/null +++ b/content/en/docs/kyverno-chainsaw/_index.md @@ -0,0 +1,18 @@ +--- +title: Kyverno Chainsaw +description: Declarative e2e testing +weight: 410 +hide_feedback: true +--- + +Kyverno Chainsaw is a sub-project of Kyverno provides declarative end-to-end testing for Kubernetes controllers. + +
+
+ Website
+
+
+ GitHub
+
+
+
diff --git a/content/en/docs/kyverno-cli/usage/apply.md b/content/en/docs/kyverno-cli/usage/apply.md
index e75e3c114..71acdb958 100644
--- a/content/en/docs/kyverno-cli/usage/apply.md
+++ b/content/en/docs/kyverno-cli/usage/apply.md
@@ -811,7 +811,7 @@ With the `apply` command, Kubernetes ValidatingAdmissionPolicies can be applied
Policy manifest (check-deployment-replicas.yaml):
```yaml
-apiVersion: admissionregistration.k8s.io/v1beta1
+apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
name: check-deployments-replicas
@@ -868,7 +868,7 @@ The below example applies a `ValidatingAdmissionPolicyBinding` along with the po
Policy manifest (check-deployment-replicas.yaml):
```yaml
-apiVersion: admissionregistration.k8s.io/v1beta1
+apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
name: "check-deployment-replicas"
@@ -887,7 +887,7 @@ spec:
validations:
- expression: object.spec.replicas <= 5
---
-apiVersion: admissionregistration.k8s.io/v1beta1
+apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
name: "check-deployment-replicas-binding"
diff --git a/content/en/docs/kyverno-cli/usage/test.md b/content/en/docs/kyverno-cli/usage/test.md
index 545a91923..7472181e9 100644
--- a/content/en/docs/kyverno-cli/usage/test.md
+++ b/content/en/docs/kyverno-cli/usage/test.md
@@ -49,7 +49,7 @@ results:
resources: # optional, primarily for `validate` rules.
-
+
+ Website
+
+
+ GitHub
+
+
+
diff --git a/content/en/docs/kyverno-policy-reporter/_index.md b/content/en/docs/kyverno-policy-reporter/_index.md
new file mode 100644
index 000000000..6214960ce
--- /dev/null
+++ b/content/en/docs/kyverno-policy-reporter/_index.md
@@ -0,0 +1,18 @@
+---
+title: Policy Reporter
+description: Apply Kyverno policies anywhere
+weight: 420
+hide_feedback: true
+---
+
+Policy Reporter is a sub-project of Kyverno that provides in-cluster management of policy reports with a web-based graphical user interface.
+
+
+
+ Website
+
+
+ GitHub
+
+
+
diff --git a/content/en/docs/monitoring/_index.md b/content/en/docs/monitoring/_index.md
index b37819711..ac341ab5e 100644
--- a/content/en/docs/monitoring/_index.md
+++ b/content/en/docs/monitoring/_index.md
@@ -138,11 +138,19 @@ metricsConfig:
# Per Metric configuration, allows disabling metrics, dropping labels and change the bucket boundaries.
metricsExposure:
+ # Counter disabled
+ kyverno_policy_rule_info_total:
+ enabled: false
+ # Histogram disabled
+ kyverno_admission_review_duration_seconds:
+ enabled: false
+ # Counter with customized dimensions
+ kyverno_admission_requests:
+ disabledLabelDimensions: ["resource_namespace", "resource_kind", "resource_request_operation"]
+ # Histogram with custom boundaries and dimensions
kyverno_policy_execution_duration_seconds:
disabledLabelDimensions: ["resource_kind", "resource_namespace", "resource_request_operation"]
bucketBoundaries: [0.005, 0.01, 0.025]
- kyverno_admission_review_duration_seconds:
- enabled: false
...
```
diff --git a/content/en/docs/monitoring/bonus-grafana-dashboard/index.md b/content/en/docs/monitoring/bonus-grafana-dashboard/index.md
index 675c50e53..d577187be 100644
--- a/content/en/docs/monitoring/bonus-grafana-dashboard/index.md
+++ b/content/en/docs/monitoring/bonus-grafana-dashboard/index.md
@@ -40,3 +40,122 @@ curl -fsS https://raw.githubusercontent.com/kyverno/kyverno/main/charts/kyverno/
+
+### Tutorial
+
+```sh
+kind create cluster
+```
+
+Add Helm repositories.
+
+```sh
+helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
+helm repo add kyverno https://kyverno.github.io/kyverno/
+```
+
+Update Helm repositories.
+
+```sh
+helm repo update
+```
+
+Install Kyverno and the kube-prometheus-stack Helm chart.
+
+```sh
+helm install kyverno kyverno/kyverno --namespace kyverno --create-namespace
+helm install monitoring prometheus-community/kube-prometheus-stack -n monitoring --create-namespace
+
+kubectl -n monitoring get po -l "release"
+```
+
+Create the ServiceMonitor resource.
+
+
+Add the following contents to a file named `service-monitor.yaml`.
+
+```yaml
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+ labels:
+ app.kubernetes.io/instance: monitoring
+ chart: kube-prometheus-stack-51.2.0
+ heritage: Helm
+ release: monitoring
+ name: service-monitor-kyverno-service
+ namespace: monitoring
+spec:
+ endpoints:
+ - interval: 60s
+ path: /metrics
+ scheme: http
+ targetPort: 8000
+ tlsConfig:
+ insecureSkipVerify: true
+ namespaceSelector:
+ matchNames:
+ - kyverno
+ selector:
+ matchLabels:
+ app.kubernetes.io/instance: kyverno
+```
+
+Add the appropriate labels.
+
+```sh
+kubectl label ns kyverno app.kubernetes.io/instance=kyverno
+kubectl label ns kyverno app.kubernetes.io/name=kyverno
+```
+
+Create the ServiceMonitor.
+
+```sh
+kubectl apply -f service-monitor.yaml
+```
+
+Restart Deployments and StatefulSets in the `monitoring` Namespace.
+
+```sh
+kubectl rollout restart deploy,sts -n monitoring
+```
+
+Check services in the `monitoring` Namespace.
+
+```sh
+kubectl get svc -n monitoring
+
+NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
+monitoring-kube-prometheus-prometheus ClusterIP 10.96.238.189 -`sum(increase(kyverno_policy_results_total{policy_namespace="default", rule_result="fail"}[24h])) by (rule_type)` +`sum(increase(kyverno_policy_results{policy_namespace="default", rule_result="fail"}[24h])) by (rule_type)` * Tracking the per-minute rate of the number of rule executions triggered by incoming Pod requests over the cluster:
-`rate(kyverno_policy_results_total{resource_kind="Pod", rule_execution_cause="admission_request"}[1m])*60` +`rate(kyverno_policy_results{resource_kind="Pod", rule_execution_cause="admission_request"}[1m])*60` * Tracking the total number of policies over the cluster running as a part of background scans over the last 2 hours:
-`count(increase(kyverno_policy_results_total{rule_execution_cause="background_scan"}[2h]) by (policy_name))` +`count(increase(kyverno_policy_results{rule_execution_cause="background_scan"}[2h]) by (policy_name))` diff --git a/content/en/docs/policy-reports/_index.md b/content/en/docs/policy-reports/_index.md index c117cab4d..04db46c78 100644 --- a/content/en/docs/policy-reports/_index.md +++ b/content/en/docs/policy-reports/_index.md @@ -98,6 +98,66 @@ Entries in a policy report contain a `result` field which can be either `pass`, | warn | The annotation `policies.kyverno.io/scored` has been set to `"false"` in the policy converting otherwise `fail` results to `warn`. | | error | Variable substitution failed outside of preconditions and elsewhere in the rule (ex., in the pattern). | +### Scenarios for skipped evaluations + +A `skip` result signifies that Kyverno decided not to fully evaluate the resource against a specific rule. This is different from a pass where the resource was evaluated and deemed compliant. A `skip` means the rule was essentially bypassed. + +Here's a breakdown of common scenarios resulting in a `skip`: + +1. **Preconditions Not Met:** + +This is the most frequent reason for a skip. If a rule has preconditions defined and any of the conditions within the any or all blocks evaluate to FALSE, the entire rule is skipped. Kyverno won't even attempt to apply the pattern, effectively bypassing the rule. + +2. **Policy Exceptions:** + +Kyverno allows you to define exceptions to policies using PolicyException resources. If an exception exists that matches a specific resource and rule, Kyverno will skip the rule for that resource. + +3. **Conditional Anchors `()` with Unmet Conditions:** + +When using a conditional anchor, the corresponding section is skipped if the condition within the anchor evaluates to FALSE. + +4. **Global Anchors `<()` with Unmet Conditions:** + +Similar to conditional anchors, if the condition inside a global anchor is FALSE, the entire rule is skipped. The difference is that global anchors apply to the whole rule, not just a specific section. + +5. **Anchor Logic Resulting in Skip:** + +As explained in the [validate documentation](../writing-policies/validate.md), a combination of anchors and their evaluation results can lead to a skip. Specifically, a conditional anchor might be skipped, but if it's a sibling to another condition that results in a pass or fail, the overall result will reflect that of the sibling, potentially masking the skip. + +*Example:* If we have the following policy: + +```yaml +spec: + =(initContainers): + - (name): "!istio-init" + =(securityContext): + =(runAsUser): ">0" + =(containers): + - =(securityContext): + =(runAsUser): ">0" +``` + +The following resource would result in pass: + +```yaml +spec: + initContainers: + - name: istio-init + securityContext: + runAsUser: 0 + containers: + - name: nginx + image: nginx +``` + +That's because for the `initContainers` block the condition isn't met so it's a skip. But the `containers` block is a pass. So the overall result is a pass. + +**Key Points to Remember:** + +* A skip result is not a failure; it's a deliberate bypass based on predefined conditions or exceptions. +* Understanding the distinction between pass and skip is crucial for accurately interpreting policy report data. +* When troubleshooting a skip, carefully examine preconditions, exceptions, and the logic within your anchors to pinpoint the reason for the bypass. + ## Viewing policy report summaries You can view a summary of the Namespaced policy reports using the following command: diff --git a/content/en/docs/policy-reports/validatingadmissionpolicy-reports.md b/content/en/docs/policy-reports/validatingadmissionpolicy-reports.md index 2040e3e28..9baf38b28 100644 --- a/content/en/docs/policy-reports/validatingadmissionpolicy-reports.md +++ b/content/en/docs/policy-reports/validatingadmissionpolicy-reports.md @@ -14,7 +14,7 @@ To configure Kyverno to generate reports for ValidatingAdmissionPolicies, set th Create a ValidatingAdmissionPolicy that checks the Deployment replicas and a ValidatingAdmissionPolicyBinding that binds the policy to a namespace whose labels set to `environment: staging`. ```yaml -apiVersion: admissionregistration.k8s.io/v1beta1 +apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingAdmissionPolicy metadata: name: "check-deployment-replicas" @@ -33,7 +33,7 @@ spec: validations: - expression: object.spec.replicas <= 5 --- -apiVersion: admissionregistration.k8s.io/v1beta1 +apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingAdmissionPolicyBinding metadata: name: "check-deployment-replicas-binding" diff --git a/content/en/docs/releases/_index.md b/content/en/docs/releases/_index.md index dc4146ab1..30c7b7120 100644 --- a/content/en/docs/releases/_index.md +++ b/content/en/docs/releases/_index.md @@ -65,4 +65,4 @@ A minor release will contain a mix of features, enhancements, and bug fixes. Major features follow the [Kyverno Design Proposal (KDP)](https://github.com/kyverno/KDP/) process. -During the start of a release, there may be many issues assigned to the release milestone. The priorities for the release are discussed in the weekly contributor's meetings. As the release progresses several issues may be moved to the next milestone. Hence, if an issue is important it is important to advocate its priority early in the release cycle. +During the start of a release, there may be many issues assigned to the release milestone. The priorities for the release are discussed in the weekly maintainer's meetings. As the release progresses several issues may be moved to the next milestone. Hence, if an issue is important it is important to advocate its priority early in the release cycle. diff --git a/content/en/docs/security/_index.md b/content/en/docs/security/_index.md index 8c26dca4b..1267bd329 100644 --- a/content/en/docs/security/_index.md +++ b/content/en/docs/security/_index.md @@ -62,7 +62,7 @@ With each release, the following artifacts are uploaded (where CLI binaries incl ## Verifying Kyverno Container Images -Kyverno container images are signed using Cosign and the [keyless signing feature](https://docs.sigstore.dev/cosign/verify/). The signatures are stored in a separate repository from the container image they reference located at `ghcr.io/kyverno/signatures`. To verify the container image using Cosign v1.x, follow the steps below. +Kyverno container images are signed using Cosign and the [keyless signing feature](https://docs.sigstore.dev/cosign/verifying/verify/). The signatures are stored in a separate repository from the container image they reference located at `ghcr.io/kyverno/signatures`. To verify the container image using Cosign v1.x, follow the steps below. 1. Install [Cosign](https://github.com/sigstore/cosign#installation) 2. Configure the Kyverno signature repository: @@ -242,7 +242,7 @@ Kyverno Pods are configured to follow security best practices and conform to the ### RBAC -The Kyverno RBAC configurations are described in the [installation](../installation/customization.md#roles-and-permissions) section. +The Kyverno RBAC configurations are described in the [installation](../installation/customization.md#role-based-access-controls) section. Use the following command to view all Kyverno roles: @@ -352,7 +352,7 @@ The sections below list each threat, mitigation, and provide Kyverno specific de * [Mitigation ID 1 - RBAC rights are strictly controlled](https://github.com/kubernetes/sig-security/blob/main/sig-security-docs/papers/admission-control/kubernetes-admission-control-threat-model.md#mitigation-id-1---rbac-rights-are-strictly-controlled) - Kyverno RBAC configurations are described in the [installation section](../installation/customization.md#roles-and-permissions). The `kyverno:admission-controller` role is used by Kyverno to configure webhooks. It is important to limit Kyverno to the required permissions and audit changes in the RBAC roles and role bindings. + Kyverno RBAC configurations are described in the [installation section](../installation/customization.md#role-based-access-controls). The `kyverno:admission-controller` role is used by Kyverno to configure webhooks. It is important to limit Kyverno to the required permissions and audit changes in the RBAC roles and role bindings. ### Threat ID 5 - Attacker gets access to valid credentials for the webhook @@ -420,7 +420,7 @@ The sections below list each threat, mitigation, and provide Kyverno specific de * [Mitigation ID 1 - RBAC rights are strictly controlled](https://github.com/kubernetes/sig-security/blob/main/sig-security-docs/papers/admission-control/kubernetes-admission-control-threat-model.md#mitigation-id-1---rbac-rights-are-strictly-controlled) - Kyverno RBAC configurations are described in the [configuration section](../installation/customization.md#roles-and-permissions). The `kyverno:admission-controller` role is used by Kyverno to configure webhooks. It is important to limit Kyverno to the required permissions and audit changes in the RBAC roles and role bindings. + Kyverno RBAC configurations are described in the [configuration section](../installation/customization.md#role-based-access-controls). The `kyverno:admission-controller` role is used by Kyverno to configure webhooks. It is important to limit Kyverno to the required permissions and audit changes in the RBAC roles and role bindings. Kyverno excludes certain critical system Namespaces by default including the Kyverno Namespace itself. These exclusions can be managed and configured via the [ConfigMap](../installation/customization.md#configmap-keys). diff --git a/content/en/docs/troubleshooting/_index.md b/content/en/docs/troubleshooting/_index.md index f850dab0f..c5e7c6285 100644 --- a/content/en/docs/troubleshooting/_index.md +++ b/content/en/docs/troubleshooting/_index.md @@ -104,7 +104,7 @@ You can also follow the steps on the [Kyverno wiki](https://github.com/kyverno/k **Symptom**: I'm using AKS and Kyverno is using too much memory or CPU or produces many audit logs -**Solution**: On AKS the Kyverno webhooks will be mutated by the AKS [Admissions Enforcer](https://learn.microsoft.com/en-us/azure/aks/faq#can-admission-controller-webhooks-impact-kube-system-and-internal-aks-namespaces) plugin, that can lead to an endless update loop. To prevent that behavior, set the annotation `"admissions.enforcer/disabled": true` to all Kyverno webhooks. When installing via Helm, the annotation can be added with `config.webhookAnnotations`. +**Solution**: On AKS the Kyverno webhooks will be mutated by the AKS [Admissions Enforcer](https://learn.microsoft.com/en-us/azure/aks/faq#can-admission-controller-webhooks-impact-kube-system-and-internal-aks-namespaces) plugin, that can lead to an endless update loop. To prevent that behavior, set the annotation `"admissions.enforcer/disabled": true` to all Kyverno webhooks. When installing via Helm, the annotation can be added with `config.webhookAnnotations`. As of Kyverno 1.12, this configuration is enabled by default. ## Kyverno is slow to respond @@ -134,7 +134,7 @@ You can also follow the steps on the [Kyverno wiki](https://github.com/kyverno/k **Symptom**: I'm using GKE and after installing Kyverno, my cluster is either broken or I'm seeing timeouts and other issues. -**Solution**: Private GKE clusters do not allow certain communications from the control planes to the workers, which Kyverno requires to receive webhooks from the API server. In order to resolve this issue, create a firewall rule which allows the control plane to speak to workers on the Kyverno TCP port which, by default at this time, is 9443. +**Solution**: Private GKE clusters do not allow certain communications from the control planes to the workers, which Kyverno requires to receive webhooks from the API server. In order to resolve this issue, create a firewall rule which allows the control plane to speak to workers on the Kyverno TCP port which, by default at this time, is 9443. For more details, see the [GKE documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules). ## Kyverno fails on EKS diff --git a/content/en/docs/writing-policies/cleanup.md b/content/en/docs/writing-policies/cleanup.md index 68a9ed6b5..8fba6ad83 100644 --- a/content/en/docs/writing-policies/cleanup.md +++ b/content/en/docs/writing-policies/cleanup.md @@ -5,10 +5,6 @@ description: > weight: 70 --- -{{% alert title="Warning" color="warning" %}} -Cleanup policies are a **beta** feature. It is not ready for production usage and there may be breaking changes. Normal semantic versioning and compatibility rules will not apply. -{{% /alert %}} - Kyverno has the ability to cleanup (i.e., delete) existing resources in a cluster in two different ways. The first way is via a declarative policy definition in either a `CleanupPolicy` or `ClusterCleanupPolicy`. See the section on [cleanup policies](#cleanup-policy) below for more details. The second way is via a reserved time-to-live (TTL) label added to a resource. See the [cleanup label](#cleanup-label) section for further details. ## Cleanup Policy @@ -16,7 +12,7 @@ Kyverno has the ability to cleanup (i.e., delete) existing resources in a cluste Similar to other policies which can validate, mutate, generate, or verify images in resources, Kyverno can cleanup resources by defining a new policy type called a `CleanupPolicy`. Cleanup policies come in both cluster-scoped and Namespaced flavors; a `ClusterCleanupPolicy` being cluster scoped and a `CleanupPolicy` being Namespaced. A cleanup policy uses the familiar `match`/`exclude` block to select and exclude resources which are subjected to the cleanup process. A `conditions{}` block (optional) uses common expressions similar to those found in [preconditions](preconditions.md) and [deny rules](validate.md#deny-rules) to query the contents of the selected resources in order to refine the selection process. [Context variables](external-data-sources.md) (optional) can be used to fetch data from other resources to factor into the cleanup process. And, lastly, a `schedule` field defines, in cron format, when the rule should run. {{% alert title="Note" color="info" %}} -Since cleanup policies always operate against existing resources in a cluster, policies created with `subjects`, `Roles`, or `ClusterRoles` in the `match`/`exclude` block are not allowed since this information is only known at admission time. +Since cleanup policies always operate against existing resources in a cluster, policies created with `subjects`, `Roles`, or `ClusterRoles` in the `match`/`exclude` block are not allowed since this information is only known at admission time. Additionally, `operations[]`, while permitted, are ignored as the only trigger is schedule based. {{% /alert %}} 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. diff --git a/content/en/docs/writing-policies/exceptions.md b/content/en/docs/writing-policies/exceptions.md index 89b019cdc..8ec57660d 100644 --- a/content/en/docs/writing-policies/exceptions.md +++ b/content/en/docs/writing-policies/exceptions.md @@ -5,10 +5,6 @@ description: > weight: 80 --- -{{% alert title="Warning" color="warning" %}} -Policy exceptions are a **beta** feature. Normal semantic versioning and compatibility rules will not apply. -{{% /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. diff --git a/content/en/docs/writing-policies/external-data-sources.md b/content/en/docs/writing-policies/external-data-sources.md index 43a71f72c..3d64e9153 100644 --- a/content/en/docs/writing-policies/external-data-sources.md +++ b/content/en/docs/writing-policies/external-data-sources.md @@ -714,6 +714,20 @@ The data returned by GlobalContextEntries may vary depending on whether it is a 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 %}} +#### Default values for API calls +In the case where the api server returns an error, `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 +... +``` + ## Variables from Image Registries A context can also be used to store metadata on an OCI image by using the `imageRegistry` context type. By using this external data source, a Kyverno policy can make decisions based on details of the container image that occurs as part of an incoming resource. @@ -736,6 +750,7 @@ the output `imageData` variable will have a structure which looks like the follo "registry": "ghcr.io", "repository": "kyverno/kyverno", "identifier": "latest", + "imageIndex": imageIndex, "manifest": manifest, "configData": config, } @@ -755,7 +770,7 @@ The `imageData` variable represents a "normalized" view of an image after any re ``` {{% /alert %}} -The `manifest` and `config` keys contain the output from `crane manifest
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 ce1db8b8a..1d1e816e4 100644
--- a/content/en/docs/writing-policies/verify-images/notary/_index.md
+++ b/content/en/docs/writing-policies/verify-images/notary/_index.md
@@ -40,18 +40,32 @@ ghcr.io/kyverno/test-verify-image@sha256:b31bfb4d0213f254d361e0079deaaebefa4f82b
You can also use an OCI registry client to discover signatures and attestations for an image.
```sh
-oras discover ghcr.io/kyverno/test-verify-image:signed -o tree
-ghcr.io/kyverno/test-verify-image:signed
+oras discover -o tree ghcr.io/kyverno/test-verify-image:signed
+ghcr.io/kyverno/test-verify-image@sha256:b31bfb4d0213f254d361e0079deaaebefa4f82ba7aa76ef82e90b4935ad5b105
├── application/vnd.cncf.notary.signature
-│ └── sha256:7f870420d92765b42cec0f71ee8e25bf39b692f64d95d6f6607e9e6e54300265
+│ ├── sha256:7f870420d92765b42cec0f71ee8e25bf39b692f64d95d6f6607e9e6e54300265
+│ └── sha256:f7d941ed9e93a1ff1d5dee3b091144a87dae1d73481d5be93aa65258a110c689
├── vulnerability-scan
-│ └── sha256:f89cb7a0748c63a674d157ca84d725ff3ac09cc2d4aee9d0ec4315e0fe92a5fd
-│ └── application/vnd.cncf.notary.signature
-│ └── sha256:ec45844601244aa08ac750f44def3fd48ddacb736d26b83dde9f5d8ac646c2f3
-└── sbom/cyclone-dx
- └── sha256:8cad9bd6de426683424a204697dd48b55abcd6bb6b4930ad9d8ade99ae165414
+│ └── sha256:f89cb7a0748c63a674d157ca84d725ff3ac09cc2d4aee9d0ec4315e0fe92a5fd
+│ └── application/vnd.cncf.notary.signature
+│ └── sha256:ec45844601244aa08ac750f44def3fd48ddacb736d26b83dde9f5d8ac646c2f3
+├── sbom/cyclone-dx
+│ └── sha256:8cad9bd6de426683424a204697dd48b55abcd6bb6b4930ad9d8ade99ae165414
+│ └── application/vnd.cncf.notary.signature
+│ └── sha256:61f3e42f017b72f4277c78a7a42ff2ad8f872811324cd984830dfaeb4030c322
+├── application/vnd.cyclonedx+json
+│ └── sha256:aa886b475b431a37baa0e803765a9212f0accece0b82a131ebafd43ea78fa1f8
+│ └── application/vnd.cncf.notary.signature
+│ ├── sha256:00c5f96577878d79b545d424884886c37e270fac5996f17330d77a01a96801eb
+│ └── sha256:f3dc4687f5654ea8c2bc8da4e831d22a067298e8651fb59d55565dee58e94e2d
+├── cyclonedx/vex
+│ └── sha256:c058f08c9103bb676fcd0b98e41face2436e0a16f3d1c8255797b916ab5daa8a
+│ └── application/vnd.cncf.notary.signature
+│ └── sha256:79edc8936a4fb8758b9cb2b8603a1c7903f53261c425efb0cd85b09715eb6dfa
+└── trivy/scan
+ └── sha256:a75ac963617462fdfe6a3847d17e5519465dfb069f92870050cce5269e7cbd7b
└── application/vnd.cncf.notary.signature
- └── sha256:61f3e42f017b72f4277c78a7a42ff2ad8f872811324cd984830dfaeb4030c322
+ └── sha256:d1e2b2ba837c164c282cf389594791a190df872cf7712b4d91aa10a3520a8460
```
## Verifying Image Signatures
@@ -145,15 +159,29 @@ Consider the following image: `ghcr.io/kyverno/test-verify-image:signed`
```
ghcr.io/kyverno/test-verify-image:signed
├── application/vnd.cncf.notary.signature
-│ └── sha256:7f870420d92765b42cec0f71ee8e25bf39b692f64d95d6f6607e9e6e54300265
+│ ├── sha256:7f870420d92765b42cec0f71ee8e25bf39b692f64d95d6f6607e9e6e54300265
+│ └── sha256:f7d941ed9e93a1ff1d5dee3b091144a87dae1d73481d5be93aa65258a110c689
├── vulnerability-scan
-│ └── sha256:f89cb7a0748c63a674d157ca84d725ff3ac09cc2d4aee9d0ec4315e0fe92a5fd
-│ └── application/vnd.cncf.notary.signature
-│ └── sha256:ec45844601244aa08ac750f44def3fd48ddacb736d26b83dde9f5d8ac646c2f3
-└── sbom/cyclone-dx
- └── sha256:8cad9bd6de426683424a204697dd48b55abcd6bb6b4930ad9d8ade99ae165414
- └── application/vnd.cncf.notary.signature
- └── sha256:61f3e42f017b72f4277c78a7a42ff2ad8f872811324cd984830dfaeb4030c322
+│ └── sha256:f89cb7a0748c63a674d157ca84d725ff3ac09cc2d4aee9d0ec4315e0fe92a5fd
+│ └── application/vnd.cncf.notary.signature
+│ └── sha256:ec45844601244aa08ac750f44def3fd48ddacb736d26b83dde9f5d8ac646c2f3
+├── sbom/cyclone-dx
+│ └── sha256:8cad9bd6de426683424a204697dd48b55abcd6bb6b4930ad9d8ade99ae165414
+│ └── application/vnd.cncf.notary.signature
+│ └── sha256:61f3e42f017b72f4277c78a7a42ff2ad8f872811324cd984830dfaeb4030c322
+├── application/vnd.cyclonedx+json
+│ └── sha256:aa886b475b431a37baa0e803765a9212f0accece0b82a131ebafd43ea78fa1f8
+│ └── application/vnd.cncf.notary.signature
+│ ├── sha256:00c5f96577878d79b545d424884886c37e270fac5996f17330d77a01a96801eb
+│ └── sha256:f3dc4687f5654ea8c2bc8da4e831d22a067298e8651fb59d55565dee58e94e2d
+├── cyclonedx/vex
+│ └── sha256:c058f08c9103bb676fcd0b98e41face2436e0a16f3d1c8255797b916ab5daa8a
+│ └── application/vnd.cncf.notary.signature
+│ └── sha256:79edc8936a4fb8758b9cb2b8603a1c7903f53261c425efb0cd85b09715eb6dfa
+└── trivy/scan
+ └── sha256:a75ac963617462fdfe6a3847d17e5519465dfb069f92870050cce5269e7cbd7b
+ └── application/vnd.cncf.notary.signature
+ └── sha256:d1e2b2ba837c164c282cf389594791a190df872cf7712b4d91aa10a3520a8460
```
This image has:
@@ -161,6 +189,9 @@ This image has:
1. A notary signature.
2. A vulnerability scan report, signed using notary.
3. A CycloneDX SBOM, signed using notary.
+4. A CycloneDX VEX report, signed using notary.
+5. A Trivy scan report, signed using notary.
+
This policy checks the signature in the repo `ghcr.io/kyverno/test-verify-image` and ensures that it has been signed by verifying its signature against the provided certificates:
```yaml
@@ -227,4 +258,116 @@ After this policy is applied, Kyverno will verify the signature on the sbom/cycl
```sh
kubectl run test --image=ghcr.io/kyverno/test-verify-image:signed --dry-run=server
pod/test created (server dry run)
-```
\ No newline at end of file
+```
+
+### Validation across multiple image attestations
+
+Consider the image: `ghcr.io/kyverno/test-verify-image:signed` which image has:
+
+1. A notary signature.
+2. A vulnerability scan report, signed using notary.
+3. A CycloneDX VEX report, signed using notary.
+
+This policy checks:
+1. The signature in the repo `ghcr.io/kyverno/test-verify-image`
+2. Ensures that it has a vulnerability scan report of type `trivy/vulnerability`, and a CycloneDX VEX report of type `vex/cyclone-dx`, both are signed using the given certificate.
+3. All the vulnerabilities found in the trivy scan report should be allowed in the vex report.
+
+```yaml
+apiVersion: kyverno.io/v1
+kind: ClusterPolicy
+metadata:
+ name: check-image-attestation
+spec:
+ validationFailureAction: Enforce
+ webhookTimeoutSeconds: 30
+ failurePolicy: Fail
+ rules:
+ - name: verify-attestation-notary
+ match:
+ any:
+ - resources:
+ kinds:
+ - Pod
+ context:
+ - name: keys
+ configMap:
+ name: keys
+ namespace: notary-verify-attestation
+ verifyImages:
+ - type: Notary
+ imageReferences:
+ - "ghcr.io/kyverno/test-verify-image*"
+ attestations:
+ - type: trivy/vulnerability
+ name: trivy
+ attestors:
+ - entries:
+ - certificates:
+ cert: |-
+ -----BEGIN CERTIFICATE-----
+ MIIDmDCCAoCgAwIBAgIUCntgF4FftePAhEa6nZTsu/NMT3cwDQYJKoZIhvcNAQEL
+ BQAwTDELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAldBMRAwDgYDVQQHDAdTZWF0dGxl
+ MQ8wDQYDVQQKDAZOb3RhcnkxDTALBgNVBAMMBHRlc3QwHhcNMjQwNjEwMTYzMTQ2
+ WhcNMzQwNjA4MTYzMTQ2WjBMMQswCQYDVQQGEwJVUzELMAkGA1UECAwCV0ExEDAO
+ BgNVBAcMB1NlYXR0bGUxDzANBgNVBAoMBk5vdGFyeTENMAsGA1UEAwwEdGVzdDCC
+ ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJkEGqbILiWye6C1Jz+jwwDY
+ k/rovpXzxS+EQDvfj/YKvx37Kr4cjboJORu3wtzICWhPUtVWZ21ShfjerKgNq0iB
+ mrlF4cqz2KcOfuUT3XBglH/NwhEAqOrGPQrMsoQEFWgnilr0RTc+j4vDnkdkcTj2
+ K/qPhQHRAeb97TdvFCqcZfAGqiOVUqzDGxd2INz/fJd4/nYRX3LJBn9pUGxqRwZV
+ ElP5B/aCBjJDdh6tAElT5aDnLGAB+3+W2YwG342ELyAl2ILpbSRUpKLNAfKEd7Nj
+ 1moIl4or5AIlTkgewZ/AK68HPFJEV3SwNbzkgAC+/mLVCD8tqu0o0ziyIUJtoQMC
+ AwEAAaNyMHAwHQYDVR0OBBYEFFTIzCppwv0vZnAVmETPm1CfMdcYMB8GA1UdIwQY
+ MBaAFFTIzCppwv0vZnAVmETPm1CfMdcYMAkGA1UdEwQCMAAwDgYDVR0PAQH/BAQD
+ AgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMDMA0GCSqGSIb3DQEBCwUAA4IBAQB8/vfP
+ /TQ3X80JEZDsttdvd9NLm08bTJ/T+nh0DIiV10aHymQT9/u+iahfm1+7mj+uv8LS
+ Y63LepQCX5p9SoFzt513pbNYXMBbRrOKpth3DD49IPL2Gce86AFGydfrakd86CL1
+ 9MhFeWhtRf0KndyUX8J2s7jbpoN8HrN4/wZygiEqbQWZG8YtIZ9EewmoVMYirQqH
+ EvW93NcgmjiELuhjndcT/kHjhf8fUAgSuxiPIy6ern02fJjw40KzgiKNvxMoI9su
+ G2zu6gXmxkw+x0SMe9kX+Rg4hCIjTUM7dc66XL5LcTp4S5YEZNVC40/FgTIZoK0e
+ r1dC2/Y1SmmrIoA1
+ -----END CERTIFICATE-----
+ - type: vex/cyclone-dx
+ name: vex
+ attestors:
+ - entries:
+ - certificates:
+ cert: |-
+ -----BEGIN CERTIFICATE-----
+ MIIDmDCCAoCgAwIBAgIUCntgF4FftePAhEa6nZTsu/NMT3cwDQYJKoZIhvcNAQEL
+ BQAwTDELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAldBMRAwDgYDVQQHDAdTZWF0dGxl
+ MQ8wDQYDVQQKDAZOb3RhcnkxDTALBgNVBAMMBHRlc3QwHhcNMjQwNjEwMTYzMTQ2
+ WhcNMzQwNjA4MTYzMTQ2WjBMMQswCQYDVQQGEwJVUzELMAkGA1UECAwCV0ExEDAO
+ BgNVBAcMB1NlYXR0bGUxDzANBgNVBAoMBk5vdGFyeTENMAsGA1UEAwwEdGVzdDCC
+ ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJkEGqbILiWye6C1Jz+jwwDY
+ k/rovpXzxS+EQDvfj/YKvx37Kr4cjboJORu3wtzICWhPUtVWZ21ShfjerKgNq0iB
+ mrlF4cqz2KcOfuUT3XBglH/NwhEAqOrGPQrMsoQEFWgnilr0RTc+j4vDnkdkcTj2
+ K/qPhQHRAeb97TdvFCqcZfAGqiOVUqzDGxd2INz/fJd4/nYRX3LJBn9pUGxqRwZV
+ ElP5B/aCBjJDdh6tAElT5aDnLGAB+3+W2YwG342ELyAl2ILpbSRUpKLNAfKEd7Nj
+ 1moIl4or5AIlTkgewZ/AK68HPFJEV3SwNbzkgAC+/mLVCD8tqu0o0ziyIUJtoQMC
+ AwEAAaNyMHAwHQYDVR0OBBYEFFTIzCppwv0vZnAVmETPm1CfMdcYMB8GA1UdIwQY
+ MBaAFFTIzCppwv0vZnAVmETPm1CfMdcYMAkGA1UdEwQCMAAwDgYDVR0PAQH/BAQD
+ AgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMDMA0GCSqGSIb3DQEBCwUAA4IBAQB8/vfP
+ /TQ3X80JEZDsttdvd9NLm08bTJ/T+nh0DIiV10aHymQT9/u+iahfm1+7mj+uv8LS
+ Y63LepQCX5p9SoFzt513pbNYXMBbRrOKpth3DD49IPL2Gce86AFGydfrakd86CL1
+ 9MhFeWhtRf0KndyUX8J2s7jbpoN8HrN4/wZygiEqbQWZG8YtIZ9EewmoVMYirQqH
+ EvW93NcgmjiELuhjndcT/kHjhf8fUAgSuxiPIy6ern02fJjw40KzgiKNvxMoI9su
+ G2zu6gXmxkw+x0SMe9kX+Rg4hCIjTUM7dc66XL5LcTp4S5YEZNVC40/FgTIZoK0e
+ r1dC2/Y1SmmrIoA1
+ -----END CERTIFICATE-----
+ validate:
+ deny:
+ conditions:
+ any:
+ - key: '{{ trivy.Vulnerabilities[*].VulnerabilityID }}'
+ operator: AnyNotIn
+ value: '{{ vex.vulnerabilities[*].id }}'
+ message: All vulnerabilities in trivy and vex should be same
+```
+
+After this policy is applied, Kyverno will verify the signatures in the image and the attestations and then evaluate the validate deny condition which checks all the vulneribilities in trivy report are there in vex report.
+
+```sh
+kubectl run test --image=ghcr.io/kyverno/test-verify-image:signed --dry-run=server
+pod/test created (server dry run)
+```
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 b66e2890b..01dfc66d3 100644
--- a/content/en/docs/writing-policies/verify-images/sigstore/_index.md
+++ b/content/en/docs/writing-policies/verify-images/sigstore/_index.md
@@ -90,6 +90,48 @@ check-image:
invalid signature'
```
+### Verifying Sigstore bundles
+
+Container images signatures that use [sigstore bundle format](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto) such as [GitHub Artifact Attestation](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations) can be verified using verification type `SigstoreBundle`. The following example verifies images containing SLSA Provenance created and signed using GitHub Artifact Attestation.
+
+```yaml
+apiVersion: kyverno.io/v1
+kind: ClusterPolicy
+metadata:
+ annotations:
+ pod-policies.kyverno.io/autogen-controllers: none
+ name: sigstore-attestation-verification
+spec:
+ background: false
+ validationFailureAction: Enforce
+ webhookTimeoutSeconds: 30
+ rules:
+ - match:
+ any:
+ - resources:
+ kinds:
+ - Pod
+ name: sigstore-attestation-verification
+ verifyImages:
+ - imageReferences:
+ - "*"
+ type: SigstoreBundle
+ attestations:
+ - attestors:
+ - entries:
+ - keyless:
+ issuer: https://token.actions.githubusercontent.com
+ subject: https://github.com/vishal-chdhry/artifact-attestation-example/.github/workflows/build-attested-image.yaml@refs/heads/main
+ rekor:
+ url: https://rekor.sigstore.dev
+ conditions:
+ - all:
+ - key: '{{ buildDefinition.buildType }}'
+ operator: Equals
+ value: https://actions.github.io/buildtypes/workflow/v1
+ type: https://slsa.dev/provenance/v1
+```
+
### Skipping Image References
`skipImageReferences` can be used to precisely filter image references that should be verified by a policy. A list of references can be specified in `skipImageReferences` and images that match those references will be excluded from image verification process. The following example will match all images from `ghcr.io` but will skip images from `ghcr.io/trusted`.
@@ -435,7 +477,7 @@ This image can now be verified using the leaf or root certificates.
## Keyless signing and verification
-The following policy verifies an image signed using ephemeral keys and signing data stored in a transparency log, known as [keyless signing](https://docs.sigstore.dev/signing/overview/):
+The following policy verifies an image signed using ephemeral keys and signing data stored in a transparency log, known as [keyless signing](https://docs.sigstore.dev/cosign/signing/overview/):
```yaml
apiVersion: kyverno.io/v1
@@ -508,7 +550,7 @@ The supported formats include:
* gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY]
* hashivault://[KEY]
-Refer to https://docs.sigstore.dev/cosign/kms_support for additional details.
+Refer to https://docs.sigstore.dev/cosign/key_management/overview/ for additional details.
### Enabling IRSA to access AWS KMS
@@ -646,67 +688,42 @@ spec:
Kyverno does not by default have the same chain of trust as the underlying Kubernetes Nodes nor is it able to access them due to security concerns. Because the Nodes in your cluster can pull an image from a private registry (even if no authentication is required) does not mean Kyverno can. Kyverno ships with trust for the most common third-party certificate authorities and has no knowledge of internal PKI which may be in use by your private registry. Without the chain of trust established, Kyverno will not be able to fetch image metadata, signatures, or other OCI artifacts from a registry. Perform the following steps to present the necessary root certificates to Kyverno to establish trust.
-1. There are two potential ways to have Kyverno trust your private registry. The first allows replacing all the certificates Kyverno trusts by default with only those needed by your internal registry. This has the benefit of being a simpler process at the cost of Kyverno losing trust for any public registries such as Docker Hub, Amazon ECR, GitHub Container Registry, etc. The second involves providing Kyverno with the same trust as your Nodes. Often times this trust includes the aforementioned public certificate authorities but in other cases may not. This first step involves the latter process.
+There are two possible methods to present Kyverno with custom certificates. The first is to replace the internal default certificate store with your custom one in which all necessary certificates are stored in a ConfigMap. The second is to allow Kyverno to mount a hostPath volume on the underlying Node so it can read the same certificate store as the host.
+
+#### Replace
-Update your internal `ca-certificates` bundle by adding your private certificate authorities root certificate to the bundle and regenerating it. Many Linux distributions have slightly different processes, but it is documented [here](https://ubuntu.com/server/docs/security-trust-store) for Ubuntu as an example. If this process has already been done and your Nodes are using this, simply copy the contents out and proceed to the next step.
+Using this first method, you replace Kyverno's internal certificate store with your own. The certificate(s) you supply using this method will overwrite the entire certificate store Kyverno ships with by default which may prevent you from accessing public registries signed by third-party certificate authorities. This method may be favorable when you are only using private, internal registries with no need to contact external services.
-2. Create a ConfigMap in your cluster, preferably in the Kyverno Namespace, which has these contents stored as a multi-line value. It should look something like the below.
+To use this method, set the Helm value `global.caCertificates.data` along with the certificate(s) you wish Kyverno to trust. An example snippet is shown below.
```yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
- name: kyverno-certs
- namespace: kyverno
-data:
- ca-certificates: |
- -----BEGIN CERTIFICATE-----
- MIIH0zCCBbugAwIBAgIIXsO3pkN/pOAwDQYJKoZIhvcNAQEFBQAwQjESMBAGA1UE
- AwwJQUNDVlJBSVoxMRAwDgYDVQQLDAdQS0lBQ0NWMQ0wCwYDVQQKDARBQ0NWMQsw
- CQYDVQQGEwJFUzAeFw0xMTA1MDUwOTM3MzdaFw0zMDEyMzEwOTM3MzdaMEIxEjAQ
- BgNVBAMMCUFDQ1ZSQUlaMTEQMA4GA1UECwwHUEtJQUNDVjENMAsGA1UECgwEQUND
-Created by
-
+
@@ -22,6 +22,7 @@
{{ with .Site.Params.copyright }}© {{ now.Year}} {{ .}} {{ T "footer_all_rights_reserved" }}{{ end }}
{{ define "footer-links-block" }}
diff --git a/netlify.toml b/netlify.toml
index 77fa86e0b..ea2573b16 100644
--- a/netlify.toml
+++ b/netlify.toml
@@ -45,4 +45,9 @@ status = 200
[[headers]]
for = "/*"
[headers.values]
- X-Frame-Options = "SAMEORIGIN"
\ No newline at end of file
+ X-Frame-Options = "SAMEORIGIN"
+
+[[headers]]
+ for = "/blog/index.xml"
+ [headers.values]
+ access-control-allow-origin = "*"
diff --git a/render/render.go b/render/render.go
index 94e0f6c54..674d37422 100644
--- a/render/render.go
+++ b/render/render.go
@@ -136,6 +136,11 @@ func render(git *gitInfo, outdir string) error {
if err != nil {
return fmt.Errorf("failed to clean directory %s: %v", outdir, err)
}
+
+ err = removeEmptyDirs(outdir)
+ if err != nil {
+ return fmt.Errorf("failed to clean directory %s: %v", outdir, err)
+ }
}
for _, yamlFilePath := range yamls {
@@ -205,45 +210,94 @@ func render(git *gitInfo, outdir string) error {
return nil
}
-// deleteMarkdownFiles deletes all .md files except "_index.md"
-func deleteMarkdownFiles(outdir string) error {
- d, err := os.Open(outdir)
+// removeEmptyDirs collects directories and deletes empty ones from deepest to shallowest
+func removeEmptyDirs(dir string) error {
+ var dirs []string
+
+ // First, traverse the directory tree to collect directories
+ err := filepath.WalkDir(dir, func(path string, d os.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+ if d.IsDir() {
+ dirs = append(dirs, path)
+ }
+ return nil
+ })
if err != nil {
return err
}
- defer func() {
- if err := d.Close(); err != nil {
+ // Sort directories by depth (deepest directories first)
+ sort.Slice(dirs, func(i, j int) bool {
+ return len(dirs[i]) > len(dirs[j])
+ })
+
+ // Attempt to delete directories, starting from the deepest
+ for _, path := range dirs {
+ empty, err := isEmptyDir(path)
+ if err != nil {
+ return err
+ }
+ if empty {
if Verbose {
- log.Printf("failed to close output dir %s: %v", outdir, err)
+ log.Printf("Removing empty directory: %s\n", path)
+ }
+ err := os.Remove(path)
+ if err != nil {
+ fmt.Printf("Failed to remove directory %s: %v", path, err)
}
}
- }()
+ }
+
+ return nil
+}
- files, err := d.Readdir(-1)
+// isEmptyDir checks if a directory is empty
+func isEmptyDir(dirPath string) (bool, error) {
+ entries, err := os.ReadDir(dirPath)
if err != nil {
- return err
+ return false, err
}
+ return len(entries) == 0, nil
+}
- if Verbose {
- log.Printf("cleaning directory %s", outdir)
- }
+// deleteMarkdownFiles deletes all .md files except "_index.md"
+func deleteMarkdownFiles(outdir string) error {
+ // Walk through the directory and its subdirectories
+ err := filepath.WalkDir(outdir, func(path string, d os.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
- for _, file := range files {
- if file.Mode().IsRegular() {
- name := file.Name()
- if filepath.Ext(name) == ".md" {
- if filepath.Base(name) == "_index.md" {
- continue
- }
+ // Process only files
+ if d.IsDir() {
+ return nil
+ }
- if err := os.Remove(name); err != nil {
- if Verbose {
- log.Printf("failed to delete file %s: %v", name, err)
- }
+ name := d.Name()
+ if filepath.Ext(name) == ".md" {
+ // Skip _index.md files
+ if filepath.Base(name) == "_index.md" {
+ return nil
+ }
+
+ if err := os.Remove(path); err != nil {
+ if Verbose {
+ log.Printf("failed to delete file %s: %v", path, err)
}
}
}
+
+ return nil
+ })
+
+ if err != nil {
+ return err
+ }
+
+ if Verbose {
+ log.Printf("cleaned directory %s", outdir)
}
return nil
diff --git a/static/images/kyverno-architecture.png b/static/images/kyverno-architecture.png
index 10c7d9c70..98cd3346a 100644
Binary files a/static/images/kyverno-architecture.png and b/static/images/kyverno-architecture.png differ
diff --git a/static/images/kyverno_website_graphics.pptx b/static/images/kyverno_website_graphics.pptx
index d7ff0d65e..023b6a28c 100644
Binary files a/static/images/kyverno_website_graphics.pptx and b/static/images/kyverno_website_graphics.pptx differ