feat: explain how certificate rotation works.

Adds a new page in the explanation section of the documentation to clarify how the new certification rotation works. Signed-off-by: José Guilherme Vanz <[email protected]> Co-authored-by: John Krug <[email protected]>
kubewarden · Sep 5, 2024 · 2897543 · 2897543
1 parent 765e6ad
commit 2897543
Showing 1 changed file with 50 additions and 0 deletions.
diff --git a/docs/explanations/certificates.md b/docs/explanations/certificates.md
@@ -0,0 +1,50 @@
+---
+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. In the root CA renewal process, this
+is done by updating the webhooks to use a CA bundle with the new root CA and
+the old root CA. This allows the API server to continue to communicate with the
+Kubewarden controller while the new certificate is being propagated. 
+
+Once the new certificate is ready and the old one is invalid, the controller
+will update the webhook configuration to use the new certificate only. 
+
+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.
+