diff --git a/docs/glossary.md b/docs/glossary.md index 957fb4f5b5..5516976406 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -24,24 +24,29 @@ the namespace in which the AdmissionPolicy is defined. ### ClusterAdmissionPolicy -A ClusterAdmissionPolicy defines how policies evaluate requests. +An [AdmissionPolicy](#admissionpolicy) which targets cluster-wide resources. ### ClusterPolicyReport A [PolicyReport](#policyreport) and a ClusterPolicyReport store results of -policy scans. Which one is used depends on the scope of the resource. +policy scans. Which one is used, depends on the scope of the resource. ## K ### kwctl -A CLI tool allowing administrators to test policies before applying them to a -cluster. +A CLI tool to generate and test Kubernetes YAML files for policy deployment. ## M ### MutatingWebhookConfiguration +A +[Kubernetes resource](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#what-are-admission-webhooks) +created by the Kubewarden controller to let Kubernetes know where to send an `AdmissionReview`. +In other words, +this is how a Kubewarden controller informs Kubernetes where to find a resource mutating policy. + ## P ### PolicyReport @@ -57,6 +62,11 @@ A PolicyServer validates incoming requests by executing Kubewarden policies agai ### ValidatingWebhookConfiguration +A +[Kubernetes resource](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#what-are-admission-webhooks) +created by the Kubewarden controller to let Kubernetes know where to send a `AdmissionReview`. +In other words, this is how Kubewarden informs Kubernetes where to find a resource validating policy. + ## W ### waPC diff --git a/docs/quick-start.md b/docs/quick-start.md index b0ab2da833..b35a65922d 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -37,7 +37,7 @@ The Kubewarden stack comprises: :::tip -The Kubernetes Custom Resource Definitions (CRD) defined by Kubewarden are described [here](reference/CRDs.md). +The Kubernetes Custom Resource Definitions (CRDs) defined by Kubewarden are described [here](reference/CRDs.md). ::: @@ -60,7 +60,7 @@ helm install --wait --namespace cert-manager --create-namespace \ :::info Authentication Kubewarden policies can be retrieved from the GitHub container registry at https://ghcr.io. You need authentication to use the repository with the Kubewarden CLI, a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) (PAT). -Their documentation guides you through creating one if you have not already done so. +Their documentation guides you through creating one if you haven't already done so. Then you authenticate with a command like: ```console @@ -112,8 +112,8 @@ Since [`v0.4.0`](https://github.com/kubewarden/kubewarden-controller/releases/ta Now a Helm chart called `kubewarden-defaults`, installs the default policy server. -This means that if you are not using the latest version of the `kubewarden-controller` and are trying to upgrade or delete, -your default policy server will not be upgraded or deleted. +This means that if you aren't using the latest version of the `kubewarden-controller` and are trying to upgrade or delete, +your default policy server won't be upgraded or deleted. So, you might run into issues if you try to install the `kubewarden-defaults` with some conflicting information, for example, the same policy server name. To be able to take advantage of future upgrades in the `kubewarden-defaults` Helm chart remove the existing `PolicyServer` resource created by the `kubewarden-controller` before installing the new chart. @@ -128,12 +128,13 @@ The default configuration values are sufficient for most deployments. All option Kubewarden has three main components which you will interact with: - The [[< policy-server >]] -- The ClusterAdmissionPolicy -- The AdmissionPolicy +- The [[< cluster-admission-policy >]] +- The [[< admission-policy >]] ### `PolicyServer` -A Kubewarden `PolicyServer` is managed by the `kubewarden-controller` and multiple [[< policy-server >]]s can be deployed in the same Kubernetes cluster. +A Kubewarden `PolicyServer` is managed by the `kubewarden-controller`. +Multiple [[< policy-server >]]s can be deployed in the same Kubernetes cluster. A `PolicyServer` validates incoming requests by executing Kubewarden policies against them. @@ -172,7 +173,7 @@ Changing any of these attributes causes a `PolicyServer` deployment with the new ### ClusterAdmissionPolicy -The `ClusterAdmissionPolicy` resource is the core of the Kubewarden stack. It defines how policies evaluate requests. +The [[< cluster-admission-policy >]]`ClusterAdmissionPolicy` resource is the core of the Kubewarden stack. It defines how policies evaluate requests. Enforcing policies is the most common operation which a Kubernetes administrator performs. You can declare as many policies as you want, each will target one or more Kubernetes resources (i.e., `pods`, `Custom Resource`). @@ -232,7 +233,7 @@ The policy will process only the requests that are targeting the Namespace where Other than that, there are no functional differences between the `AdmissionPolicy` and `ClusterAdmissionPolicy` resources. :::info -`AdmissionPolicy` requires Kubernetes 1.21.0 or above. This is because we are using the `kubernetes.io/metadata.name` label, which was introduced in Kubernetes 1.21.0 +`AdmissionPolicy` requires Kubernetes 1.21.0 or above. This is because we're using the `kubernetes.io/metadata.name` label, which was introduced in Kubernetes 1.21.0 ::: The complete documentation of these Custom Resources can be found [here](https://github.com/kubewarden/kubewarden-controller/blob/main/docs/crds/README.asciidoc) or on [docs.crds.dev](https://doc.crds.dev/github.com/kubewarden/kubewarden-controller). @@ -316,7 +317,7 @@ spec: EOF ``` -This will produce the following output: +This produces the following output: ```console pod/unprivileged-pod created @@ -376,8 +377,8 @@ kubectl delete namespace kubewarden ``` :::caution -Kubewarden contains a helm pre-delete hook that will remove all `PolicyServers` and `kubewarden-controller`. -Then the `kubewarden-controller` will delete all resources, so it is important that `kubewarden-controller` is running when helm uninstall is executed. +Kubewarden contains a helm pre-delete hook that removes all `PolicyServer`s and `kubewarden-controller`s. +Then the `kubewarden-controller` will delete all resources, so it's important that `kubewarden-controller` is running when helm uninstall is executed. ::: `ValidatingWebhookConfigurations` and `MutatingWebhookConfigurations` created by kubewarden should be deleted, this can be checked with: diff --git a/variables.json b/variables.json index 6f6d5d2637..5e52c1ee6b 100644 --- a/variables.json +++ b/variables.json @@ -3,7 +3,26 @@ "admission-policy": "
AdmissionServerA namespace-wide resource. The policy processes only requests targeting the namespace where the AdmissionPolicy is defined. [Glossary](glossary#admission-policy)
", + "cluster-admission-policy": "
ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. [Glossary](glossary#cluster-admission-policy)
", + + "cluster-policy-report": "
ClusterPolicyReportA PolicyReport and a ClusterPolicyReport store results of policy scans. Which one is used, depends on the scope of the resource. [Glossary](glossary#clusterpolicyreport)
", + + "kwctl": "
kwctlA CLI tool to generate and test Kubernetes YAML files for policy deployment. [Glossary](glossary#kwctl)
", + + "mutating-webhook-configuration": "
MutatingWebhookConfigurationA Kubernetes resource created by the Kubewarden controller to let Kubernetes know where to send an `AdmissionReview`. [Glossary](glossary#mutatingwebhookconfiguration)
", + + "policy-report": "
PolicyReportA PolicyReport and a ClusterPolicyReport store results of policy scans. Which one is used depends on the scope of the resource. [Glossary](glossary#policyreport)
", + "policy-server": "
PolicyServerA PolicyServer validates incoming requests by executing Kubewarden policies against requests. [Glossary](glossary#policy-server)
", - "cluster-admission-policy": "
ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. [Glossary](glossary#cluster-admission-policy)
" + "validating-webhook-configuration": "
ValidatingWebhookConfigurationA Kubernetes resource created by the Kubewarden controller to let Kubernetes know where to send a `AdmissionReview`. [Glossary](glossary#validatingwebhookconfiguration)
", + + "waPC": "
wapcWebAssembly Procedure Calls. https://wapc.io. [Glossary](glossary#wapc)
", + + "WASI": "
wasiWebAssembly System Interface. https://wasi.dev. [Glossary](glossary#wasi)
", + + "Wasm": "
wasm A binary instruction format for a stack-based virtual machine. Designed for web deployment. https://webassemly.org.[Glossary](glossary#wasm)
", + + "Wasmtime": "
wasmtimeA runtime for WebAssembly. https://wasmtime.dev. [Glossary](glossary#wasmtime)
" + }