Merge branch 'main' into multi-prov-docs

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
+```

docs/content/en/docs/concepts/architecture/components/_index.md

@@ -28,36 +28,3 @@ style Scheduler fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
 style Lifecycle-Operator fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
 style Metrics-Operator fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
 ```
-
-**Keptn's Lifecycle Operator** is
-a Kubernetes [operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
-that automates the deployment and management
-of the Keptn Lifecycle Controller components in a Kubernetes cluster.
-The Keptn Lifecycle Operator contains several controllers for **Keptn CRDs**
-and a **Mutating Webhook**.
-
-Here's a brief overview:
-
-**Keptn CRDs:** Keptn Lifecycle Operator contains
-several controllers that manage and reconcile different types of Keptn CRDs
-such as the Project Controller, Service Controller, and Stage Controller.
-
-**Mutating Webhook:** automatically injects Keptn labels
-and annotations into Kubernetes resources,
-such as deployments and services.
-These labels and annotations are used to enable Keptn's automation
-and monitoring capabilities.
-
-**Keptn's Lifecycle Metrics Operator**
-collects,  processes, and analyzes metrics data from a variety of sources.
-Once collected, this data, can be used to generate a variety of reports
-and dashboards that provide insights into the health and performance of the application and infrastructure.
-
-**Keptn's Lifecycle Scheduler** replaces the
-[Kubernetes scheduler](https://kubernetes.io/docs/concepts/scheduling-eviction/kube-scheduler/)
-to allow users to schedule events and tasks to occur
-at specific times during the application lifecycle.
-The Lifecycle Scheduler can trigger events such as
-deployment, testing, and remediation at specific times or intervals.
-The Keptn Scheduler guarantees that Pods are initiated only after
-the Pre-Deployment checks are completed.

docs/content/en/docs/concepts/architecture/components/lifecycle-operator/_index.md

@@ -0,0 +1,27 @@
+---
+title: Keptn Lifecycle Operator
+linktitle: Lifecycle Operator
+description: Basic understanding of Keptn's Lifecycle Operator
+weight: 80
+cascade:
+---
+
+
+**Keptn's Lifecycle Operator** is
+a Kubernetes [operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
+that automates the deployment and management
+of the Keptn Lifecycle Controller components in a Kubernetes cluster.
+The Keptn Lifecycle Operator contains several controllers for **Keptn CRDs**
+and a **Mutating Webhook**.
+
+Here's a brief overview:
+
+**Keptn CRDs:** Keptn Lifecycle Operator contains
+several controllers that manage and reconcile different types of Keptn CRDs
+such as the Project Controller, Service Controller, and Stage Controller.
+
+**Mutating Webhook:** automatically injects Keptn labels
+and annotations into Kubernetes resources,
+such as deployments and services.
+These labels and annotations are used to enable Keptn's automation
+and monitoring capabilities.

docs/content/en/docs/concepts/architecture/components/metrics-operator/_index.md

@@ -0,0 +1,54 @@
+---
+title: Keptn Metrics Operator
+linktitle: Metrics Operator
+description: Basic understanding of Keptn's Metrics Operator
+weight: 80
+cascade:
+---
+
+
+The Keptn Metrics Operator collects, processes, and analyzes metrics data from a variety of sources.
+Once collected, this data, can be used to generate a variety of reports and dashboards
+that provide insights into the health and performance of the application and infrastructure.
+
+While Kubernetes does have two metrics servers, they have limitations.
+The custom and external APIs only allow you to use a single observability platform.
+The Keptn Metrics Operator solves this problem by providing a single entry point for
+all your metrics data, regardless of its source.
+Furthermore, due to the integration with the Kubernetes custom metrics API, these metrics are also
+compatible with the Kubernetes HorizontalPodAutoscaler (HPA) which enables the horizontal scaling of workloads
+based on metrics collected from multiple observability platforms such as Prometheus, Dynatrace or Datadog.
+
+The Metrics Operator consists of the following components:
+
+* Metrics Controller
+* Metrics Adapter
+
+```mermaid
+graph TD;
+    Metrics-Operator-->Metrics-Adapter;
+    Metrics-Operator-->Metrics-Controller
+style Metrics-Operator fill:#006bb8,stroke:#fff,stroke-width:px,color:#fff
+style Metrics-Adapter fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
+style Metrics-Controller fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
+```
+
+**Metrics adapter** is used to expose custom metrics from an application to external monitoring and alerting tools.
+The adapter exposes custom metrics on a specific endpoint where external monitoring and alerting tools can scrape them.
+It is an important component of the metrics operator as it allows for the collection and exposure of custom metrics,
+which can be used to gain insight into the behavior and performance of applications running on a Kubenetes cluster.
+
+**Metrics controller** is used to fetch metrics from a SLI provider.
+The controller reconciles a [`KeptnMetric`](../../../../yaml-crd-ref/metric.md) CR and
+updates its status with the metric value provided by the selected SLI provider.
+The steps in which the controller fetches metrics are given below:
+
+* It first fetches the `KeptnMetric` object to reconcile.
+* If the object is not found, it returns and lets Kubernetes handle deleting all associated resources.
+* If the object is found, the code checks that if the metric has been updated within the configured
+interval which is defined in the `Spec.FetchIntervalSeconds`.
+If not, then it skips reconciling and requeues the request for later.
+* If the metric should be reconciled, it fetches the provider defined in the `Spec.Provider.Name` field.
+* If the provider is not found, it returns and requeues the request for later.
+* If the provider is found, it loads the provider and evaluates the query defined in the `Spec.Query` field.
+* If the evaluation is succesful, it stores the fetched value in the status of the `KeptnMetric` object.

docs/content/en/docs/concepts/architecture/components/scheduler/_index.md

@@ -0,0 +1,16 @@
+---
+title: Keptn Lifecycle Scheduler
+linktitle: Scheduler
+description: Basic understanding of Keptn's Lifecycle Scheduler
+weight: 80
+cascade:
+---
+
+**Keptn's Lifecycle Scheduler** replaces the
+[Kubernetes scheduler](https://kubernetes.io/docs/concepts/scheduling-eviction/kube-scheduler/)
+to allow users to schedule events and tasks to occur
+at specific times during the application lifecycle.
+The Lifecycle Scheduler can trigger events such as
+deployment, testing, and remediation at specific times or intervals.
+The Keptn Scheduler guarantees that Pods are initiated only after
+the Pre-Deployment checks are completed.

docs/content/en/docs/getting-started.md

@@ -149,7 +149,7 @@ kubectl describe keptnworkloadinstances podtato-head-podtato-head-entry -n podta
 ```
 
 > **Note**
-The event stream of the object contains more detailed informatio
+The event stream of the object contains more detailed information
 
 <details>
 <summary>Watch application state</summary>

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

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.

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.

docs/content/en/docs/snippets/tasks/install.md

@@ -2,8 +2,7 @@
 
 ## Install version 0.7.0 and above
 
-In version 0.7.0 and later, you can install the Lifecycle Toolkit using helm charts,
-or manifests.
+In version 0.7.0 and later, you can install the Lifecycle Toolkit using either helm charts or manifests.
 
 For installing the Lifecycle Toolkit via Helm chart: