diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index f72623ce16..7e243586b7 100644 --- 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 index 14fa525f45..81ec4fc187 100644 --- 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 new file mode 100644 index 0000000000..cbefb3ab15 --- /dev/null +++ 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 index ff846acdcc..bea083e437 100644 --- 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 index f403b45f13..f9709d5c9d 100644 --- 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 index 943de88f38..d7ca1dbc0d 100644 --- 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 . ``` +> **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 index 758c9be4bd..009fe71e3c 100644 --- 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 index 2921cbfc99..b3a280a723 100644 --- 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 index b10fd720ee..c71f0ad76e 100644 --- a/docs-new/docs/components/metrics-operator.md +++ b/docs-new/docs/components/metrics-operator.md @@ -7,20 +7,21 @@ 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. @@ -28,15 +29,30 @@ 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(()) +P1[] <--> Y +P3 <--> Y +P3 <--> Z +P2[] <--> 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, diff --git a/docs-new/docs/components/scheduling.md b/docs-new/docs/components/scheduling.md index d98a154165..9e7a76de3d 100644 --- a/docs-new/docs/components/scheduling.md +++ b/docs-new/docs/components/scheduling.md @@ -38,14 +38,14 @@ For example, a pod gated by Keptn looks like the following: {% include "./assets/gated.yaml" %} ``` -If the `pre-deployment` checks have finished successfully, +If the `pre-deployment` checks and evaluations have finished successfully, the WorkloadVersion Controller removes the gate from the Pod. -The default k8s scheduler can then allow the Pod to be bound to a node. +The default k8s scheduler then binds the Pod to a node. If the `pre-deployment` checks have not yet finished successfully, the gate stays and the Pod remains in the pending state. When removing the gate, the WorkloadVersion controller also adds the following annotation so that, -if the spec is updated, the Pod is not gated again: +if the Pod is updated, it is not gated again: ```yaml {% include "./assets/gate-removed.yaml" %} @@ -56,7 +56,7 @@ if the spec is updated, the Pod is not gated again: The **Keptn Scheduler** works by registering itself as a Permit plugin within the Kubernetes scheduling cycle that ensures that Pods are scheduled to a node until and unless the pre-deployment checks have finished successfully. -This helps to prevent Pods from being scheduled to nodes that are not yet ready for them, +This helps to prevent Pods from being bound to nodes that are not yet ready for them, which can lead to errors and downtime. Furthermore, it also allows users to control the deployment of an application based on customized rules that can take into consideration more parameters than what the default @@ -73,7 +73,7 @@ a [Permit plugin](https://kubernetes.io/docs/concepts/scheduling-eviction/schedu Firstly the Mutating Webhook checks for annotations on Pods to see if it is annotated with [Keptn specific annotations](../guides/integrate.md#basic-annotations). If the annotations are present, the Webhook assigns the **Keptn Scheduler** to the Pod. -This ensures that the Keptn Scheduler only gets Pods that have been annotated for it. +This ensures that the Keptn Scheduler only manages Pods that have been annotated for Keptn. A Pod `test-pod` modified by the Mutating Webhook looks as follows: ```yaml @@ -82,43 +82,26 @@ A Pod `test-pod` modified by the Mutating Webhook looks as follows: If the Pod is annotated with Keptn specific annotations, the Keptn Scheduler retrieves the WorkloadVersion CRD that is associated with the Pod. -The **WorkloadVersion CRD** contains information about the `pre-deployment` checks that +The **WorkloadVersion CR** contains information about the `pre-deployment` checks that need to be performed before the Pod can be scheduled. -The Keptn Scheduler then checks the status of the WorkloadVersion CRD to see +The Keptn Scheduler then checks the status of the WorkloadVersion CR to see if the `pre-deployment` checks have finished successfully. If the pre-deployment checks have finished successfully, the **Keptn Scheduler** allows -the Pod to be scheduled to a node. -If the `pre-deployment` checks have not yet finished, the Keptn Scheduler tells Kubernetes to check again later. +the Pod to be bound to a node. +If the `pre-deployment` checks have not finished successfully within 5 minutes, +the Pod is not bound to a node and it remains in a Pending state. It is important to note that the Keptn Scheduler is a plugin to the default Kubernetes scheduler. -This means that all of the checks that are performed by the default Kubernetes scheduler +This means that all of the checks that are by default performed by the default Kubernetes scheduler will also be performed by the **Keptn Scheduler**. For example, if there is not enough capacity on any node to schedule the Pod, the Keptn Scheduler will not be able to schedule it, even if the `pre-deployment` checks have finished successfully. -The Keptn Scheduler processes the following information from the WorkloadVersion CRD: - -* The name of the pre-deployment checks that need to be performed. -* The status of the pre-deployment checks. -* The deadline for the pre-deployment checks to be completed. -* The Keptn Scheduler checks the status of the `pre-deployment` checks every 10 seconds. -If the checks have not finished successfully within 5 minutes, -the Keptn Scheduler does not allow the Pod to be scheduled. - -If all of the `pre-deployment` checks have finished successfully and the deadline has not been reached, -the Keptn Scheduler allows the Pod to be scheduled. -If any of the `pre-deployment` checks have not finished successfully or the deadline has -been reached, the Keptn Scheduler tells Kubernetes to check again later. - -Also the Keptn Scheduler will not schedule Pods to nodes that have failed `pre-deployment` -checks in the past. -This helps to prevent Pods from being scheduled to nodes that are not ready for them. - ## Integrating Keptn with your custom scheduler Keptn scheduling logics are compatible with -the [Scheduler Framework](https://kubernetes.io/docs/concepts/scheduling-eviction/scheduling-framework/). +the [Kubernetes Scheduler Framework](https://kubernetes.io/docs/concepts/scheduling-eviction/scheduling-framework/). Keptn does not work with a custom scheduler unless it is implemented as a [scheduler plugin](https://kubernetes.io/docs/concepts/scheduling-eviction/scheduling-framework/#plugin-configuration). diff --git a/mkdocs.yml b/mkdocs.yml index ce14305f14..436a0ad143 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -55,6 +55,7 @@ extra_javascript: extra_css: - assets/stylesheets/versions.css - assets/stylesheets/color-schemes.css + - assets/stylesheets/mermaid.css plugins: - search - social @@ -65,6 +66,12 @@ plugins: - blog: blog_dir: blog draft_if_future_date: true +markdown_extensions: + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format nav: - Home: