Merge pull request #446 from jvanz/main

Explain how certificate rotation works
kubewarden · Sep 6, 2024 · 8ef9743 · 8ef9743
2 parents d15deaf + 9d82880
commit 8ef9743
Show file tree

Hide file tree

Showing 8 changed files with 68 additions and 61 deletions.
diff --git a/docs/explanations/certificates.md b/docs/explanations/certificates.md
@@ -0,0 +1,56 @@
+---
+sidebar_label: Certificate rotation
+sidebar_position: 21
+title: Certificate rotation 
+description: How Kubewarden controller manages its certificates
+keywords: [ kubewarden, certificate, controller, reconciliation ]
+doc-persona: [kubewarden-operator]
+doc-type: [explanation]
+doc-topic: [explanations, certificates]
+---
+
+<head>
+  <link rel="canonical" href="https://docs.kubewarden.io/explanations/certificates"/>
+</head>
+
+
+Since Kubewarden v1.17.0, the cert-manager dependency was removed. 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
+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
+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
+certificates and webhook configurations used by the entire Kubewarden stack.
+
+:::note
+All the certificates generated by the Helm chart and later by the controller uses
+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 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/howtos/Rancher-Fleet.md b/docs/howtos/Rancher-Fleet.md
@@ -21,9 +21,8 @@ It does this by defining [Fleet Bundles](https://fleet.rancher.io/concepts).
 
 ## Installing
 
-The Kubewarden charts are standard charts,
-they have dependencies (such as `cert-manager`),
-and depend transitively on each other
+The Kubewarden charts are standard charts, they depend transitively on each
+other
 
 `kubewarden-crds` ← `kubewarden-controller` ← `kubewarden-defaults`
 

diff --git a/docs/howtos/airgap/02-install.md b/docs/howtos/airgap/02-install.md
@@ -34,16 +34,6 @@ Alternatively, the `imagelist.txt` and `policylist.txt` files are shipped inside
 
     :::
 
-1. Add `cert-manager`, if not available, to your private registry.
-
-    ```console
-    helm repo add jetstack https://charts.jetstack.io
-    helm repo update
-    helm pull jetstack/cert-manager
-    helm template ./cert-manager-<Version>.tgz | \
-      awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./kubewarden-images.txt
-    ```
-
 1. Download `kubewarden-save-images.sh` and `kubewarden-load-images.sh` from the
 [utilities repository](https://github.com/kubewarden/utils).
 1. Save Kubewarden container images into a `.tar.gz` file:
@@ -84,12 +74,6 @@ helm pull kubewarden/kubewarden-controller
 helm pull kubewarden/kubewarden-defaults
 ```
 
-Download `cert-manager`, if not installed, to the air gap cluster.
-
-```shell
-helm pull jetstack/cert-manager
-```
-
 ## Populate private registry
 
 Move these files to the air gap environment:
@@ -136,22 +120,12 @@ in the documentation to learn about configuring the `sources.yaml` file
 
 ## Install Kubewarden
 
-Now that your private registry has everything required you can install Kubewarden.
-The only difference to a standard Kubewarden installation is that you need to change the registry in the container images and policies to be the private registry.
-
-Install `cert-manager`, if not already installed, in the air gap cluster:
-
-```shell
-helm install --create-namespace cert-manager ./cert-manager-<Version>.tgz \
-    -n kubewarden \
-    --set crds.enabled=true \
-    --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/jetstack/cert-manager-controller \
-    --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/jetstack/cert-manager-webhook \
-    --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/jetstack/cert-manager-cainjector \
-    --set startupapicheck.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/jetstack/cert-manager-ctl
-```
+Now that your private registry has everything required you can install
+Kubewarden. The only difference to a standard Kubewarden installation is that
+you need to change the registry in the container images and policies to be the
+private registry.
 
-Now install the Kubewarden stack:
+Install the Kubewarden stack:
 
 ```shell
 helm install --wait -n kubewarden \

diff --git a/docs/howtos/telemetry/20-tracing-qs.md b/docs/howtos/telemetry/20-tracing-qs.md
@@ -88,8 +88,8 @@ echo http://`minikube ip`
 We can proceed to the deployment of Kubewarden in the usual way.
 
 :::note
-cert-manager is a requirement of Kubewarden, and OpenTelemetry is required for this
-feature, but we've already installed them in a previous section of this book.
+cert-manager is a requirement of OpenTelemetry, but we've already installed
+them in a previous section of this book.
 :::
 
 As a first step, we have to add the Helm repository that contains Kubewarden:

diff --git a/docs/howtos/telemetry/30-metrics-qs.md b/docs/howtos/telemetry/30-metrics-qs.md
@@ -98,8 +98,8 @@ EOF
 We can now install Kubewarden in the recommended way with Helm charts.
 
 :::note
-cert-manager is a requirement of Kubewarden, and OpenTelemetry is required for this
-feature, but we've already installed them in a previous section of this book.
+cert-manager is a requirement of OpenTelemetry, but we've already installed
+them in a previous section of this book.
 :::
 
 As a first step, we have to add the Helm repository that contains Kubewarden:

diff --git a/docs/quick-start.md b/docs/quick-start.md
@@ -44,20 +44,6 @@ The Kubernetes Custom Resource Definitions (CRDs) defined by Kubewarden are desc
 
 ## Installation
 
-:::info Prerequisites
-The Helm chart depends on `cert-manager`. Ensure you install [`cert-manager`](https://cert-manager.io/docs/installation/) _before_ the `kubewarden-controller` chart.
-
-You can install the latest version of `cert-manager` through Helm by running the following commands:
-
-```console
-helm repo add jetstack https://charts.jetstack.io
-
-helm install --wait --namespace cert-manager --create-namespace \
-	--set crds.enabled=true cert-manager jetstack/cert-manager
-```
-
-:::
-
 :::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).

diff --git a/docs/reference/dependency-matrix.md b/docs/reference/dependency-matrix.md
@@ -25,14 +25,6 @@ backwards-incompatible changes still happen. Kubewarden devs do their best to
 track Opentelemetry stack changes and adjust to them. Kubewarden is tested against a known working
 range of Opentelemetry, metrics and tracing stack.
 
-## Hard dependencies
-
-Needed for Kubewarden deployments.
-
-| Chart dependency              | Helm chart `appVersion` | Helm chart `version` |        Comments        |
-| ----------------------------- | :---------------------: | :------------------: | :--------------------: |
-| `jetstack/cert-manager` chart |      `>= 1.13 < 2`      |  Example: `v1.13.2`  | Plans to make optional |
-
 ## Optional dependencies
 
 Needed for specific features.

diff --git a/docs/reference/threat-model.md b/docs/reference/threat-model.md
@@ -283,7 +283,7 @@ For example, by:
 - using unsigned and malicious images for:
   - Kubewarden-controller
   - policy-server
-  - any of the Kubewarden dependencies (cert-manager)
+  - any of the Kubewarden dependencies 
   - any optional dependencies (Grafana, Prometheus, and others)
 - by compromising the Helm charts payload