docs: replace cert-manager (keptn#1210)

Signed-off-by: Meg McRoberts <[email protected]> Signed-off-by: Meg McRoberts <[email protected]> Co-authored-by: Giovanni Liva <[email protected]>
mowies · Apr 18, 2023 · a84cbc7 · a84cbc7
1 parent c9b1a42
commit a84cbc7
Show file tree

Hide file tree

Showing 5 changed files with 176 additions and 25 deletions.
diff --git a/docs/content/en/docs/concepts/architecture/cert-manager.md b/docs/content/en/docs/concepts/architecture/cert-manager.md
@@ -0,0 +1,65 @@
+---
+title: Keptn Certificate Manager
+description: Learn how the cert-manager works
+icon: concepts
+layout: quickstart
+weight: 100
+hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html
+---
+
+### Keptn Cert Manager
+
+The Lifecycle Toolkit includes a Mutating Webhook
+that requires TLS certificates to be mounted as a volume in its pod.
+In version 0.6.0 and later, the certificate creation
+is handled automatically by
+the [klt-cert-manager](https://github.com/keptn/lifecycle-toolkit/blob/main/klt-cert-manager/README.md).
+
+How it works:
+
+* The certificate is created as a secret
+in the `keptn-lifecycle-toolkit-system` namespace
+with a renewal threshold of 12 hours.
+* If the certificate expires,
+the [klt-cert-manager](https://github.com/keptn/lifecycle-toolkit/blob/main/klt-cert-manager/README.md)
+renews it.
+* The Lifecycle Toolkit operator waits for a valid certificate to be ready.
+* When the certificate is ready,
+  it is mounted on an empty dir volume in the operator.
+
+`klt-cert-manager` is a customized certificate manager
+that is installed with the Lifecycle Toolkit by default.
+It is included to simplify installation for new users
+and because it is much smaller than most standard certificate managers.
+However, KLT is compatible with most certificate managers
+and can be configured to use another certificate manager if you prefer.
+See [Use your own cert-manager](../../install/cert-manager.md)
+for instructions.
+
+## Invalid certificate errors
+
+When a certificate is left over from an older version,
+the webhook or the operator may generate errors
+because of an invalid certificate.
+To solve this, delete the certificate and restart the operator.
+
+The KLT cert-manager certificate is stored as a secret in the `klt` namespace.
+To retrieve it:
+
+```shell
+kubectl get secrets -n keptn-lifecycle-toolkit-system
+```
+
+This returns something like:
+
+```shell
+NAME                        TYPE                 DATA   AGE
+klt-certs                   Opaque               5      4d23h
+```
+
+Specify the `NAME` of the KLT certificate (`klt-certs` in this case)
+to delete the KLT certificate:
+
+```shell
+kubectl delete secret klt-certs -n keptn-lifecycle-toolkit-system
+```
diff --git a/docs/content/en/docs/concepts/overview/klc-cert-manager/_index.md b/docs/content/en/docs/concepts/overview/klc-cert-manager/_index.md
diff --git a/docs/content/en/docs/install/_index.md b/docs/content/en/docs/install/_index.md
@@ -19,6 +19,9 @@ or as part of an existing production cluster.
 1. Understand the [Software versions and resources](reqs.md)
    that are required
 1. [Bring or create your Kubernetes cluster](k8s.md)
+1. [Replace the default cert-manager](cert-manager.md) (optional)
+   This step is only required if you want to replace the default KLT cert-manager
+   with another cert-manager.
 1. [Install the Keptn Lifecycle Controller](install.md)
 1. [Integrate the Keptn Lifecycle Controller into your Kubernetes cluster](integrate.md)
 1. [Upgrade](upgrade.md) to a new version of the Keptn Lifecycle Toolkit
diff --git a/docs/content/en/docs/install/cert-manager.md b/docs/content/en/docs/install/cert-manager.md
@@ -0,0 +1,99 @@
+---
+title: Use your own cert-manager (optional)
+description: Replace the default KLT cert-manager
+weight: 30
+hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html
+---
+
+The Keptn Lifecycle Toolkit includes
+a light-weight, customized cert-manager
+that is used to register Webhooks to the [KubeAPI](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/).
+Bundling the cert-manager simplifies the installation for new users
+and provides the functionality KLT needs
+without the overhead of other cert-managers.
+For a description of the architecture, see
+[Keptn Certificate Manager](../concepts/architecture/cert-manager.md).
+
+KLT, however, works well with standard cert-managers.
+The KLT cert-manager can also coexist with another cert-manager.
+If you are already using a different cert-manager,
+you can continue to use that cert-manager for other components
+and use the KLT cert-manager just for KLT activities
+or you can configure KLT to use that cert-manager.
+
+If you want KLT to use your cert-manager,
+you must configure it *before* you install KLT.
+The steps are:
+
+* Install the cert-manager of your choice
+  if it is not already installed.
+* Modify the `Deployment` manifest of each KLT operator component.
+* Add the `Certificate` CRD for the cert-manager you are using.
+
+## Modify the KLT manifest
+
+You must modify the KLT manifest for each KLT operator component
+to make it aware of the cert-manager you are using.
+These instructions implement
+[cert-manager.io](https://cert-manager.io/);
+the process is similar for other cert-managers.
+
+To configure KLT to use your cert-manager,
+change the `Deployment` manifest of each KLT operator component
+and **replace** the following `volumes` definition
+
+   ```yaml
+   - emptyDir: {}
+     name: certs-dir
+   ```
+
+   with
+
+   ```yaml
+   - name: cert
+     secret:
+       defaultMode: 420
+       secretName: webhook-server-cert
+   ```
+
+Each manifest must have the following special annotation:
+
+```yaml
+cert-manager.io/inject-ca-from=klt-serving-cert/keptn-lifecycle-toolkit-system
+```
+
+The value of the annotation must match the
+`name/namespace` of the cert-manager CRD discussed below.
+
+## Add the CRD for your cert-manager
+
+This is the CRD for `cert-manager.io`:
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: klt-serving-cert 
+  namespace: keptn-lifecycle-toolkit-system
+spec:
+  dnsNames:
+  - lifecycle-webhook-service.keptn-lifecycle-toolkit-system.svc
+  - lifecycle-webhook-service.keptn-lifecycle-toolkit-system.svc.cluster.local
+  issuerRef:
+    kind: Issuer
+    name: klt-selfsigned-issuer
+  secretName webhook-server-cert
+```
+
+Note the following about these fields:
+
+* The `apiVersion` field refers to the API for the cert-manager.
+* The `metadata` section includes two fields.
+  The value of these fields must match the annotations
+  used in the KLT operator manifests.
+* The value of the `secretName` field
+  must match the value of the `secretName` field used
+  in the `volumes` definition section of the KLT operator manifests above.
+
+See the [CA Injector](https://cert-manager.io/docs/concepts/ca-injector/)
+documentation for more details.
diff --git a/docs/content/en/docs/install/reqs.md b/docs/content/en/docs/install/reqs.md
@@ -12,3 +12,12 @@ hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.htm
 The Keptn Lifecycle Controller requires Kubernetes v1.24.0 or later.
 
 ## Resource requirements
+
+## cert-manager
+
+KLT includes a lightweight cert-manager
+that is used for installation and Webhooks.
+You can configure a different cert-manager
+before you install KLT.
+See [Implement your own cert-manager](cert-manager.md)
+for instructions.