diff --git a/docs/explanations/architecture.md b/docs/explanations/architecture.md index 4fd9a19599c..a5282364c75 100644 --- a/docs/explanations/architecture.md +++ b/docs/explanations/architecture.md @@ -20,18 +20,18 @@ This language must generate a WebAssembly binary for Kubewarden to use. ## What _is_ a policy? A policy is an [Open Container Initiative](https://opencontainers.org/) (OCI) -artifact containing a WebAssembly module, +artifact. It contains a WebAssembly module, the policy code, and the metadata required by PolicyServer -performing admission request validations and mutations. +to perform admission request validations and mutations. :::note -In the same manner as +Like [Kubernetes](https://kubernetes.io/docs/contribute/style/style-guide/), Kubewarden uses the terms 'PolicyServer' when discussing the Kubewarden policy server and -`policy-server` when discussing Pod or Deployment of a Kubewarden PolicyServer. +`policy-server` when discussing a Pod or Deployment of a Kubewarden PolicyServer. ::: @@ -48,47 +48,48 @@ The project utilizes a combination of: - Webhooks (Validation and Mutating) - the Control Plane's event notification system -### Effectively uses Kubernetes architecture +### Makes effective use of the Kubernetes architecture -Kubewarden operates seamlessly within the Kubernetes ecosystem. -At its core, the Kubewarden controller is a Kubernetes controller, -monitoring Kubewarden Custom Resource Definitions (CRDs) -and configuring Kubernetes resources to execute them. -This integration ensures that Kubewarden uses the built-in Kubernetes mechanisms, -such as controllers and CRDs, to watch, manage, and apply security policies efficiently. +Kubewarden operates seamlessly within the Kubernetes ecosystem. At its core, +the Kubewarden controller is a Kubernetes controller, monitoring Kubewarden +Custom Resource Definitions (CRDs) and configuring Kubernetes resources to +execute them. This integration ensures that Kubewarden uses the built-in +Kubernetes mechanisms, such as controllers and CRDs, to watch, manage, and +apply security policies efficiently. ### Extensible policy definition -Kubewarden employs CRDs to define and manage Kubewarden resources, -which specify the rules for admission request validations. -This design enables users to extend Kubernetes' capabilities with custom admission controls, -ensuring that security and compliance policy enforcement is consistent across the cluster. +Kubewarden employs CRDs to define and manage Kubewarden resources, which +specify the rules for admission request validations. This design enables users +to extend Kubernetes' capabilities with custom admission controls, so +that security and compliance policy enforcement is consistent across the +cluster. ### Direct admission control -When setup by the Kubewarden controller, -the policy-server Service receives admission requests directly from the Kubernetes control plane, -using `ValidationWebhooks` and `MutatingWebhooks`. -This direct interaction streamlines the admission control process, -reducing latency and increasing efficiency in policy enforcement. - -WebAssembly offers a sand-boxed execution environment, -ensuring policies run in isolation, -thus enhancing the security and stability of the policy enforcement mechanism. -This isolation prevents policies from interfering with each other or with the host system, -mitigating the risk of malicious code execution. -WebAssembly is portable and efficient, -enabling policies to run across different environments without modification. -This cross-platform compatibility ensures that Kubewarden policies are versatile, -and can be distributed and executed in diverse Kubernetes clusters +When setup by the Kubewarden controller, the policy-server Service receives +admission requests directly from the Kubernetes control plane, using +`ValidationWebhooks` and `MutatingWebhooks`. This direct interaction +streamlines the admission control process, reducing latency and increasing +efficiency in policy enforcement. + +WebAssembly offers a sand-boxed execution environment, ensuring policies run in +isolation, thus enhancing the security and stability of the policy enforcement +mechanism. This isolation prevents policies from interfering with each other or +with the host system, mitigating the risk of malicious code execution. +WebAssembly is portable and efficient, enabling policies to run across +different environments without modification. + +This cross-platform compatibility ensures that Kubewarden policies are +versatile, so you can distribute and run them on diverse Kubernetes clusters ### OCI based policy artifacts Policies in Kubewarden are OCI (Open Container Initiative) artifacts. -This standardization makes the distribution and versioning of policies easier, +This standardization makes the distribution and versioning of policies easier. Policies contain both the WebAssembly modules for enforcement logic, and metadata necessary for the PolicyServer's operation. -Leveraging OCI artifacts promotes interoperability and ease of management +Using OCI artifacts promotes interoperability and ease of management within cloud ecosystems. ### Fine-grained policy application @@ -110,7 +111,8 @@ The Kubewarden consists of these components: Kubewarden integrates with Kubernetes using [Dynamic Admission Control](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/). In particular, Kubewarden operates as a Kubernetes Admission Webhook. - The `policy-server` is the Webhook endpoint called by the Kubernetes API server to validate requests. + The `policy-server` is the Webhook endpoint called by the Kubernetes + API server to validate requests. - The [Kubewarden controller](https://github.com/kubewarden/kubewarden-controller) is a Kubernetes controller that reconciles Kubewarden's Custom Resources. @@ -137,7 +139,7 @@ The Kubewarden consists of these components: [Audit scanner](/explanations/audit-scanner/audit-scanner.md) constantly checks the resources declared in the cluster, - flagging the ones that no longer adhere with the deployed Kubewarden policies. + flagging the ones that no longer adhere to the deployed Kubewarden policies. ```mermaid %%{ @@ -227,7 +229,7 @@ a reconciliation loop activates in `kubewarden-controller`, for the `policy-server` owning the policy. This reconciliation loop creates a `ConfigMap` with all the policies bound to the `policy-server`. Then the Deployment rollout of the `policy-server` starts. -It results in starting the new `policy-server` instance with the updated configuration. +This results in starting the new `policy-server` instance with the updated configuration. At start time, the `policy-server` reads its configuration from the ConfigMap and downloads all the Kubewarden policies specified. @@ -243,8 +245,8 @@ There is further documentation in the [specification reference](../reference/spec/01-intro-spec.md) section of the documentation. -If one or more policies received wrong configuration parameters, -from the policy specification provided by the user, +If any policies received wrong configuration parameters, +from the users policy specification, then any admission requests evaluated by that policy return an error. When Kubewarden has configured all policies, @@ -309,7 +311,7 @@ A cluster can have many PolicyServers and Kubewarden policies defined. There are benefits of having many PolicyServers: - You can isolate noisy namespaces or tenants, - those generating many policy evaluations, + or those generating many policy evaluations, from the rest of the cluster so as not to adversely affect other cluster operations. - You can run mission-critical policies in a dedicated PolicyServer pool, diff --git a/docs/explanations/certificates.md b/docs/explanations/certificates.md index f4e759fa60b..4fe279d31c4 100644 --- a/docs/explanations/certificates.md +++ b/docs/explanations/certificates.md @@ -13,19 +13,19 @@ doc-topic: [explanations, certificates] -Since Kubewarden v1.17.0, the cert-manager dependency was removed. The +Kubewarden v1.17.0 removed the cert-manager dependency. The controller is able to manage all the certificates used by all the components. -This means that the controller has a new reconciliation loop that ensures the +Now, the controller has a new reconciliation loop that ensures the certificates are always up-to-date and the webhook configuration is correct. -The first certificate generation is done by the Helm chart installation. It -will generate the root CA with ten years until expiration. The Helm chart -installation also generates the controller webhook webserver certificate, -signed by the root CA. This is used by the API server to communicate with the +The Helm chart installation does the first certificate generation. It +generates the root CA with ten years until expiration. The Helm chart +installation also generates the controller webhook web server certificate, +signed by the root CA. The API server use this to communicate with the Kubewarden controller to validate the CRDs. It has a one year expiration. Once the controller starts, its reconciler renews the certificates -automatically when they are about to expire. It also updates all the +automatically when they're about to expire. It also updates the certificates and webhook configurations used by the entire Kubewarden stack. :::note @@ -33,22 +33,24 @@ All the certificates generated by the Helm chart and later by the controller use ECDSA P256 keys. ::: -The reconciliation loop renews certificates 60 days before expiration. The -certificates are rotated without downtime. -The reconciliation loop takes care of renewing the root CA too. 60 days before -its expiration, a new root CA is generated and the CA bundled used by all the -webhooks is updated with one that includes both the new root CA and -the old one. -The change of the root CA leads the reconciler to recreate the certificates -issued to the webhooks. -The propagation of the new certificates requires some time. However during this -time the updated CA bundle allows the API server to continue to communicate -with all the webhooks without any downtime. - -Once the new certificate is ready and the old one is invalid, the controller -will update the CA bundle used by the webhooks to include only the latest root CA. - -When a policy server certificate or the controller webserver certificate is -renewed, the controller updates the secret with the new certificate signed by +The reconciliation loop renews certificates 60 days before expiration. +Certificates rotate without downtime. The reconciliation loop takes care of +renewing the root CA too. + +The controller generates a new root CA 60 days before expiration. The +controller updates the CA bundle used by all the webhooks to include both the +new root CA and the old one. + +The change of the root CA leads the reconciler to re-create the certificates +issued to the webhooks. The propagation of the new certificates requires a +period of time. However, during this time the updated CA bundle lets the API +server continue to communicate with all the webhooks without any downtime. + +When a new certificate is ready, and the old one is invalid, the controller +updates the CA bundle, used by webhooks, to include only the latest root +CA. + +When a policy server, or controller web server certificate +renews, the controller updates the secret with the new certificate signed by the root CA. Due to this reload feature, the controller, and the policy server, use the new certificate with no need to restart processes, hence no downtime. diff --git a/docs/explanations/context-aware-policies.md b/docs/explanations/context-aware-policies.md index e905732e744..9767685bf55 100644 --- a/docs/explanations/context-aware-policies.md +++ b/docs/explanations/context-aware-policies.md @@ -15,23 +15,29 @@ doc-topic: [explanations, context-aware-policies] Developers can create policies that fetch information from a Kubernetes cluster at run time. These are context aware policies. -Context aware policies can determine whether an `AdmissionRequest` is acceptable using information from resources deployed in the cluster. +Context aware policies can determine whether an `AdmissionRequest` is +acceptable using information from resources deployed in the cluster. :::note Context aware policies are only available in Kubewarden versions ≥ v1.6.0. ::: -Resources a policy can access in the cluster is controlled by the policy server's [Service Account](https://kubernetes.io/docs/concepts/security/service-accounts/). +Control of which resources a policy can access in the cluster is by the policy server's +[Service Account](https://kubernetes.io/docs/concepts/security/service-accounts/). A cluster administrator controls what a policy can access via Kubernetes RBAC rules. Context aware policies have only **read** access to the requested resources. For security reasons, only `ClusterAdmissionPolicy` policies can fetch information from the Kubernetes cluster. -This is because `AdmissionPolicy` resources can be deployed by unprivileged users. -If a context aware policy is deployed as an `AdmissionPolicy` all attempts to access Kubernetes resources are blocked and reported to the cluster administrator. +This is because unprivileged users can deploy `AdmissionPolicy` resources. + +If an unprivileged user deploys a context aware policy as an `AdmissionPolicy`, the system: + +- Blocks all attempts to access Kubernetes resources. +- Reports them to the cluster administrator. By default, all the cluster resources are blocked. A Kubewarden administrator defines which Kubernetes resources each context aware policy is allowed to read. -This is done in the `ClusterAdmissionPolicy` definition using the field `contextAwareResources` . +The `ClusterAdmissionPolicy` definition uses the field `contextAwareResources` to do this. The following example deploys a policy that requires access to the `Deployment` and `Pod` resources: @@ -63,7 +69,7 @@ spec: Once deployed, this policy can read the data of the `deployment` and `pod` resources. Policy authors provide lists of Kubernetes resources for their context aware policy. -This is done by annotating the policy. +Policy authors do this by annotating the policy. Kubewarden administrators view policy metadata using the `kwctl inspect` command. They can get a list of resources the policy needs access to. An administrator uses this list to populate the `ClusterAdmissionPolicy` definition. @@ -74,19 +80,19 @@ To prevent system abuse, Kubewarden administrators must review the resources the For example, a policy evaluating ingress objects would have good reasons to read the `Ingress` resources defined in the cluster. The same policy can't justify having access to `Secret` resources. -Policies should have the least access needed to function correctly. +Policies should have the minimum access needed to function correctly. ::: :::note -Kubernetes resources are identified by `apiVersion` and `kind`. +Kubernetes resource identification uses `apiVersion` and `kind`. Usually, `apiVersion` is a string in the format `/`. -Resources from the `core` API group (Pod, Service, and others) should not define the group name, ``. +Resources from the `core` API group (Pod, Service, and others) shouldn't define the group name, ``. They should only define the `` (for example, `v1`). -For a core resource, the first will not work, the second will. +For a core resource, the first won't, the second will. ```console - apiVersion: "core/v1" @@ -104,5 +110,6 @@ All other Kubernetes resources need the full definition: `/`. ## Further readings -More detailed information about context aware policies can be found in [this section](../reference/spec/05-context-aware-policies.md) -of our reference documentation. +You can find more detailed information about context aware policies in +[this section](../reference/spec/05-context-aware-policies.md) +of the reference documentation. diff --git a/docs/explanations/distributing-policies.md b/docs/explanations/distributing-policies.md index 11e8e7303f3..a6b6ee83885 100644 --- a/docs/explanations/distributing-policies.md +++ b/docs/explanations/distributing-policies.md @@ -13,9 +13,9 @@ doc-topic: [distributing-policies] -Kubewarden policies are WebAssembly (Wasm) binaries that are evaluated by the Kubewarden Policy Server. +Kubewarden policies are WebAssembly (Wasm) binaries evaluated by the Kubewarden Policy Server. -The Kubewarden policy server can load policies from these sources: +The Kubewarden policy server loads policies from these sources: - Local filesystem - HTTP(s) server @@ -26,14 +26,14 @@ The Kubewarden policy server can load policies from these sources: - [Amazon ECR](https://aws.amazon.com/ecr/) - [Google container registry](https://cloud.google.com/artifact-registry/) -We think distributing Kubewarden policies via a regular OCI-compliant registry is the best choice. +Kubewarden recommends distributing Kubewarden policies via a regular OCI-compliant registry. Container registries are a mandatory requirement for any Kubernetes cluster. Having a single place to store, and secure, all the artifacts required by a cluster is beneficial. ## Pushing policies to an OCI-compliant registry The [OCI image format](https://github.com/opencontainers/image-spec) -specification allows you to store any binary blob inside a regular OCI-compliant container registry. +specification permits storing any binary blob inside a regular OCI-compliant container registry. The target OCI-compliant registry **must support artifacts** to successfully push a Kubewarden Policy to it. @@ -43,7 +43,7 @@ You can use the [`kwctl`](https://github.com/kubewarden/kwctl) CLI to push a Kub You also annotate a policy with `kwctl`. The process of annotating a Kubewarden policy is done by adding Wasm custom sections to the policy binary. -This means that the policy metadata is packaged with the policy itself. +This means that the policy packages it's own metadata. The `kwctl annotate` command requires two inputs: @@ -52,7 +52,7 @@ The `kwctl annotate` command requires two inputs: - the annotations file, a file containing a YAML description of the policy metadata. This file is usually located root project folder of your policy. -For example, we save this file as `metadata.yml` in the current +For example, you can save this file as `metadata.yml` in the current directory: ```yaml @@ -78,10 +78,10 @@ annotations: This policy accepts the following settings: - - `invert_behavior`: bool that inverts the policy behavior. If enabled, only palindrome names will be accepted. + - `invert_behavior`: bool that inverts the policy behavior. If enabled, only palindrome names are accepted. ``` -Now, let's annotate the policy: +Now, you can annotate the policy: ```shell $ kwctl annotate policy.wasm \ @@ -89,8 +89,8 @@ $ kwctl annotate policy.wasm \ --output-path annotated-policy.wasm ``` -The annotation process performs some optimizations on the policy, so often the annotated policy is smaller than the original. -This depends considerably on the toolchain that was used to produce the original Wasm object. +The annotation process performs certain optimizations on the policy, so often the annotated policy is smaller than the original. +This depends considerably on the toolchain used to produce the original Wasm object. :::info @@ -135,12 +135,12 @@ This is markdown text and as such allows you to define a free form usage text. This policy allows you to reject requests if: -• The name of the resource is a palindrome name. -• The namespace name where this resource is created has a palindrome name. +- The name of the resource is a palindrome name. +- The namespace name where this resource is created has a palindrome name. This policy accepts the following settings: -• invert_behavior: bool that inverts the policy behavior. If enabled, only palindrome names will be accepted. +- invert_behavior: bool that inverts the policy behavior. If enabled, only palindrome names will be accepted. Cannot determine if the policy has been signed. There was an error while attempting to fetch its signatures from the remote registry: invalid uri ``` @@ -158,10 +158,10 @@ $ kwctl push annotated-policy.wasm \ /kubewarden-policies/palindromify-policy:v0.0.1 ``` -It is discouraged to push unannotated policies. +It's discouraged to push unannotated policies. The policy server uses the metadata provided by annotations to correctly execute a policy. -By default, `kwctl push` will refuse to push such a policy to an OCI registry. +By default, `kwctl push` refuses to push such a policy to an OCI registry. If you need an unannotated policy, use the `--force` flag of `kwctl push`. -The policy can then be referenced from the Kubewarden Policy Server or `kwctl` as +You can reference a policy from the Kubewarden Policy Server or `kwctl` as `registry:///kubewarden-policies/palindromify-policy:v0.0.1`. diff --git a/docs/explanations/mutating-policies.md b/docs/explanations/mutating-policies.md index 4b2056f4308..ab430b6e8b0 100644 --- a/docs/explanations/mutating-policies.md +++ b/docs/explanations/mutating-policies.md @@ -13,34 +13,31 @@ doc-topic: [mutating-policies] -Mutating policies receive an object request and rebuild this incoming object -(mutate it) into a new request, according to the defined values in the settings -of the policy. The request will proceed through the Kubernetes API, potentially being +Mutating policies receive an object request and rebuild it +(mutate it) into a new request, according to the defined values in the policy settings. +The request proceeds through the Kubernetes API, potentially being evaluated by other policies. -If you want to allow the behavior of mutating requests, +To permit mutating request behavior in a policy set the `ClusterAdmissionPolicy.mutating` field to `true`. -However, if you set the `ClusterAdmissionPolicy.mutating` field to `false`, -the mutated requests will be rejected. - ## Why mutating policies can be dangerous ### Unreviewed mutating policies can introduce vulnerabilities :::danger To prevent system abuse, Kubewarden administrators should review mutating -policies: mutating policies could for example modify a workload, such that it -allows for privileged container creation. +policies. Mutating policies could, for example, modify a workload, such that it +permits privileged container creation. ::: #### Solution If in doubt, split policies into mutating and validating policies, instead of writing or deploying policies that both validate and mutate. This is particularly -important when using a DSL (such as Rego) to build complex policies. +important when using a DSL, such as Rego, to build complex policies. -### Misconfigured mutating policies together with 3rd party Kubernetes Controllers can get stuck in an infinite loop +### Misconfigured mutating policies together with third party Kubernetes Controllers can get stuck in an infinite loop :::danger Mutating policies return requests that proceed through the Kubernetes API. If @@ -53,15 +50,15 @@ infinite feedback loop of mutations. Perform the mutation against: -1. The lower type of resource (e.g: Pod). -2. The highest type of resource (e.g: Deployment). Note: this could still lead - to loops if a controller is managing those resources. For example - controllers of GitOps solutions (like fleet, flux, argo, ...) or other 3rd +1. The lower type of resource (for example, Pod). +2. The highest type of resource (for example, Deployment). Note: this could still lead + to loops if a controller is managing those resources. For example, + controllers of GitOps solutions (like fleet, flux, argo, ...) or other third party controllers that translate their own CRDs into Deployment objects. ## Examples -Let's see a mutating policy at work. Create the following +You can see a mutating policy at work. Create the following `ClusterAdmissionPolicy` with the `mutating` field set to `true`: ```bash @@ -99,10 +96,12 @@ EOF clusteradmissionpolicy.policies.kubewarden.io/psp-user-group created ``` -The [`psp-user-group`](https://github.com/kubewarden/user-group-psp-policy) policy is used to control users and groups in containers and can mutate the requests. -In the example above, the `runAsUser` field is set and it will be added to the container `securityContext` section. +You use the +[`psp-user-group`](https://github.com/kubewarden/user-group-psp-policy) +policy to control users and groups in containers and mutate the requests. +In the previous example, you set the `run_as_user` field and it's added to the container `securityContext` section. -As the `mutating` field is set to `true`, the following request will be applied successfully: +As the `mutating` field is `true`, the following request succeeds: ```bash # Command @@ -121,7 +120,7 @@ EOF pod/pause-user-group created ``` -Once the request is applied, you can see the results of the container's `securityContext`: +You can see the results of the container's `securityContext` after the request application: ```bash # Command @@ -168,7 +167,7 @@ EOF clusteradmissionpolicy.policies.kubewarden.io/psp-user-group configured ``` -As the `mutating` field is set to `false`, the following request will fail: +As the `mutating` field is `false`, the following request fails: ```bash # Command diff --git a/docs/explanations/policy-groups.md b/docs/explanations/policy-groups.md index 6c4b37e098b..ef1167a7097 100644 --- a/docs/explanations/policy-groups.md +++ b/docs/explanations/policy-groups.md @@ -13,39 +13,40 @@ doc-topic: [explanations, policy-group] -The policy group feature allows users to create complex policies by combining +The policy group feature permits users to create complex policies by combining simpler ones. It introduces two new Custom Resource Definitions (CRDs): -- `AdmissionPolicyGroup`: For admission policies that apply to specific +- `AdmissionPolicyGroup`: for admission policies that apply to specific namespaces. -- `ClusterAdmissionPolicyGroup`: For admission policies that apply across the +- `ClusterAdmissionPolicyGroup`: for admission policies that apply across the entire cluster. These policy groups enable users to use existing policies, reducing the -need for custom policy creation and enhancing reusability. By avoiding +need for custom policy creation and enhancing reuse. By avoiding duplication of policy logic, users can simplify management and create custom policies with a DSL-like configuration. Policy groups enable the combined evaluation of -multiple policies using logical operators. This allows the definition of -complex logic. However, it is important to note that while ordinary policies +multiple policies using logical operators. This permits the definition of +complex logic. However, while ordinary policies can include mutation logic to modify resources during admission, policy groups -are limited to validation only. +only do validation. Configuration for policy groups is similar to that of ordinary policies. The difference is the addition of the `expression`, -`message`, and `policies` fields, as well as the declaration of context-aware +`message`, and `policies` fields, and the declaration of context-aware rules in a different location. -This is an example of a `ClusterAdmissionPolicyGroup` that we will use in +This is an example of a `ClusterAdmissionPolicyGroup` that you can use in the next sections to explain the different fields:
-A `ClusterAdmissionPolicyGroup` that rejects Pods that use images with the `latest` tag, -unless the images are signed by two trusted parties: Alice and Bob. +A `ClusterAdmissionPolicyGroup` that rejects Pods that use images with the +`latest` tag, unless the images are signed by two trusted parties: Alice and +Bob. ```yaml @@ -104,15 +105,16 @@ This section covers the main configuration fields of a policy group. ### The `policies` attribute -The policies field is a map of ordinary policies. Kubewarden -policies are called by the policy group, to determine whether the resource under -evaluation is accepted or rejected. The definitions of these policies are a -simplified version of ordinary Kubewarden policies, containing only the -`module`, `settings` and `contextAwareResources` attributes. These -elements are necessary for the policies to function within a policy group. +The policies field is a map of ordinary policies. Kubewarden calls policies by +the policy group, to determine whether to accept or reject the resource under +evaluation. The definitions of these policies are a simplified version of +ordinary Kubewarden policies, containing only the `module`, `settings` and +`contextAwareResources` attributes. These elements are necessary for the +policies to function within a policy group. -Each policy of the group policy is identified by a unique name. For example, -the following snippet defines two policies: `signed_by_alice`, `signed_by_bob` and `reject_latest_tag`. +A unique name identifies each policy of the group policy. For example, the +following snippet defines three policies: `signed_by_alice`, `signed_by_bob` +and `reject_latest_tag`. ```yaml policies: @@ -128,21 +130,19 @@ policies: ``` :::tip -The same policy can be included multiple times in the same policy group, with -different settings. +A policy group can include the same policy multiple times with different settings. ::: ### The `expression` attribute -The `expression` attribute contains a statement made of the policy -identifiers joined together by logical operators. +The `expression` attribute contains a statement made of the policy identifiers +joined together by logical operators. The evaluation of the `expression` statement must evaluate to a boolean value. Each policy is represented as a function named after the identifier specified -inside of the `.spec.policies` map. The results produced -by the evaluation of the policies are then evaluated using the logical operators -provided by the user. +in the `.spec.policies` map. The results produced by the evaluation of the +policies are then evaluated using the logical operators provided by the user. These are the supported operators: @@ -150,7 +150,7 @@ These are the supported operators: - `||`: used to perform `OR` operations - `!`: used to perform `NOT` operations -Round brackets `( )` can be used to define evaluation priorities. +You can use round brackets `( )` to define evaluation priorities. For example, given the following expression: @@ -158,17 +158,17 @@ For example, given the following expression: reject_latest() || (signed_by_alice() && signed_by_bob()) ``` -The policy will reject workloads that have images using the `latest` tag, unless -these images are signed both by Alice and Bob. +The policy rejects workloads that have images using the `latest` tag, unless +these images both by Alice and Bob have signed the images. ### The `message` attribute and the response format The `message` field specifies the message returned when the evaluation of the -`expression` results in a rejection. The message is included in the response, +`expression` results in a rejection. The response includes the message, together with the results of the individual policies evaluation. :::info -The policies that belong to the group are evaluated only +Evaluation of policies that belong to the group takes place only if necessary. For example, given the following expression: @@ -177,21 +177,22 @@ For example, given the following expression: reject_latest() || (signed_by_alice() && signed_by_bob()) ``` -The `signed_by_bob` and `signed_by_alice` policies are not evaluated when -the `reject_latest` policy returns `true`. +The `signed_by_bob` and `signed_by_alice` policies aren't evaluated when the +`reject_latest` policy returns `true`. -In the same way, the `signed_by_bob` policy is not evaluated if the `signed_by_alice` -and the `reject_latest` policies return `false`. +In the same way, the `signed_by_bob` policy isn't evaluated if the +`signed_by_alice` and the `reject_latest` policies return `false`. This avoids unnecessary evaluations of policies in the group and grants fast responses to the admission requests. ::: -When a group policy performs a rejection, all the evaluation details of the -group policies are sent as part of the AdmissionResponse `.status.details.causes`. +The system sends all evaluation details of the group policies as part of the +AdmissionResponse `.status.details.causes` when a group policy performs a +rejection. -The full details of a rejected admission request can be obtained by increasing the verbosity -level of `kubectl`: +You can obtain the full details of a rejected admission request by increasing +the verbosity level of `kubectl`: ```shell kubectl -v4 apply -f signed-pod.yml @@ -218,19 +219,21 @@ I0919 18:29:40.251332 4330 helpers.go:246] server response object: [{ Error from server: error when creating "signed-pod.yml": admission webhook "clusterwide-demo.kubewarden.admission" denied the request: the image is using the latest tag or is not signed by Alice and Bob ``` -The full admission response is available in the logs of the Policy Server -when running in debug mode. -Moreover, the evaluation details are always part of the OpenTelemetry traces emitted by Policy Server. +The full admission response is available in the logs of the Policy Server when +running in debug mode. Moreover, the evaluation details are always part of the +OpenTelemetry traces emitted by Policy Server. -## Context-Aware Policies +## Context-aware policies -Another distinction between policy groups and ordinary policies is the location -where context-aware resource rules are defined. Each policy in a group +Another distinction between policy groups and ordinary policies is the +definition location of context-aware resource rules. Each policy in a group accepts an optional `contextAwareResources` field to specify the resources that -the policy is allowed to access during evaluation. -Similarly to ordinary policies, context-aware capabilities can only be used by defining a `ClusterAdmissionPolicyGroup`. -This is for security reasons, as `AdmissionPolicyGroup` resources can be deployed by unprivileged users. -For more details, refer to the [context-aware policies](./context-aware-policies.md) documentation. +the policy can access during evaluation. Similarly to ordinary policies, you +can only use context-aware capabilities by defining a +`ClusterAdmissionPolicyGroup`. This is for security reasons, as only +unprivileged users can deploy `AdmissionPolicyGroup` resources. For more +details, refer to the [context-aware policies](./context-aware-policies.md) +documentation.
@@ -275,26 +278,26 @@ spec:
-In the previous example, the `unique_service_selector` policy is allowed to -access the `Service` resource. On the other hand, the `owned_by_foo_team` +In the previous example, the `unique_service_selector` policy can +access the `Service` resource. However, the `owned_by_foo_team` has no access to Kubernetes resources. -## Settings Validation +## Settings validation -When the policy server starts, it will validate the settings of both policy +When the policy server starts, it validates the settings of both policy groups and ordinary policies. However, policy groups undergo an additional -validation step to ensure that the expression is valid and evaluates to a +validation step to check that the expression is valid and evaluates to a boolean value. ## Audit Scanner Similar to the AdmissionPolicy and ClusterAdmissionPolicy CRDs, the -`backgroundAudit` field indicates if the policy group should be included +`backgroundAudit` field indicates whether to include the policy group during [audit checks](../explanations/audit-scanner/audit-scanner.md). ## Policy Server -The `policies.yml` settings file is extended to include policy groups -alongside ordinary policies. As with ordinary policies, modules are -downloaded once. The same policy module is used in both a policy -group and an ordinary policy. +You can extend the `policies.yml` settings file to include policy groups +alongside ordinary policies. As with ordinary policies, module download takes +place once. You use the same policy module in both a policy group and an +ordinary policy.