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 00000000000..d49a1940dce --- /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/architecture/components/_index.md b/docs/content/en/docs/concepts/architecture/components/_index.md index b8e961dfb58..dcb3f14462c 100644 --- a/docs/content/en/docs/concepts/architecture/components/_index.md +++ b/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. diff --git a/docs/content/en/docs/concepts/architecture/components/lifecycle-operator/_index.md b/docs/content/en/docs/concepts/architecture/components/lifecycle-operator/_index.md new file mode 100644 index 00000000000..e064671db57 --- /dev/null +++ b/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. diff --git a/docs/content/en/docs/concepts/architecture/components/metrics-operator/_index.md b/docs/content/en/docs/concepts/architecture/components/metrics-operator/_index.md new file mode 100644 index 00000000000..48752c79f0e --- /dev/null +++ b/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. diff --git a/docs/content/en/docs/concepts/architecture/components/scheduler/_index.md b/docs/content/en/docs/concepts/architecture/components/scheduler/_index.md new file mode 100644 index 00000000000..52a3b0a3a1e --- /dev/null +++ b/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. 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 b935a31f163..00000000000 --- 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/getting-started.md b/docs/content/en/docs/getting-started.md index 2d76d1e7a40..2eacac03f19 100644 --- a/docs/content/en/docs/getting-started.md +++ b/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
Watch application state diff --git a/docs/content/en/docs/install/_index.md b/docs/content/en/docs/install/_index.md index 786b2a2372b..2c71a4fced7 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 00000000000..f78913c4155 --- /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 eb20b5793f0..e9ec16d46b3 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. diff --git a/docs/content/en/docs/snippets/tasks/install.md b/docs/content/en/docs/snippets/tasks/install.md index 67879395fdb..9872a7e721d 100644 --- a/docs/content/en/docs/snippets/tasks/install.md +++ b/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: