From a84cbc7d67e8608f4c6638ab8d8efc1424f46933 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Tue, 18 Apr 2023 04:03:14 -0700 Subject: [PATCH] docs: replace cert-manager (#1210) Signed-off-by: Meg McRoberts Signed-off-by: Meg McRoberts Co-authored-by: Giovanni Liva --- .../concepts/architecture/cert-manager.md | 65 ++++++++++++ .../overview/klc-cert-manager/_index.md | 25 ----- docs/content/en/docs/install/_index.md | 3 + docs/content/en/docs/install/cert-manager.md | 99 +++++++++++++++++++ docs/content/en/docs/install/reqs.md | 9 ++ 5 files changed, 176 insertions(+), 25 deletions(-) create mode 100644 docs/content/en/docs/concepts/architecture/cert-manager.md delete mode 100644 docs/content/en/docs/concepts/overview/klc-cert-manager/_index.md create mode 100644 docs/content/en/docs/install/cert-manager.md diff --git a/docs/content/en/docs/concepts/architecture/cert-manager.md b/docs/content/en/docs/concepts/architecture/cert-manager.md new file mode 100644 index 0000000000..d49a1940dc --- /dev/null +++ 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 deleted file mode 100644 index b935a31f16..0000000000 --- a/docs/content/en/docs/concepts/overview/klc-cert-manager/_index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Keptn Certificate Manager -icon: concepts -layout: quickstart -weight: 5 -hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html ---- - -### Keptn Cert Manager - -The Lifecycle Toolkit includes a Mutating Webhook which 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). - -The certificate is created as a secret in the `keptn-lifecycle-toolkit-system` namespace with a renewal threshold of 12 -hours. -If it 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. -The certificate is mounted on an empty dir volume in the operator. - -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. diff --git a/docs/content/en/docs/install/_index.md b/docs/content/en/docs/install/_index.md index 786b2a2372..2c71a4fced 100644 --- 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 new file mode 100644 index 0000000000..f78913c415 --- /dev/null +++ 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 index eb20b5793f..e9ec16d46b 100644 --- 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.