docs: update components section (keptn#2712)

Signed-off-by: odubajDT <[email protected]> Signed-off-by: Dubaj <[email protected]> Signed-off-by: odubajDT <[email protected]> Co-authored-by: Dubaj <[email protected]> Co-authored-by: Meg McRoberts <[email protected]> Co-authored-by: Moritz Wiesinger <[email protected]>
mowies · Jan 16, 2024 · a1330ee · a1330ee
1 parent 1fe4f15
commit a1330ee
Show file tree

Hide file tree

Showing 11 changed files with 166 additions and 123 deletions.
diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt
@@ -690,3 +690,5 @@ yml
 YOURNAME
 yourregistry
 youtube
+pymdownx
+superfences
diff --git a/docs-new/Makefile b/docs-new/Makefile
@@ -16,6 +16,7 @@ else
 INTERACTIVE_FLAG := -t
 endif
 
+PIP_CACHE_DIR=$(shell pip3 cache dir)
 PWD=$(shell pwd)
 
 .PHONY: docs-build
@@ -25,7 +26,7 @@ docs-build:
 		-v ${PWD}/requirements.txt:/requirements.txt \
 		-v ${PWD}/site:/site \
 		-v ${PWD}/.git:/.git \
-		-v ${PWD}/tmp/.pip-cache:/root/.cache/pip \
+		-v ${PIP_CACHE_DIR}:/root/.cache/pip \
 		--entrypoint "" \
 		${MKDOCS_DOCKER_IMAGE}:${MKDOCS_DOCKER_IMAGE_VERSION} \
 		sh -c 'cd /; pip install -r requirements.txt -q; mkdocs build'
@@ -38,7 +39,7 @@ docs-serve:
 		-v ${PWD}/requirements.txt:/requirements.txt \
 		-v ${PWD}/site:/site \
 		-v ${PWD}/.git:/.git \
-		-v ${PWD}/tmp/.pip-cache:/root/.cache/pip \
+		-v ${PIP_CACHE_DIR}:/root/.cache/pip \
 		--entrypoint "" \
 		${MKDOCS_DOCKER_IMAGE}:${MKDOCS_DOCKER_IMAGE_VERSION} \
 		sh -c 'cd /; pip install -r requirements.txt -q; mkdocs serve --dirty -a 0.0.0.0:$(PORT)'

diff --git a/docs-new/assets/stylesheets/mermaid.css b/docs-new/assets/stylesheets/mermaid.css
@@ -0,0 +1,3 @@
+.mermaid {
+   text-align: center;
+}
diff --git a/docs-new/docs/components/certificate-operator.md b/docs-new/docs/components/certificate-operator.md
@@ -1,65 +1,40 @@
-# Keptn Certificate Manager
+# Keptn Cert Manager
 
-## Keptn Cert Manager
-
-The Keptn Cert Manager automatically configures TLS certificates to
+The Keptn Cert Manager is a Kubernetes operator that
+automatically configures TLS certificates to
 [secure communication with the Kubernetes API](https://kubernetes.io/docs/concepts/security/controlling-access/#transport-security).
-You can instead
-[use cert-manager.io](../installation/configuration/cert-manager.md)
-for this purpose.
-
-Keptn 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 [keptn-cert-manager](https://github.com/keptn/lifecycle-toolkit/blob/main/keptn-cert-manager/README.md).
-
-How it works:
-
-* The certificate is created as a secret
-in the `keptn-system` namespace
-with a renewal threshold of 12 hours.
-* If the certificate expires,
-the [keptn-cert-manager](https://github.com/keptn/lifecycle-toolkit/blob/main/keptn-cert-manager/README.md)
-renews it.
-* The Keptn `lifecycle-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.
-
-`keptn-cert-manager` is a customized certificate manager
-that is installed with Keptn by default.
-It is included to simplify installation for new users
-and because it is much smaller than most standard certificate managers.
-However, Keptn is compatible with most certificate managers
-and can be configured to use another certificate manager if you prefer.
-See [Use Keptn with cert-manager.io](../installation/configuration/cert-manager.md)
-for instructions.
 
-## Invalid certificate errors
+Keptn includes mutating, validating and conversion Webhooks
+that require TLS certificates to be mounted as a volume.
+These webhooks and CRDs contain a `keptn.sh/inject-cert: "true"` label indicating that
+these resources require a TLS certificate.
 
-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.
+```mermaid
+graph TD;
 
-The Keptn cert-manager certificate is stored as a secret in the
-`keptn-system` namespace.
-To retrieve it:
-
-```shell
-kubectl get secrets -n keptn-system
+E((Manifests)) -- apply --> D[Kubernetes API]
+F[Webhook Controller] <-- watches Secret --> D
+    
+style D fill:#006bb8,stroke:#fff,stroke-width:px,color:#fff
+style F fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
+style E fill:#fff,stroke:#123,stroke-width:px,color:#006bb8
 ```
 
-This returns something like:
+How it works:
 
-```shell
-NAME                        TYPE                 DATA   AGE
-keptn-certs                   Opaque               5      4d23h
-```
+* Keptn Cert Manager looks for the resources with `keptn.sh/inject-cert: "true"` label.
+* It creates a [secret](https://kubernetes.io/docs/concepts/configuration/secret/)
+(if it does not exist yet) with a TLS certificate in the
+Keptn installation namespace and mounts this Secret as a volume to the labelled resource.
+* The TLS certificate stored in the Secret has an expiration time of 12 hours and is
+automatically renewed.
 
-Specify the `NAME` of the Keptn certificate (`keptn-certs` in this case)
-to delete the Keptn certificate:
+If you don't want to use Keptn Cert Manager, you can instead
+use [cert-manager.io](../installation/configuration/cert-manager.md)
+for this purpose.
 
-```shell
-kubectl delete secret keptn-certs -n keptn-system
-```
+## Troubleshooting
+
+When experiencing problems with setting up cert-manager.io,
+please refer to the
+[cert-manager.io troubleshooting page](https://cert-manager.io/docs/troubleshooting/).
diff --git a/docs-new/docs/components/index.md b/docs-new/docs/components/index.md
@@ -8,3 +8,18 @@ Keptn consists of the following main components:
 * [Keptn Metrics Operator](./metrics-operator.md)
 * [Keptn Scheduler](./scheduling.md)
 * [Keptn Certificate Manager](./certificate-operator.md)
+
+The architectural diagram:
+
+```mermaid
+graph TD;
+
+A[Lifecycle Operator]
+B[Metrics Operator] -- provide metrics --> A
+C[Cert manager] -- watch certificate --> A
+C[Cert manager] -- watch certificate --> B
+
+style A fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
+style B fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
+style C fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
+```
diff --git a/docs-new/docs/components/lifecycle-operator/deployment-flow.md b/docs-new/docs/components/lifecycle-operator/deployment-flow.md
@@ -58,6 +58,7 @@ If any pre-deployment evaluation or task fails,
 the `KeptnApp` issues an appropriate `*Errored` event
 and the deployment remains pending indefinitely,
 until further changes or external intervention
+either resolve the problem or terminate the execution.
 If all evaluations and tasks in a phase are successful,
 the `KeptnApp` issues the appropriate `*Succeeded` event
 and initiates the next phase.
@@ -70,6 +71,9 @@ To view these events on your cluster, execute:
 kubectl get events -n <namespace> . 
 ```
 
+> **Note**
+This only displays Kubernetes events, not Cloud Events.
+
 ### Pre-deployment phase
 
 Pre-deployment tasks can perform any kind of action needed
@@ -159,28 +163,32 @@ AppPostDeployEvaluations
 Completed
 ```
 
-## Events that are not part of the deployment flow
+## Events that are generated asynchronously
 
 Additional phases/states exist,
-such as those that describe what happens when something fails.
-
-Whenever something in the system happens (we create a new resource, etc.)
-a Kubernetes event is generated.
-The following events are defined as part of Keptn
-but they are not part of the deployment flow.
+such as those that describe what is currently happening in the system.
+During the lifetime of the application, custom resources are created,
+updated, deleted or reconciled.
+Each reconciliation, or re-evaluation of the state of custom resources
+by the controller, can cause the generation of events.
 These include:
 
 ```shell
-CreateEvaluation
 ReconcileEvaluation
 ReconcileTask
+ReconcileWorkload
+CreateEvaluation
 CreateTask
 CreateApp
 CreateAppVersion
 CreateWorkload
 CreateWorkloadVersion
-Completed
+CreateAppCreationRequest
+UpdateWorkload
+DeprecateAppVersion
+AppCompleted
+WorkloadCompleted
 Deprecated
-WorkloadDeployReconcile
-WorkloadDeployReconcileErrored
+Completed
+Cancelled
 ```
diff --git a/docs-new/docs/components/lifecycle-operator/index.md b/docs-new/docs/components/lifecycle-operator/index.md
@@ -4,17 +4,50 @@
 a Kubernetes [operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
 that automates the deployment and management
 of the Keptn components in a Kubernetes cluster.
-The Keptn Lifecycle Operator contains several controllers for **Keptn CRDs**
-and a **Mutating Webhook**.
+It plays a crucial role in managing and orchestrating
+the various stages of application lifecycle management within
+Keptn.
 
-Here's a brief overview:
+The lifecycle operator acts as the backbone of Keptn, overseeing the entire application lifecycle from deployment
+to testing, evaluation, and observability.
+It facilitates a streamlined and automated approach to managing the evolution of applications, ensuring smooth
+transitions between different stages such as development, testing, staging, and production.
 
-**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.
+```mermaid
+graph TD;
 
-**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.
+G((CRs + manifests)) -- apply --> H[Kubernetes API]
+I[Scheduler] <-- schedules Pods --> H
+J[Lifecycle controllers] <-- orchestrates --> H
+    
+style H fill:#006bb8,stroke:#fff,stroke-width:px,color:#fff
+style I fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
+style J fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
+style G fill:#fff,stroke:#123,stroke-width:px,color:#006bb8
+```
+
+Key responsibilities of the lifecycle operator include:
+
+1. **Automated Deployment:** It automates the deployment of applications using various deployment strategies,
+such as blue-green deployments or canary releases, ensuring seamless rollouts without disrupting the user experience.
+
+2. **Continuous Testing:** The operator integrates testing mechanisms throughout the lifecycle, enabling continuous
+validation of application changes.
+It runs automated tests, assesses performance, and ensures the application meets predefined quality gates
+before moving to the next stage.
+
+3. **Evaluation and Feedback:** It collects metrics and evaluates the performance of deployed applications
+against predefined Service Level Objectives (SLOs) and Service Level Indicators (SLIs).
+It analyzes this data to provide feedback and insights into the application's health and performance.
+
+4. **Observability:** It provides observability of the running application out-of-the-box by exposing metrics,
+traces and logs.
+
+5. **State Management and Versioning:** It manages the state and versioning of applications, keeping track of
+different versions deployed across various environments and ensuring consistency in the deployment process.
+
+Overall, the lifecycle operator in Keptn acts as an intelligent control system, orchestrating the flow of
+changes and ensuring the reliability, quality, and agility of applications throughout their lifecycle in
+a cloud-native environment.
+It empowers development teams to focus on innovation by automating repetitive tasks and providing a
+standardized, efficient approach to managing complex application lifecycle.
diff --git a/docs-new/docs/components/lifecycle-operator/keptn-apps.md b/docs-new/docs/components/lifecycle-operator/keptn-apps.md
@@ -10,7 +10,7 @@ with the ability to handle extra phases.
 It can execute the pre/post-deployment evaluations of a Workload
 and run pre/post-deployment tasks.
 
-In its state, it tracks the currently active `Workload Instances`,
+In its state, it tracks the currently active `Workload Instances`
 (`Pod`, `DaemonSet`, `StatefulSet`, and `ReplicaSet` resources),
 as well as the overall state of the Pre Deployment phase,
 which Keptn can use to determine
@@ -97,9 +97,9 @@ Annotations take precedence over labels,
 and the `keptn.sh` keys take precedence over `app.kubernetes.io` keys.
 In other words:
 
-* The operator first checks if the `keptn.sh/` key is present
+* The operator first checks if the `keptn.sh/*` key is present
   in the annotations, and then in the labels.
-* If neither is the case, it looks for the `app.kubernetes.io/` equivalent,
+* If neither is the case, it looks for the `app.kubernetes.io/*` equivalent,
   again first in the annotations, then in the labels.
 
 Keptn automatically generates appropriate

diff --git a/docs-new/docs/components/metrics-operator.md b/docs-new/docs/components/metrics-operator.md
@@ -7,36 +7,52 @@ to generate a variety of reports and dashboards
 that provide insights into the health and performance
 of the application and infrastructure.
 
-While Kubernetes has ways to extend its metrics APIs, they have limitations,
-especially that they only allow you to use a single observability platform
+While Kubernetes has ways to extend its metrics APIs, there are limitations,
+especially that they allow you to use only a single observability platform
 such as Prometheus, Dynatrace or Datadog.
 The Keptn Metrics Operator solves this problem
 by providing a single entry point for
-all your metrics data, regardless of its source,
-so you can use multiple instances of multiple observability platforms.
+all your metrics data, regardless of its source.
+This means that data multiple observability platforms are available via
+a single access point.
 
 Keptn metrics are integrated with the Kubernetes
 [Custom Metrics API](https://github.com/kubernetes/metrics#custom-metrics-api),
 so they are compatible with the Kubernetes
 [HorizontalPodAutoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)
 (HPA), which enables the horizontal scaling of workloads
-based on metrics collected from multiple observability platforms.
+based on metrics collected from observability platforms.
 See
 [Using the HorizontalPodAutoscaler](../use-cases/hpa.md)
 for instructions.
 
 The Metrics Operator consists of the following components:
 
 * Metrics Controller
+* Analysis 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
+K((CRs)) -- apply --> L[Kubernetes API]
+X[Metrics Adapter] <--> L
+Y[Metrics Controller] <--> L
+Z[Analysis Controller] <--> L
+
+P3((<svg height="80" width="80"><image href="https://upload.wikimedia.org/wikipedia/commons/thumb/3/38/Prometheus_software_logo.svg/2066px-Prometheus_software_logo.svg.png" height="80" width="80" /></svg>))
+P1[<svg height="80" width="100"><image href="https://imgix.datadoghq.com/img/about/presskit/usage/logousage_white.png" height="100" width="100" /></svg>]  <--> Y
+P3 <--> Y
+P3 <--> Z
+P2[<svg height="70" width="100"><image href="https://seeklogo.com/images/D/dynatrace-logo-0B89594073-seeklogo.com.png" height="70" width="100" /></svg>] <--> Z
+
+style L fill:#006bb8,stroke:#fff,stroke-width:px,color:#fff
+style Y fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
+style Z fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
+style X fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8
+style K fill:#fff,stroke:#123,stroke-width:px,color:#006bb8
+style P1 fill:#fff,stroke:#fff,stroke-width:px,color:#fff
+style P2 fill:#fff,stroke:#fff,stroke-width:px,color:#fff
+style P3 fill:#fff,stroke:#fff,stroke-width:px,color:#fff
 ```
 
 The **Metrics adapter** exposes custom metrics from an application
@@ -67,12 +83,12 @@ The steps in which the controller fetches metrics are given below:
    * If not, it skips the reconciliation process
      and queues the request for later.
 
-1. The controller attempts to fetch the provider defined in the
+2. The controller attempts to fetch the provider defined in the
    `spec.provider.name` field.
    * If this is not possible, the controller reconciles
      and queues the request for later.
 
-1. If the provider is found,
+3. If the provider is found,
    the controller loads the provider and evaluates the query
    defined in the `spec.query` field.
    * If the evaluation is successful,