diff --git a/docs/howtos/airgap/01-requirements.md b/docs/howtos/airgap/01-requirements.md index 28106561d07..b8913a3609a 100644 --- a/docs/howtos/airgap/01-requirements.md +++ b/docs/howtos/airgap/01-requirements.md @@ -1,7 +1,7 @@ --- sidebar_label: Requirements -title: Requirements for a Kubewarden air gap installation -description: Requirements for a Kubewarden air gap installation. +title: Requirements for installing Kubewarden in an air gapped environment +description: Requirements for installing Kubewarden in an air gapped installation. keywords: [kubewarden, kubernetes, air gap installation] doc-persona: [kubewarden-operator, kubewarden-integrator] doc-type: [howto] diff --git a/docs/howtos/airgap/02-install.md b/docs/howtos/airgap/02-install.md index 283a63c3a3f..0a80772476f 100644 --- a/docs/howtos/airgap/02-install.md +++ b/docs/howtos/airgap/02-install.md @@ -12,8 +12,8 @@ doc-topic: [operator-manual, airgap, installation] -This guide shows you how to install Kubewarden in air-gapped environments. -For an air-gapped installation of Kubewarden, +This guide shows you how to install Kubewarden in air gapped environments. +For an air gapped installation of Kubewarden, you need a private Open Container Initiative (OCI) registry accessible by your Kubernetes cluster. Kubewarden Policies are WebAssembly modules, therefore you can store them in an OCI-compliant registry as OCI artifacts. @@ -142,7 +142,7 @@ helm install --wait -n kubewarden \ :::caution To use the Policy Reported sub-chart available in the `kubewarden-controller` chart you need to define other values specific for the -sub-chart in an air-gapped environment. +sub-chart in an air gapped environment. See an example below: ```shell diff --git a/docs/howtos/airgap/_category_.json b/docs/howtos/airgap/_category_.json index ae6a44b525f..c801003d029 100644 --- a/docs/howtos/airgap/_category_.json +++ b/docs/howtos/airgap/_category_.json @@ -1,5 +1,5 @@ { - "label": "Airgap", + "label": "Air gap", "position": 100, "collapsed": true } diff --git a/docs/howtos/application-collection/_category_.json b/docs/howtos/application-collection/_category_.json index ac59ad39362..03cb6593911 100644 --- a/docs/howtos/application-collection/_category_.json +++ b/docs/howtos/application-collection/_category_.json @@ -1,5 +1,5 @@ { "label": "Rancher Application Collection", - "position": 120, + "position": 140, "collapsed": true } diff --git a/docs/howtos/argocd-installation.md b/docs/howtos/argocd-installation.md index 222cdebac38..dcb0b31abf1 100644 --- a/docs/howtos/argocd-installation.md +++ b/docs/howtos/argocd-installation.md @@ -1,6 +1,6 @@ --- sidebar_label: ArgoCD Installation -sidebar_position: 35 +sidebar_position: 90 title: ArgoCD Installation description: How to install Kubewarden with ArgoCD keywords: [kubewarden, gitops, argocd] diff --git a/docs/howtos/audit-scanner.md b/docs/howtos/audit-scanner.md index 47c6a8ea659..1e66f3cd6c5 100644 --- a/docs/howtos/audit-scanner.md +++ b/docs/howtos/audit-scanner.md @@ -1,6 +1,6 @@ --- sidebar_label: Audit Scanner -sidebar_position: 70 +sidebar_position: 21 title: Audit Scanner description: How-to install and use Audit Scanner. keywords: [kubewarden, kubernetes, audit scanner] diff --git a/docs/howtos/pod-security-admission-with-kubewarden.md b/docs/howtos/pod-security-admission-with-kubewarden.md index d274362b64c..3d6f97c7cc2 100644 --- a/docs/howtos/pod-security-admission-with-kubewarden.md +++ b/docs/howtos/pod-security-admission-with-kubewarden.md @@ -1,6 +1,6 @@ --- sidebar_label: Pod Security Admission -sidebar_position: 30 +sidebar_position: 42 title: Using Pod Security Admission with Kubewarden description: Using Pod Security Admission with Kubewarden, since the Kubernetes 1.25 release. keywords: [kubewarden, pod security admission, pod security policy, kubernetes] diff --git a/docs/howtos/policies.md b/docs/howtos/policies.md index 1122cd39617..32984e7f97b 100644 --- a/docs/howtos/policies.md +++ b/docs/howtos/policies.md @@ -1,6 +1,6 @@ --- sidebar_label: Configuring policies -sidebar_position: 90 +sidebar_position: 30 title: Configuring policies description: Dependency matrix of Kubewarden. keywords: [policies, ClusterAdmissionPolicies, AdmissionPolicies, configuration, namespaces] diff --git a/docs/howtos/policy-groups.md b/docs/howtos/policy-groups.md index f8aa8c4139b..2839b2fdfbf 100644 --- a/docs/howtos/policy-groups.md +++ b/docs/howtos/policy-groups.md @@ -1,6 +1,6 @@ --- sidebar_label: Policy Groups -sidebar_position: 36 +sidebar_position: 33 title: How to use policy groups description: How to use Kubewarden policy groups keywords: [kubewarden, policy groups, clusteradmissionpolicygroup, admissionpolicygroup] diff --git a/docs/howtos/policy-servers/_category_.json b/docs/howtos/policy-servers/_category_.json index 806e6873346..ffc07c67723 100644 --- a/docs/howtos/policy-servers/_category_.json +++ b/docs/howtos/policy-servers/_category_.json @@ -1,5 +1,5 @@ { "label": "Configuring Policy Servers", - "position": 80, + "position": 32, "collapsed": true } diff --git a/docs/howtos/production-deployments.md b/docs/howtos/production-deployments.md index e0cb0fcccad..c0d8f512c02 100644 --- a/docs/howtos/production-deployments.md +++ b/docs/howtos/production-deployments.md @@ -2,6 +2,7 @@ sidebar_label: Production deployments title: Configuring Kubewarden stack for production description: Configuring Kubewarden stack for production +sidebar_position: 20 keywords: [ kubewarden, diff --git a/docs/howtos/psp-migration.md b/docs/howtos/psp-migration.md index 6e664d5aa0b..171b737b44d 100644 --- a/docs/howtos/psp-migration.md +++ b/docs/howtos/psp-migration.md @@ -1,6 +1,6 @@ --- sidebar_label: PSP migration -sidebar_position: 20 +sidebar_position: 40 title: PodSecurityPolicy migration description: Discusses PSP migration to Kubewarden policies after Kubernetes v1.25. keywords: [kubewarden, kubernetes, appvia, psp, pod security policy] diff --git a/docs/howtos/security-hardening/_category_.json b/docs/howtos/security-hardening/_category_.json index b2ea062b3a1..d820fbbeee1 100644 --- a/docs/howtos/security-hardening/_category_.json +++ b/docs/howtos/security-hardening/_category_.json @@ -1,5 +1,5 @@ { "label": "Security", - "position": 100, + "position": 90, "collapsed": true } diff --git a/docs/howtos/secure-supply-chain.md b/docs/howtos/security-hardening/secure-supply-chain.md similarity index 99% rename from docs/howtos/secure-supply-chain.md rename to docs/howtos/security-hardening/secure-supply-chain.md index 914c9bb2c81..0d06f342c62 100644 --- a/docs/howtos/secure-supply-chain.md +++ b/docs/howtos/security-hardening/secure-supply-chain.md @@ -295,7 +295,7 @@ The following checks were performed on each of these signatures: ## Configuring the policy server to check policy signatures You can configure Kubewarden with a `ConfigMap` to only run trusted policies. -The `ConfigMap` structure described in [Signature Config Reference](../reference/verification-config.md#signature-configuration-reference). +The `ConfigMap` structure described in [Signature Config Reference](../../reference/verification-config.md#signature-configuration-reference). It's used to verify a policy using `kwctl`. The `ConfigMap` should define allowable configurations under the `verification-config` field. diff --git a/docs/howtos/security-hardening/security-hardening.md b/docs/howtos/security-hardening/security-hardening.md new file mode 100644 index 00000000000..af00f2dde95 --- /dev/null +++ b/docs/howtos/security-hardening/security-hardening.md @@ -0,0 +1,81 @@ +--- +sidebar_label: Security hardening +sidebar_position: 50 +title: Security hardening +description: Harden the Kubewarden installation +keywords: [kubewarden, kubernetes, security] +doc-persona: [kubewarden-operator, kubewarden-integrator] +doc-type: [howto] +doc-topic: [operator-manual, security] +--- + +Kubewarden strives to be secure with little configuration. +In this section and its subpages you can find hardening tips (with their +trade-offs) to secure Kubewarden itself. + +Please refer to our [threat model](../reference/threat-model) for more information. + +### `kubewarden-defaults` Helm chart + +Operators can obtain a secure deployment by installing all the +Kubewarden Helm charts. It's recommended to install the +`kubewarden-defaults` Helm chart and enable its recommended policies with: + +```console +helm install --wait -n kubewarden kubewarden-defaults kubewarden/kubewarden-defaults \ + --set recommendedPolicies.enabled=True \ + --set recommendedPolicies.defaultPolicyMode=protect +``` + +This provides a default PolicyServer and default policies, in protect mode, to +ensure the Kubewarden stack is safe from other workloads. + +### Verifying Kubewarden artifacts + +See the [Verifying Kubewarden](../tutorials/verifying-kubewarden) tutorial. + +### RBAC + +Kubewarden describes RBAC configurations in different +_Explanations_ sections. Users can fine-tune the needed permissions for the +[Audit Scanner](../explanations/audit-scanner#permissions-and-serviceaccounts) +feature, as well as [per Policy Server](../explanations/context-aware-policies) +Service Account for the context-aware feature. + +The view all Roles: + +```console +kubectl get clusterroles,roles -A | grep kubewarden +``` + +### Per-policy permissions + +For context-aware policies, operators specify fine-grained permissions per +policy under its `spec.contectAwareResources`, and those work in conjuction +with the Service Account configured for the Policy Server where the policy +runs. + +### Workload coverage + +By default, Kubewarden excludes specific Namespaces from Kubewarden coverage. This is +done to simplify first-time use and interoperability with other workloads. + +Security-conscious operators can tune these Namespaces list via the +`.global.skipNamespaces` value for both the `kubewarden-controller` and +`kubewarden-defaults` Helm charts. + +### SecurityContexts + +Starting from 1.23, Kubewarden's stack is able to run in a Namespace +where the [restricted +Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/#restricted) +are enforced, with current Pod hardening best practices. + +The `kubewarden-controller` Helm chart configures the SecurityContexts and +exposes them in its `values.yaml`. + +The `kubewarden-defaults` Helm chart allows for configuing the default Policy +Server `.spec.securityContexts` under `.Values.policyServer.securityContexts`. + +For Policy Servers managed by operators, you can configure them via their +[`spec.securityContexts`](https://docs.kubewarden.io/reference/CRDs#policyserversecurity). diff --git a/docs/howtos/security-hardening/webhook-mtls.md b/docs/howtos/security-hardening/webhook-mtls.md index c9b0b6ef001..d90634ff441 100644 --- a/docs/howtos/security-hardening/webhook-mtls.md +++ b/docs/howtos/security-hardening/webhook-mtls.md @@ -15,6 +15,9 @@ doc-topic: [operator-manual, security] This guide shows you how to enable mutual TLS (mTLS) for all the webhooks used by the Kubewarden stack when using [k3s](https://k3s.io/) as your Kubernetes distribution. +For more information on how to harden the webhooks, see the [reference +page](../../reference/security-hardening/webhooks-hardening). + ## Prerequisites Before installing k3s, you need to create a certificate authority (CA) and a client certificate to use to secure the communication between the Kubewarden webhooks and the Kubernetes API server. diff --git a/docs/howtos/ui-extension/01-install.md b/docs/howtos/ui-extension/01-install.md index cd2baa62f14..71a7719b9b0 100644 --- a/docs/howtos/ui-extension/01-install.md +++ b/docs/howtos/ui-extension/01-install.md @@ -26,7 +26,7 @@ however, the Kubewarden controller is installed through the Rancher UI as a cluster scoped resource. :::note -For air-gapped installations, follow [these steps](../airgap/02-install.md). +For air gapped installations, follow [these steps](../airgap/02-install.md). ::: Within the Extensions page, @@ -101,7 +101,7 @@ As Kubewarden is a Rancher Official Extension, the Rancher team provides a mechanism to automatically generate an Extension Catalog Image. This is added to the `rancher-images.txt` file when [installing Rancher Manager](https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images#1-find-the-required-assets-for-your-rancher-version) -for air-gapped instances. +for air gapped instances. Once this image has been mirrored to a registry accessible to your air-gapped cluster, you can import the image within the Rancher UI. diff --git a/docs/howtos/ui-extension/_category_.json b/docs/howtos/ui-extension/_category_.json index cffc9dba974..fe92cd0a952 100644 --- a/docs/howtos/ui-extension/_category_.json +++ b/docs/howtos/ui-extension/_category_.json @@ -1,5 +1,5 @@ { "label": "Rancher UI extension", - "position": 110, + "position": 130, "collapsed": true } diff --git a/docs/howtos/vap-migration.md b/docs/howtos/vap-migration.md index 50391872bbd..721f8e2c45c 100644 --- a/docs/howtos/vap-migration.md +++ b/docs/howtos/vap-migration.md @@ -1,6 +1,6 @@ --- sidebar_label: ValidatingAdmissionPolicy migration -sidebar_position: 35 +sidebar_position: 41 title: ValidatingAdmissionPolicy migration description: Discusses how to migrate from Kubernetes VAP policies to Kubewarden. keywords: [kubewarden, kubernetes, cel, vap, validatingadmissionpolicy] diff --git a/docs/howtos/workarounds/_category_.json b/docs/howtos/workarounds/_category_.json index fcc60be22fe..2df736758da 100644 --- a/docs/howtos/workarounds/_category_.json +++ b/docs/howtos/workarounds/_category_.json @@ -1,5 +1,5 @@ { "label": "Workarounds", - "position": 15, + "position": 140, "collapsed": true } diff --git a/docs/reference/spec/host-capabilities/02-signature-verifier-policies.md b/docs/reference/spec/host-capabilities/02-signature-verifier-policies.md index 9ba2b8b2118..db30f705272 100644 --- a/docs/reference/spec/host-capabilities/02-signature-verifier-policies.md +++ b/docs/reference/spec/host-capabilities/02-signature-verifier-policies.md @@ -26,7 +26,7 @@ This allows implementing a "Secure Supply Chain" for your cluster. Part of the function of the secure supply chain is to ensure that all container images running in the cluster are signed and verified. This proves that they come from their stated authors, with no tampering. For further reading, check the docs on -[how we implement a Secure Supply Chain for the policies themselves](../../../howtos/secure-supply-chain.md). +[how we implement a Secure Supply Chain for the policies themselves](../../../howtos/security-hardening/secure-supply-chain.md). Sigstore signatures are stored inside of container registries, next to the OCI object being signed. diff --git a/docs/reference/threat-model.md b/docs/reference/threat-model.md index 742a7c66a00..0781d7d2081 100644 --- a/docs/reference/threat-model.md +++ b/docs/reference/threat-model.md @@ -302,6 +302,6 @@ For example, by: The Kubernetes Administrator must verify the Kubewarden images, its dependencies' images, and charts out of the Kubernetes cluster, in a trusted environment. You can do this with `cosign`, for example. - Incidentally, this is part of the implementation needed for air-gapped installations. + Incidentally, this is part of the implementation needed for air gapped installations. 2. Use signed Helm charts, and verified digests instead of tags for Kubewarden images in those Helm charts. This doesn't secure dependencies though. diff --git a/docs/reference/verification-config.md b/docs/reference/verification-config.md index 38722da2514..b188f0d5e93 100644 --- a/docs/reference/verification-config.md +++ b/docs/reference/verification-config.md @@ -20,7 +20,7 @@ The verification-config format is used by: - `policy-server` to verify policy modules provenance - `verify-image-signatures` policy to verify cluster images provenance -See [secure supply chain](../howtos/secure-supply-chain.md) for more info. +See [secure supply chain](../howtos/security-hardening/secure-supply-chain.md) for more info. ## Format