From 170e7fb33ab1798559a3df5257a0c1676b990f73 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Charles-Edouard=20Br=C3=A9t=C3=A9ch=C3=A9?=
 <charles.edouard@nirmata.com>
Date: Mon, 6 Jan 2025 12:39:03 +0100
Subject: [PATCH] docs: add docs for certificates management
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Charles-Edouard Brétéché <charles.edouard@nirmata.com>
---
 website/docs/install/certificates.md          | 57 +++++++++++++++++++
 website/docs/quick-start/authz-server.md      |  2 +
 website/docs/tutorials/envoy-gateway/index.md |  2 +
 website/docs/tutorials/istio/index.md         |  2 +
 website/mkdocs.yaml                           |  2 +
 5 files changed, 65 insertions(+)
 create mode 100644 website/docs/install/certificates.md

diff --git a/website/docs/install/certificates.md b/website/docs/install/certificates.md
new file mode 100644
index 0000000..e5d6e86
--- /dev/null
+++ b/website/docs/install/certificates.md
@@ -0,0 +1,57 @@
+# Certificates management
+
+The Kyverno Authz Server comes with a validation webhook and needs a valid certificate to let the api server call into it.
+
+At deployment time you can either provide your own certificate or use [cert-manager](https://cert-manager.io) to create one for the Kyverno Authz Server.
+
+## Bring your own
+
+If you want to bring your own certificate, you can set `certificates.static` values when installing the helm chart.
+
+```bash
+# create certificate
+openssl req -new -x509  \
+  -subj "/CN=kyverno-authz-server-validation.kyverno.svc" \
+  -addext "subjectAltName = DNS:kyverno-authz-server-validation.kyverno.svc" \
+  -nodes -newkey rsa:4096 -keyout tls.key -out tls.crt
+
+# install chart with static certificate
+helm install kyverno-authz-server \
+  --namespace kyverno --create-namespace \
+  --wait \
+  --repo https://kyverno.github.io/kyverno-envoy-plugin kyverno-authz-server \
+  --set-file certificates.static.crt=tls.crt \
+  --set-file certificates.static.key=tls.key
+```
+
+## Use cert-manager
+
+If you don't want to manage the certificate yourself you can rely on [cert-manager](https://cert-manager.io) to create the certificate for you and inject it in the webhook configuration.
+
+```bash
+# install cert-manager
+helm install cert-manager \
+  --namespace cert-manager --create-namespace \
+  --wait \
+  --repo https://charts.jetstack.io cert-manager \
+  --set crds.enabled=true
+
+# create a certificate issuer
+kubectl apply -f - <<EOF
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: selfsigned-issuer
+spec:
+  selfSigned: {}
+EOF
+
+# install chart with managed certificate
+helm upgrade --install kyverno-authz-server \
+  --namespace kyverno --create-namespace \
+  --wait \
+  --repo https://kyverno.github.io/kyverno-envoy-plugin kyverno-authz-server \
+  --set certificates.certManager.issuerRef.group=cert-manager.io \
+  --set certificates.certManager.issuerRef.kind=ClusterIssuer \
+  --set certificates.certManager.issuerRef.name=selfsigned-issuer
+```
diff --git a/website/docs/quick-start/authz-server.md b/website/docs/quick-start/authz-server.md
index 5382917..dc12846 100644
--- a/website/docs/quick-start/authz-server.md
+++ b/website/docs/quick-start/authz-server.md
@@ -81,6 +81,8 @@ spec:
 EOF
 ```
 
+For more certificate management options, refer to [Certificates management](../install/certificates.md).
+
 ### Deploy the Kyverno Authz Server
 
 Now we can deploy the Kyverno Authz Server.
diff --git a/website/docs/tutorials/envoy-gateway/index.md b/website/docs/tutorials/envoy-gateway/index.md
index ced5591..74f0174 100644
--- a/website/docs/tutorials/envoy-gateway/index.md
+++ b/website/docs/tutorials/envoy-gateway/index.md
@@ -149,6 +149,8 @@ spec:
 EOF
 ```
 
+For more certificate management options, refer to [Certificates management](../../install/certificates.md).
+
 ### Deploy the Kyverno Authz Server
 
 Now deploy the Kyverno Authz Server.
diff --git a/website/docs/tutorials/istio/index.md b/website/docs/tutorials/istio/index.md
index 2d219b9..2f49346 100644
--- a/website/docs/tutorials/istio/index.md
+++ b/website/docs/tutorials/istio/index.md
@@ -81,6 +81,8 @@ spec:
 EOF
 ```
 
+For more certificate management options, refer to [Certificates management](../../install/certificates.md).
+
 ### Deploy the Kyverno Authz Server
 
 Now we can deploy the Kyverno Authz Server.
diff --git a/website/mkdocs.yaml b/website/mkdocs.yaml
index 191708c..e5f9738 100644
--- a/website/mkdocs.yaml
+++ b/website/mkdocs.yaml
@@ -7,6 +7,8 @@ nav:
   - quick-start/authz-server.md
   - quick-start/sidecar-injector.md
   - quick-start/next-steps.md
+  - Install:
+    - install/certificates.md
 - Policies:
   - policies/index.md
   - policies/failure-policy.md