Merge pull request #541 from jhkrug/explanation-lang-active

Explanation section - updated language and active voice. CNCF suggestion.

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,

docs/explanations/audit-scanner/audit-scanner.md

@@ -21,35 +21,42 @@ The Audit Scanner feature is available starting from Kubewarden 1.7.0 release
 :::
 
 The `audit-scanner` component constantly checks resources in the cluster.
-It flags the ones that don't adhere to the Kubewarden policies deployed in the cluster.
+It flags the ones not adhering to Kubewarden policies deployed in the cluster.
 
-Policies evolve over time.
-New ones are deployed, existing ones are updated.
-Versions and configuration settings change.
-This can lead to situations where resources already inside the cluster are no longer compliant.
-The audit scanning feature provides Kubernetes administrators with a tool that constantly verifies the compliance state of their clusters.
+Policies evolve over time. There are new policy deployments and policy updates.
+Versions and configuration settings change. This can lead to situations where
+resources already inside the cluster are no longer compliant. The audit
+scanning feature provides Kubernetes administrators with a tool that constantly
+verifies the compliance state of their clusters.
 
-To explain the use of the audit scanner in Kubewarden, consider the following scenario.
+To explain the use of the audit scanner in Kubewarden, consider the following
+scenario:
 
-Assume Bob is deploying a WordPress Pod in the cluster.
-Bob is new to Kubernetes, makes a mistake and deploys the Pod running as a privileged container.
-At this point, there's no policy preventing that so the Pod is successfully created in the cluster.
+Assume Bob is deploying a WordPress Pod in the cluster. Bob is new to
+Kubernetes, makes a mistake and deploys the Pod running as a privileged
+container. At the moment, there's no policy preventing that so the Pod is
+successfully created in the cluster.
 
-Some days later, Alice, the Kubernetes administrator, enforces a Kubewarden policy that prohibits the creation of privileged containers.
-The Pod deployed by Bob keeps running in the cluster as it already exists.
+A few days later, Alice, the Kubernetes administrator, enforces a Kubewarden
+policy that prohibits the creation of privileged containers. The Pod deployed
+by Bob keeps running in the cluster as it already exists.
 
-A report generated by the audit scanner lets Alice identify all the workloads that are violating creation policies.
-This includes the WordPress Pod created by Bob.
+A report generated by the audit scanner lets Alice identify all the workloads
+that are violating creation policies. This includes the WordPress Pod created
+by Bob.
 
 The audit scanner operates by:
 
 - identifying all the resources to audit
-- for each resource, it builds a synthetic admission request with the resource's data
-- it sends each admission request to a policy server endpoint which is only for audit requests
+- for each resource, it builds a synthetic admission request with the
+  resource's data
+- it sends each admission request to a policy server endpoint which is only for
+  audit requests
 
-For the policy evaluating the request, there are no differences between real or audit requests.
-This auditing policy server endpoint has instrumentation to collect data about the evaluation.
-So, users can use their monitoring tools to analyze audit scanner data.
+For the policy evaluating the request, there are no differences between real or
+audit requests. This auditing policy server endpoint has instrumentation to
+collect data about the evaluation. So, users can use their monitoring tools to
+analyze audit scanner data.
 
 ## Enable audit scanner
 
@@ -60,25 +67,38 @@ Detailed installation instructions are in the
 
 ## Policies
 
-By default, the audit scanner evaluates every policy.
-Operators that want to skip a policy evaluation in the audit scanner must set the `spec.backgroundAudit` field to `false` in the policy definition.
+By default, the audit scanner evaluates every policy. Operators that want to
+skip a policy evaluation in the audit scanner must set the
+`spec.backgroundAudit` field to `false` in the policy definition.
 
 Also, policies in Kubewarden now support two optional annotations:
 
-- The `io.kubewarden.policy.severity` annotation lets you specify the severity level of the policy violation, such as `critical`, `high`, `medium`, `low` or `info`.
-- The `io.kubewarden.policy.category` annotation lets you categorize the policy based on a specific domain or purpose, such as `PSP`, `compliance`, or `performance`.
+- The `io.kubewarden.policy.severity` annotation lets you specify the severity
+  level of the policy violation, such as `critical`, `high`, `medium`, `low` or
+  `info`.
+- The `io.kubewarden.policy.category` annotation lets you categorize the policy
+  based on a specific domain or purpose, such as `PSP`, `compliance`, or
+  `performance`.
 
-See the policy authors [documentation](../../tutorials/writing-policies/index.md) for more information.
+See the policy authors
+[documentation](../../tutorials/writing-policies/index.md) for more
+information.
 
 ## Permissions and ServiceAccounts
 
-The audit scanner in Kubewarden requires specific Role Based Access Control (RBAC) configurations to be able to scan Kubernetes resources and save the results.
-A correct default Service Account with those permissions is created during the installation.
-The user can create their own ServiceAccount to configure access to resources.
-
-The default audit scanner `ServiceAccount` is bound to the `view` `ClusterRole` provided by Kubernetes.
-This `ClusterRole` allows read-only access to a wide range of Kubernetes resources within a namespace.
-You can find more details about this role in the [Kubernetes documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles).
-
-Also, the audit scanner is bound to a `ClusterRole` that grants read access to Kubewarden resource types and read-write access to the `PolicyReport` [CRDs](policy-reports.md).
-These permissions let the scanner fetch resources for conducting audit evaluations and creating policy reports based on the evaluation results.
+The audit scanner in Kubewarden requires specific Role Based Access Control
+(RBAC) configurations to be able to scan Kubernetes resources and save the
+results. Installation creates a correct default Service Account with those
+permissions. The user can create their own ServiceAccount to configure access
+to resources.
+
+The default audit scanner `ServiceAccount` binds to the `view` `ClusterRole`
+provided by Kubernetes. This `ClusterRole` permits read-only access to a wide
+range of Kubernetes resources within a namespace. You can find more details
+about this role in the [Kubernetes
+documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles).
+
+The audit scanner binds to a `ClusterRole` that grants read access to
+Kubewarden resource types and read-write access to the `PolicyReport` CRDs.
+These permissions let the scanner fetch resources for conducting audit
+evaluations and creating policy reports based on the evaluation results.

docs/explanations/audit-scanner/limitations.md

@@ -16,10 +16,10 @@ doc-topic: [explanations, audit-scanner, limitations]
 
 Policies can inspect `CREATE`, `UPDATE`, and `DELETE` events.
 
-The audit scanner can not simulate `UPDATE` events,
-as it doesn't know which part of the resource need to be changed.
+The audit scanner can't simulate `UPDATE` events, as it doesn't know which part
+of the resource requires changing.
 
-So, a policy concerned only with `UPDATE` events is ignored by the audit scanner.
+So, the audit scanner ignores a policy concerned only with `UPDATE` events.
 
 :::note
 
@@ -30,23 +30,25 @@ The audit-scanner v1.7.0 release supports only `CREATE` events.
 
 ## Policies relying on user and user group information
 
-Each Kubernetes admission request object has information about which user (or ServiceAccount) initiated the event,
-and to which group they belong.
+Each Kubernetes admission request object has information about which user (or
+ServiceAccount) initiated the event, and to which group they belong.
 
-All the events simulated by the audit scanner are originated by the same hard coded user and group.
-Because of that, policies that rely on these values to make their decisions will not produce meaningful results.
+All the events simulated by the audit scanner originate from the same hard
+coded user and group. Because of that, policies that rely on these values to
+make their decisions won't produce meaningful results.
 
-For these cases, the policy should be configured to be skipped from the audit checks.
+For these cases, configure the policy as not auditable.
 
 ## Policies relying on external data
 
-Policies can request and use external data when performing an evaluation.
-These policies can be evaluated by the audit checks,
-but their outcomes can change depending on the external data.
+Policies can request and use external data when performing an evaluation. You
+can evaluate these policies with the audit checks but their outcomes can change
+depending on the external data.
 
 ## Usage of `*` by policies
 
-Both the `AdmissionPolicy` and the `ClusterAdmissionPolicy` custom resources have the following fields:
+Both the `AdmissionPolicy` and the `ClusterAdmissionPolicy` custom resources
+have the following fields:
 
 ```yaml
 spec:
@@ -61,4 +63,4 @@ spec:
 
 The `apiGroups`, `apiVersions` and `resources` attributes can use the wildcard `*`.
 This wildcard symbol causes the policy to match all the values used in the field.
-The audit scanner ignores policies that make use of the `*` symbol.
+The audit scanner ignores policies that use the `*` symbol.