docs: add "Intro to KLT"; edit "Getting Started"

docs/.htmltest.yml

@@ -6,4 +6,7 @@ IgnoreDirs:
 IgnoreURLs:
   - "linkedin.com"
   - "localhost"
+  # our edit links in the sidebar might not work for newly created pages
+  - "github.com/keptn/lifecycle-toolkit/tree/main"
+  - "github.com/keptn/lifecycle-toolkit/edit/main"
 StripQueryString: false

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

@@ -5,32 +5,12 @@ description: Learn how to use the Keptn Lifecycle Toolkit.
 weight: 15
 ---
 
-`kubectl create -f deployment.yaml` will "blindly" deploy workloads, but who needs to be notified that this deployment
-is about to happen? Is your infrastructure ready? Do your downstream services meet their SLOs? Can your infrastructure
-handle the deployment?
 
-After the deployment, beyond the standard k8s probes, how can you integrate with other tooling to automatically test the
-deployment? How do you know the deployment is meeting its SLOs? Has the deployment caused any issues downstream? Who
-needs to know that the deployment was successful (or unsuccessful)?
+This page gives instructions for installing the Keptn Lifecycle Toolkit
+and running a simple Keptn application to familiarize yourself
+with how KLT works.
 
-The Keptn Lifecycle Toolkit (KLT) "wraps" a standard Kubernetes deployment and provides both workload (single service)
-tests and SLO evaluations. Multiple workloads can also be logically grouped (and evaluated) as a single cohesive unit: a
-Keptn Application. In other words, an application is a collection of multiple workloads.
-
-The Keptn Lifecycle Toolkit is a tool and vendor-neutral mechanism - it does not depend on particular GitOps tooling -
-ArgoCD, Flux, Gitlab or others - KLT works with them all.
-
-The Keptn Lifecycle Toolkit emits signals at every stage (k8s events, OpenTelemetry metrics and traces) to ensure your
-deployments are observable.
-
-Available steps (applicable to both workload and application entities):
-
-* Pre-Deployment Tasks: e.g. checking for dependant services, checking if the cluster is ready for the deployment, etc.
-* Pre-Deployment Evaluations: e.g. evaluate metrics before your application gets deployed (e.g. layout of the cluster)
-* Post-Deployment Tasks: e.g. trigger a test, trigger a deployment to another cluster, etc.
-* Post-Deployment Evaluations: e.g. evaluate the deployment, evaluate the test results, etc.
-
-## What you will learn here
+You will learn how to do the following:
 
 * Use the Keptn Lifecycle Toolkit to control the deployment of your application
 * Connect the lifecycle-toolkit to Prometheus
@@ -39,22 +19,28 @@ Available steps (applicable to both workload and application entities):
 
 ## Prerequisites
 
+You need the following to complete this exercise:
+
 * A Kubernetes cluster >= Kubernetes 1.24
-  * If you don't have one, we recommend [Kubernetes-in-Docker(KinD)](https://kind.sigs.k8s.io/docs/user/quick-start/)
-    to set up your local development environment
+  * If you don't have one, we recommend
+      [Kubernetes-in-Docker(KinD)](https://kind.sigs.k8s.io/docs/user/quick-start/)
+      to set up your local development environment
+
 * kubectl installed on your system
   * See (<https://kubernetes.io/docs/tasks/tools/>) for more information
 
 ## Check Kubernetes Version
 
-Run the following and ensure both client and server versions are greater than or equal to v1.24.
+Run the following and ensure that both client and server versions
+are running Kubernetes versions greater than or equal to v1.24.
 
 ```shell
 kubectl version --short
 ```
 
-The output should look like this. In this example, both client and server are at v1.24.0 so the Keptn Lifecycle Toolkit
-will work.
+The output should look like this.
+In this example, both client and server are at v1.24.0
+so the Keptn Lifecycle Toolkit will work.
 
 {{% readfile file="./snippets/tasks/k8s_version_output.md" markdown="true" %}}
 
@@ -64,9 +50,16 @@ will work.
 
 ## Check out the Getting Started Repository
 
-For the further progress of this guide, we need a sample application as well as some helpers which make it easier for
-your to set up your environment. These things can be found in our Getting Started repository which can be checked out as
-follows:
+This exercise uses a sample application and some helpers
+that make it easier for you to set up your environment.
+These can be found in our Getting Started repository.
+Use the following command to check out this repository:
+
+For the further progress of this guide,
+we need a sample application as well as some helpers
+which make it easier foryour to set up your environment.
+These things can be found in our Getting Started repository
+which can be checked out as follows:
 
 ```shell
 git clone https://github.com/keptn-sandbox/lifecycle-toolkit-examples.git
@@ -75,14 +68,22 @@ cd lifecycle-toolkit-examples
 
 ## Install the required observability features
 
-The Keptn Lifecycle Toolkit emits OpenTelemetry data as standard but the toolkit does not come pre-bundled with
-Observability backend tooling. This is deliberate as it provides flexibility for you to bring your own Observability
-backend which consumes this emitted data.
+The Keptn Lifecycle Toolkit emits OpenTelemetry data as standard
+but the toolkit does not come pre-bundled with Observability backend tooling.
+This is deliberate as it provides flexibility
+for you to bring your own Observability backend
+that consumes this emitted data.
+
+In order to use the observability features of the lifecycle toolkit,
+we need a monitoring and tracing backend.
+
+In this guide, we use:
 
-In order to use the observability features of the lifecycle toolkit, we need a monitoring and tracing backend.
+* [Prometheus](https://prometheus.io/) for Metrics
+* [Jaeger](https://jaegertracing.io) for Traces
+* [Grafana](https://github.com/grafana/) for Dashboarding
 
-In this guide, we will use [Prometheus](https://prometheus.io/) for Metrics, [Jaeger](https://jaegertracing.io) for
-Traces and [Grafana](https://github.com/grafana/) for Dashboarding.
+Install these with the following commands:
 
 ```shell
 make install-observability
@@ -91,22 +92,30 @@ make restart-lifecycle-toolkit
 
 ## The Demo Application
 
-For this demonstration, we use a slightly modified version
-of [the PodTatoHead](https://github.com/podtato-head/podtato-head).
+For this demonstration, we use a slightly modified version of
+[the PodTatoHead](https://github.com/podtato-head/podtato-head) application.
 
 <!-- markdown-link-check-disable-next-line -->
 ![img.png](assets/podtatohead.png)
 
-Over time, we will evolve this application from a simple manifest to a Keptn-managed application. We will install it
-first with kubectl and add pre- as well as post-deployment tasks. For this, we will check if the entry service is
-available before the other ones get scheduled. Afterward, we will add evaluations to ensure that our infrastructure is
-in a good shape before we deploy the application. Finally, we will evolve to a GitOps driven deployment and will notify
-an external webhook service when the deployment has finished.
+Over time, we will evolve this application
+from a simple manifest to a Keptn-managed application:
+
+* We install it with **kubectl**
+  then add pre- and post-deployment tasks.
+  * For this, we check if the entry service is available
+    before the other services are scheduled.
+* We then add evaluations to ensure
+    that our infrastructure is in good shape before we deploy the application.
+* Finally, we evolve to a GitOps driven deployment
+  and notify an external webhook service when the deployment has finished.
 
 ## Install the Demo Application (Version 1)
 
-In the first version of the Demo application, the Keptn Lifecycle Toolkit evaluates metrics provided by prometheus and
-checks if a specified amount of CPUs is available before deploying the application
+In the first version of the Demo application,
+the Keptn Lifecycle Toolkit evaluates metrics provided by Prometheus
+and checks if the specified amount of CPUs are available
+before deploying the application
 
 To install it, simply apply the manifest:
 
@@ -118,46 +127,58 @@ You can watch the progress of the deployment as follows:
 
 ### Watch workload state
 
-When the Lifecycle Toolkit detects workload labels ("app.kubernetes.io/name" and "keptn.sh/workload") on a resource, a
-KeptnWorkloadInstance (kwi) resource will be created. Using this resource you can watch the progress of the deployment.
+When the Lifecycle Toolkit detects workload labels
+("app.kubernetes.io/name" or "keptn.sh/workload") on a resource,
+a KeptnWorkloadInstance (kwi) resource is created.
+Using this resource you can watch the progress of the deployment.
 
 ```shell
 kubectl get keptnworkloadinstances -n podtato-kubectl
 ```
 
-This will show the current status of the Workloads and in which phase they are at the moment. You can get more detailed
-information about the workloads by describing one of the resources:
+This shows the current status of the Workloads
+and in which phase they are at the moment.
+You can get more detailed information about the workloads
+by describing one of the resources:
 
 ```shell
 kubectl describe keptnworkloadinstances podtato-head-podtato-head-entry -n podtato-kubectl
 ```
 
-Note that there are more detailed information in the event stream of the object.
-
-### Watch application state
-
-Although you didn't specify an application in your manifest, the Lifecycle Toolkit assumed that this is a single-service
-application and created an ApplicationVersion (kav) resource for you.
+Note that the event stream of the object contains more detailed information.
+</details>
 
-Using `kubectl get keptnappversions -n podtato-kubectl` you can see state of these resources.
+<details>
+<summary>Watch application state</summary>
+Although you didn't specify an application in your manifest,
+the Lifecycle Toolkit assumes that this is a single-service application
+and creates an ApplicationVersion (kav) resource for you.
 
-### Watch pods
+Using `kubectl get keptnappversions -n podtato-kubectl`,
+you can see the state of these resources.
+</details>
 
-Obviously, you should see that the pods are starting normally. You can watch the state of the pods using:
+<details>
+<summary>Watch pods</summary>
+Obviously, you should see that the pods are starting normally.
+You can watch the state of the pods using:
 
 ```shell
 kubectl get pods -n podtato-kubectl
 ```
 
-Furthermore, you can port-forward the podtato-head service to your local machine and access the application via your
-browser:
+Furthermore, you can port-forward the podtato-head service
+to your local machine and access the application via your browser:
 
 ```shell
 make port-forward-grafana
 ```
 
-In your browser (<http://localhost:3000>, Log in with the user 'admin' and the password 'admin'), you can open the
-Dashboard `Keptn Applications` and see the current state of the application which should be similar to the following:
+In your browser (<http://localhost:3000>),
+log in with the user `admin` and the password `admin`).
+You can open the Dashboard `Keptn Applications`
+and see the current state of the application,
+which should be similar to the following:
 
 <!-- markdown-link-check-disable-next-line -->
 ![grafana.png](assets/grafana.png)
@@ -169,26 +190,34 @@ In this screen you get the following information:
 * Deployment Time per Version
 * The link to the Trace of the deployment
 
-After some time (~60 seconds), you should see one more failed deployment in your dashboard. You can click on the link to
-the trace and see the reason for the failure:
+After some time (~60 seconds),
+you should see one more failed deployment in your dashboard.
+You can click on the link to the trace and see the reason for the failure:
 
 <!-- markdown-link-check-disable-next-line -->
 ![trace-failed.png](assets/trace-failed.png)
 
-In this case, we see the name of the failed pre-deployment evaluation and the reason for the failure. In this case, the
-minimum amount of CPUs is not met. This is a problem we can solve by changing the treshold in the evaluation file.
+In this case, we see the name of the failed pre-deployment evaluation
+and the reason for the failure.
+In this case, the minimum amount of CPUs is not met.
+This is a problem we can solve by changing the threshold in the evaluation file.
 
 ## Install the Demo Application (Version 2)
 
-To achieve this, we changed the operator in the evaluation file (sample-app/version-2/app-pre-deploy-eval) from `<`
-to `>` and applied the new manifest:
+To achieve this, we changed the operator in the evaluation file
+(sample-app/version-2/app-pre-deploy-eval) from `<` to `>`
+and applied the new manifest:
 
 ```shell
 kubectl apply -f sample-app/version-2
 ```
 
-After this, you can inspect the new state of the application using the same commands as before. You should see that the
-deployment is now successful and that the trace is also updated. You should also see in the Grafana Dashboards that the
-deployment was successful.
+After this, you can inspect the new state of the application
+using the same commands as before.
+You should see that the deployment is now successful
+and that the trace is also updated.
+You should also see in the Grafana Dashboards
+that the deployment was successful.
 
-Congratulations! You successfully deployed the first application using the Keptn Lifecycle Toolkit!
+Congratulations! You have successfully deployed an application
+using the Keptn Lifecycle Toolkit!

docs/content/en/docs/intro-klt.md

@@ -0,0 +1,100 @@
+---
+title: Introduction to the Keptn Lifecycle Toolkit
+linktitle: Introduction to the Keptn Lifecycle Toolkit
+description: Understand the Keptn Lifecycle Toolkit
+weight: 05
+cascade:
+  github_subdir: "docs/content/en/docs"
+  path_base_for_github_subdir: "/content/en/docs-dev"
+---
+
+The Keptn Lifecycle Toolkit (KLT) implements observability
+for deployments that are implemented with standard GitOps tools
+such as ArgoCD, Flux, and Gitlab
+and brings application awareness to your Kubernetes cluster.
+
+These standard GitOps deployment tools
+do an excellent job at deploying applications
+but do not handle all issues
+that are required to ensure that your deployment is usable.
+The Keptn Lifecycle Toolkit "wraps" a standard Kubernetes GitOps deployment
+with the capability to automatically handle issues
+before and after the actual deployment.
+
+Pre-deployment issues:
+
+* Send appropriate notifications that this deployment is about to happen
+* Check that downstream services meet their SLOs
+* Verify that your infrastructure is ready
+* Ensure that your infrastructure
+  has the resources necessary for a successful deployment
+
+Post-deployment issues:
+
+* Integrate with tooling beyond the standard Kubernetes probes
+* Automatically test the deployment
+* Ensure that the deployment is meeting its SLOs
+* Identify any downstream issues that may be caused by this deployment
+* Send appropriate notifications about whether the deployment was successful or unsuccessful
+
+KLT can evaluate both workload (single service) tests
+and SLO evaluations before and after the actual deployment.
+Multiple workloads can also be logically grouped and evaluated
+as a single cohesive unit called a `KeptnApp`.
+In other words, a `KeptnApp` is a collection of multiple workloads.
+
+KLT is tool- and vendor neutral and does not depend on particular GitOps tooling.
+KLT emits signals at every stage
+(Kubernetes events, OpenTelemetry metrics and traces)
+to ensure that your deployments are observable.
+It supports the following steps:
+
+* Pre-Deployment Tasks: e.g. checking for dependant services,
+  setting the cluster to be ready for the deployment, etc.
+* Pre-Deployment Evaluations: e.g. evaluate metrics
+  before your application gets deployed (e.g. layout of the cluster)
+* Post-Deployment Tasks: e.g. trigger a test,
+  trigger a deployment to another cluster, etc.
+* Post-Deployment Evaluations: e.g. evaluate the deployment,
+  evaluate the test results, etc.
+
+All of these things can be executed for a workload or for a KeptnApp,
+which is a collection of multiple workloads.
+
+## Compare Keptn Lifecycle Toolkit and Keptn LTS
+
+The Keptn Lifecycle Controller (KLT) is a Keptn subproject
+whose design reflects lessons we learned while developing Keptn LTS.
+KLT recognizes that tools such as Argo and Flux
+are very good at deploying applications.
+However, these deployment tools do not provide
+pre-deployment and post-deployment evaluations and actions;
+this is what KLT adds.
+
+Keptn LTS is a long-term support release
+that can deploy applications on platforms other than Kubernetes,
+can accomodate complex scoring algorithms for SLO evaluations,
+and can implement remediations (self-healing) for problems discovered
+on the production site.
+
+In a December 2022 Keptn Community meeting,
+we discussed the differences and similarities
+between Keptn and the Keptn Lifecycle Toolkit
+to help you decide which best fits your needs.
+View the recording:
+[Compare Keptn V1 and the Keptn Lifecycle Toolkit](https://www.youtube.com/watch?v=0nCbrG_RFos)
+
+## Overviews of Keptn Lifecycle Toolkit
+
+A number of presentations are available to give an overview
+of the Keptn Lifecycle Toolkit:
+
+* [What is keptn, how it works, and how to get started!](https://www.dynatrace.com/news/blog/what-is-keptn-how-it-works-and-how-to-get-started/)
+
+* [Observability and Orchestration of your Deployment](https://www.youtube.com/watch?v=0nCbrG_RFos)
+
+* [Keptn Lifecycle Toolkit Demo Tutorial on k3s, with ArgoCD for GitOps, OTel, Prometheus and Grafana](https://www.youtube.com/watch?v=6J_RzpmXoCc)
+
+* The "IsItObservable Tutorial for KLT" will be released to YouTube soon.
+* You can explore the [GitHub repository](https://github.com/isItObservable/keptn-lifecycle-Toolkit)
+* that accompanies this video in the meantime.