From 0c1eecbf6d191c52f72f2590843e78f7742e3efc Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 18 Oct 2023 04:43:52 -0700 Subject: [PATCH 1/8] docs: restructure getting-started section Signed-off-by: Meg McRoberts --- .../content/en/docs/getting-started/_index.md | 593 +---------------- .../assets/webhook.site.1.png | Bin .../assets/webhook.site.2.png | Bin .../assets/webhook.site.3.png | Bin .../getting-started/observability/_index.md | 594 ++++++++++++++++++ .../assets/deploymenttrace.png | Bin .../{ => observability}/assets/grafana.png | Bin .../{ => observability}/assets/install01.png | Bin .../{ => observability}/assets/install02.png | Bin .../assets/keptnapplications.png | Bin .../assets/keptnprommetrics.png | Bin .../{ => observability}/assets/nginx.png | Bin .../assets/podtatohead.png | Bin .../assets/trace-failed.png | Bin .../tasks/_index.md | 5 +- .../usecase_metrics.md | 6 +- 16 files changed, 601 insertions(+), 597 deletions(-) rename docs/content/en/docs/{tutorials => getting-started}/assets/webhook.site.1.png (100%) rename docs/content/en/docs/{tutorials => getting-started}/assets/webhook.site.2.png (100%) rename docs/content/en/docs/{tutorials => getting-started}/assets/webhook.site.3.png (100%) create mode 100644 docs/content/en/docs/getting-started/observability/_index.md rename docs/content/en/docs/getting-started/{ => observability}/assets/deploymenttrace.png (100%) rename docs/content/en/docs/getting-started/{ => observability}/assets/grafana.png (100%) rename docs/content/en/docs/getting-started/{ => observability}/assets/install01.png (100%) rename docs/content/en/docs/getting-started/{ => observability}/assets/install02.png (100%) rename docs/content/en/docs/getting-started/{ => observability}/assets/keptnapplications.png (100%) rename docs/content/en/docs/getting-started/{ => observability}/assets/keptnprommetrics.png (100%) rename docs/content/en/docs/getting-started/{ => observability}/assets/nginx.png (100%) rename docs/content/en/docs/getting-started/{ => observability}/assets/podtatohead.png (100%) rename docs/content/en/docs/getting-started/{ => observability}/assets/trace-failed.png (100%) rename docs/content/en/docs/{tutorials => getting-started}/tasks/_index.md (97%) rename docs/content/en/docs/{intro => getting-started}/usecase_metrics.md (98%) diff --git a/docs/content/en/docs/getting-started/_index.md b/docs/content/en/docs/getting-started/_index.md index b1e576d302..a38869cd75 100644 --- a/docs/content/en/docs/getting-started/_index.md +++ b/docs/content/en/docs/getting-started/_index.md @@ -1,594 +1,5 @@ --- -title: Getting started with Keptn Observability -description: Get started with Keptn Observability +title: Getting started +description: Get started with Keptn weight: 20 --- - -Keptn provides sophisticated observability features -that enhance your existing cloud-native deployment environment. -These features are useful whether or not you use a GitOps strategy. - -The following is an imperative walkthrough. - -## Prerequisites - -- [Docker](https://docs.docker.com/get-started/overview/) -- [kubectl](https://kubernetes.io/docs/reference/kubectl/) -- [Helm](https://helm.sh/docs/intro/install/) -- A Kubernetes cluster >= 1.24 (we recommend [Kubernetes kind](https://kind.sigs.k8s.io/docs/user/quick-start/)) - (`kind create cluster`) - -## Objectives - -- Install Keptn on your cluster -- Annotate a namespace and deployment to enable Keptn -- Install Grafana and Observability tooling to view DORA metrics and OpenTelemetry traces - -## System Overview - -By the end of this page, here is what will be built. -The system will be built in stages. - -![system overview](assets/install01.png) - -## The Basics: A Deployment, Keptn and DORA Metrics - -To begin our exploration of the Keptn observability features, we will: - -- Deploy a simple application called `keptndemo`. - -Keptn will monitor the deployment and generate: - -- An OpenTelemetry trace per deployment -- DORA metrics - -![the basics](assets/install02.png) - -Notice though that the metrics and traces have nowhere to go. -That will be fixed in a subsequent step. - -## Step 1: Install Keptn - -Install Keptn using Helm: - -```shell -helm repo add klt https://charts.lifecycle.keptn.sh -helm repo update -helm upgrade --install keptn klt/klt -n keptn-lifecycle-toolkit-system --create-namespace --wait -``` - -Keptn will need to know where to send OpenTelemetry traces. -Of course, Jaeger is not yet installed so traces have nowhere to go (yet), -but creating this configuration now means the system is preconfigured. - -Save this file as `collectorconfig.yaml`. -It doesn't matter where this file is located on your local machine: - -```yaml ---- -apiVersion: options.keptn.sh/v1alpha1 -kind: KeptnConfig -metadata: - name: keptnconfig-sample - namespace: keptn-lifecycle-toolkit-system -spec: - OTelCollectorUrl: 'jaeger-collector.keptn-lifecycle-toolkit-system.svc.cluster.local:4317' - keptnAppCreationRequestTimeoutSeconds: 30 -``` - -Apply the file and restart Keptn to pick up the new config: - -```shell -kubectl apply -f collectorconfig.yaml -``` - -## Step 2: Create Namespace for Demo Application - -Save this file as `namespace.yaml`. -The annotation means that Keptn is active for workloads in this namespace. - -```yaml -apiVersion: v1 -kind: Namespace -metadata: - name: keptndemo - annotations: - keptn.sh/lifecycle-toolkit: enabled -``` - -Create the namespace: - -```shell -kubectl apply -f namespace.yaml -``` - -## Step 3: Deploy Demo Application - -It is time to deploy the demo application. - -Save this manifest as `app.yaml`: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-deployment - namespace: keptndemo - labels: - app.kubernetes.io/name: nginx -spec: - replicas: 1 - selector: - matchLabels: - app.kubernetes.io/name: nginx - template: - metadata: - labels: - app.kubernetes.io/part-of: keptndemoapp - app.kubernetes.io/name: nginx - app.kubernetes.io/version: 0.0.1 - spec: - containers: - - name: nginx - image: nginx:1.14.2 - ports: - - containerPort: 80 ---- -apiVersion: apps/v1 -kind: Service -apiVersion: v1 -kind: Service -metadata: - name: nginx - namespace: keptndemo -spec: - selector: - app.kubernetes.io/name: nginx - ports: - - protocol: TCP - port: 8080 - targetPort: 80 -``` - -Now apply it: - -```shell -kubectl apply -f app.yaml -``` - -Keptn looks for these 3 labels: - -- `app.kubernetes.io/part-of` -- `app.kubernetes.io/name` -- `app.kubernetes.io/version` - -These are [Kubernetes recommended labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/#labels) -but if you want to use different labels, you can swap them for these Keptn specific labels: - -- `keptn.sh/app` instead of `app.kubernetes.io/part-of` -- `keptn.sh/workload` instead of `app.kubernetes.io/name` -- `keptn.sh/version` instead of `app.kubernetes.io/version` - -## Step 4: Explore Keptn - -Keptn is now aware of your deployments and is generating DORA statistics about them. - -Keptn has created a resource called a `KeptnApp` to track your application. -The name of which is based on the `part-of` label. - -It may take up to 30 seconds to create the `KeptnApp` so run the following command until you see the `keptnappdemo` CRD. - -```shell -kubectl -n keptndemo get keptnapp -``` - -Expected output: - -```shell -NAME AGE -keptndemoapp 2s -``` - -Keptn also creates a new application version every time you increment the `version` label. - -The `PHASE` will change as the deployment progresses. -A successful deployment is shown as `PHASE=Completed` - -```shell -kubectl -n keptndemo get keptnappversion -``` - -Expected output: - -```shell -NAME APPNAME VERSION PHASE -keptndemoapp-0.0.1-*** keptndemoapp 0.0.1 Completed -``` - -Keptn can run tasks and SLO (Service Level Objective) evaluations before and after deployment. -You haven't configured this yet, but you can see the full lifecycle for a `keptnappversion` by running: - -```shell -kubectl -n keptndemo get keptnappversion -o wide -``` - -Keptn applications are a collection of workloads. -By default, Keptn will build `KeptnApp` resources based on the labels you provide. - -In the example above, the `KeptnApp` called `keptndemoapp` contains one `KeptnWorkload` -(based on the `app.kubernetes.io/name` label): - -## Step 5: View your application - -Port-forward to expose your app on `http://localhost:8080`: - -```shell -kubectl -n keptndemo port-forward svc/nginx 8080 -``` - -Open a browser window and go to `http://localhost:8080` - -You should see the "Welcome to nginx" page. - -![nginx demo app](assets/nginx.png) - -## Step 6: View DORA Metrics - -Keptn is generating DORA metrics and OpenTelemetry traces for your deployments. - -These metrics are exposed via the Keptn lifecycle operator `/metrics` endpoint on port `2222`. - -To see these raw metrics: - -- Port forward to the lifecycle operator metrics service: - -```shell -SERVICE=$(kubectl get svc -l control-plane=lifecycle-operator -A -ojsonpath="{.items[0].metadata.name}") -kubectl -n keptn-lifecycle-toolkit-system port-forward svc/$SERVICE 2222 -``` - -Note that this command will (and should) continue to run in your terminal windows. -Open a new terminal window to continue. - -- Access metrics in Prometheus format on `http://localhost:2222/metrics` -- Look for metrics starting with `keptn_` - -![keptn prometheus metrics](assets/keptnprommetrics.png) - -Keptn emits various metrics about the state of your system. -These metrics can then be visualised in Grafana. - -For example: - -- `keptn_app_active` tracks the number of applications that Keptn manages -- `keptn_deployment_active` tracks the currently live number of deployments occurring. - Expect this metric to be `0` when everything is currently deployed. - It will occasionally rise to `n` during deployments and then fall back to `0` when deployments are completed. - -There are many other Keptn metrics. - -## Step 7: Make DORA metrics more user friendly - -It is much more user-friendly to provide dashboards for metrics, logs and traces. -So let's install new Observability components to help us: - -- [Cert manager](https://cert-manager.io): Jaeger requires cert-manager -- [Jaeger](https://jaegertracing.io): Store and view DORA deployment traces -- [Prometheus](https://prometheus.io): Store DORA metrics -- [OpenTelemetry collector](https://opentelemetry.io/docs/collector/): - Scrape metrics from the above DORA metrics endpoint & forward to Prometheus -- [Grafana](https://grafana.com) (and some prebuilt dashboards): Visualise the data - -![add observability](assets/install01.png) - -## Step 8: Install Cert Manager - -Jaeger requires Cert Manager, so install it now: - -```shell -kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.2/cert-manager.crds.yaml -helm repo add jetstack https://charts.jetstack.io -helm repo update -helm install cert-manager --namespace cert-manager --version v1.12.2 jetstack/cert-manager --create-namespace --wait -``` - -## Step 9: Install Jaeger - -Save this file as `jaeger.yaml` (it can be saved anywhere on your computer): - -```yaml -apiVersion: jaegertracing.io/v1 -kind: Jaeger -metadata: - name: jaeger -spec: - strategy: allInOne -``` - -Install Jaeger to store and visualise the deployment traces generated by Keptn: - -```shell -kubectl create namespace observability -kubectl apply -f https://github.com/jaegertracing/jaeger-operator/releases/download/v1.46.0/jaeger-operator.yaml -n observability -kubectl wait --for=condition=available deployment/jaeger-operator -n observability --timeout=300s -kubectl apply -f jaeger.yaml -n keptn-lifecycle-toolkit-system -kubectl wait --for=condition=available deployment/jaeger -n keptn-lifecycle-toolkit-system --timeout=300s -``` - -Port-forward to access Jaeger: - -```shell -kubectl -n keptn-lifecycle-toolkit-system port-forward svc/jaeger-query 16686 -``` - -Jaeger is available on `http://localhost:16686` - -## Step 10: Install Grafana dashboards - -Create some Keptn Grafana dashboards that will be available when Grafana is installed and started: - - -```shell -kubectl create ns monitoring -kubectl apply -f https://raw.githubusercontent.com/keptn/lifecycle-toolkit/klt-v0.8.2/examples/support/observability/config/prometheus/grafana-config.yaml -kubectl apply -f https://raw.githubusercontent.com/keptn/lifecycle-toolkit/klt-v0.8.2/examples/support/observability/config/prometheus/grafana-dashboard-keptn-applications.yaml -kubectl apply -f https://raw.githubusercontent.com/keptn/lifecycle-toolkit/klt-v0.8.2/examples/support/observability/config/prometheus/grafana-dashboard-keptn-overview.yaml -kubectl apply -f https://raw.githubusercontent.com/keptn/lifecycle-toolkit/klt-v0.8.2/examples/support/observability/config/prometheus/grafana-dashboard-keptn-workloads.yaml -``` - - -### Install Grafana datasources - -This file will configure Grafana to look at the Jaeger service and the Prometheus service on the cluster. - -Save this file as `datasources.yaml`: - -```yaml -apiVersion: v1 -kind: Secret -type: Opaque -metadata: - labels: - grafana_datasource: "1" - name: grafana-datasources - namespace: monitoring -stringData: - datasources.yaml: |- - { - "apiVersion": 1, - "datasources": [ - { - "access": "proxy", - "editable": false, - "name": "prometheus", - "orgId": 1, - "type": "prometheus", - "url": "http://observability-stack-kube-p-prometheus.monitoring.svc:9090", - "version": 1 - }, - { - "orgId":1, - "name":"Jaeger", - "type":"jaeger", - "typeName":"Jaeger", - "typeLogoUrl":"public/app/plugins/datasource/jaeger/img/jaeger_logo.svg", - "access":"proxy", - "url":"http://jaeger-query.keptn-lifecycle-toolkit-system.svc.cluster.local:16686", - "user":"", - "database":"", - "basicAuth":false, - "isDefault":false, - "jsonData":{"spanBar":{"type":"None"}}, - "readOnly":false - } - ] - } -``` - -Now apply it: - -```shell -kubectl apply -f datasources.yaml -``` - -## Step 11: Install kube prometheus stack - -This will install: - -- Prometheus -- Prometheus Configuration -- Grafana & default dashboards - -Save this file as `values.yaml`: - -```yaml -grafana: - adminPassword: admin - sidecar.datasources.defaultDatasourceEnabled: false -prometheus: - prometheusSpec: - additionalScrapeConfigs: - - job_name: "scrape_klt" - scrape_interval: 5s - static_configs: - - targets: ['lifecycle-operator-metrics-service.keptn-lifecycle-toolkit-system.svc.cluster.local:2222'] -``` - -```shell -helm repo add prometheus-community https://prometheus-community.github.io/helm-charts -helm repo update -helm upgrade --install observability-stack prometheus-community/kube-prometheus-stack --version 48.1.1 --namespace monitoring --values=values.yaml --wait -``` - -## Step 12: Access Grafana - -```shell -kubectl -n monitoring port-forward svc/observability-stack-grafana 80 -``` - -- Grafana username: `admin` -- Grafana password: `admin` - -View the Keptn dashboards at: `http://localhost/dashboards` - -Remember that Jaeger and Grafana weren't installed during the first deployment -so expect the dashboards to look a little empty. - -## Step 13: Deploy v0.0.2 and populate Grafana - -By triggering a new deployment, Keptn will track this deployment and the Grafana dashboards will actually have data. - -Modify your `app.yaml` and change the `app.kubernetes.io/version` from `0.0.1` to `0.0.2` -(or `keptn.sh/version` if you used the Keptn specific labels earlier). - -Apply your update: - -```shell -kubectl apply -f app.yaml -``` - -After about 30 seconds you should now see two `keptnappversions`: - -```shell -kubectl -n keptndemo get keptnappversion -``` - -Expected output: - -```shell -NAME APPNAME VERSION PHASE -keptndemoapp-0.0.1-*** keptndemoapp 0.0.1 Completed -keptndemoapp-0.0.2-*** keptndemoapp 0.0.2 AppDeploy -``` - -Wait until the `PHASE` of `keptndemoapp-0.0.2` is `Completed`. -This signals that the deployment was successful and the pod is running. - -View the Keptn Applications Dashboard and you should see the DORA metrics and an OpenTelemetry trace: - -![keptn applications dashboard](assets/keptnapplications.png) - -![deployment trace](assets/deploymenttrace.png) - -## Step 14: More control over KeptnApp - -To customize workloads and checks associated with the application, we can edit the autogenerated KeptnApp or create our own. - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha3 -kind: KeptnApp -metadata: - name: - namespace: -spec: - version: "x.y" - revision: x - workloads: - - name: - version: - - name: - version: - preDeploymentTasks: - - - postDeploymentTasks: - - - preDeploymentEvaluations: - - - postDeploymentEvaluations: - - -``` - -## Fields - -- **apiVersion** -- API version being used. -- **kind** -- Resource type. - Must be set to `KeptnApp` - -- **metadata** - - **name** -- Unique name of this application. - Names must comply with the - [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) - specification. - -- **spec** - - **version** -- version of the Keptn application. - Changing this version number causes a new execution - of all application-level checks - - **revision** -- revision of a `version`. - The value is an integer that can be modified - to trigger another deployment of a `KeptnApp` of the same version. - For example, increment this number to restart a `KeptnApp` version - that failed to deploy, perhaps because a - `preDeploymentEvaluation` or `preDeploymentTask` failed. - See - [Restart an Application Deployment](../implementing/restart-application-deployment/) - for a longer discussion of this. - - **workloads** - - **name** - name of this Kubernetes - [workload](https://kubernetes.io/docs/concepts/workloads/). - Use the same naming rules listed above for the application name. - Provide one entry for each workload - associated with this Keptn application. - - **version** -- version number for this workload. - Changing this number causes a new execution - of checks for this workload only, - not the entire application. - -The remaining fields are required only when implementing -the release lifecycle management feature. -If used, these fields must be populated manually: - -- **preDeploymentTasks** -- list each task - to be run as part of the pre-deployment stage. - Task names must match the value of the `metadata.name` field - for the associated [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) resource. -- **postDeploymentTasks** -- list each task - to be run as part of the post-deployment stage. - Task names must match the value of the `metadata.name` field - for the associated - [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) - resource. -- **preDeploymentEvaluations** -- list each evaluation to be run - as part of the pre-deployment stage. - Evaluation names must match the value of the `metadata.name` field - for the associated - [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) - resource. -- **postDeploymentEvaluations** -- list each evaluation to be run - as part of the post-deployment stage. - Evaluation names must match the value of the `metadata.name` field - for the associated [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) - resource. - -## Example - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha3 -kind: KeptnApp -metadata: - name: podtato-head - namespace: podtato-kubectl -spec: - version: "latest" - workloads: - - name: podtato-head-left-arm - version: "my_vers12.5" - - name: podtato-head-left-leg - version: "my_v24" - postDeploymentTasks: - - post-deployment-hello - preDeploymentEvaluations: - - my-prometheus-definition -``` - -You may have noticed that the `KeptnApp` Custom Resources are created automatically by Keptn. - -However, you can override this automatic behaviour by creating a custom `KeptnApp` CRD. -In this way, you are in full control of what constitutes a Keptn Application. -See [KeptnApp Reference page](../yaml-crd-ref/app.md) for more information. - -## What's next? - -Keptn can run pre and post deployment tasks and SLO evaluations automatically. - -Continue the Keptn learning journey by [adding deployment tasks](../implementing/tasks). diff --git a/docs/content/en/docs/tutorials/assets/webhook.site.1.png b/docs/content/en/docs/getting-started/assets/webhook.site.1.png similarity index 100% rename from docs/content/en/docs/tutorials/assets/webhook.site.1.png rename to docs/content/en/docs/getting-started/assets/webhook.site.1.png diff --git a/docs/content/en/docs/tutorials/assets/webhook.site.2.png b/docs/content/en/docs/getting-started/assets/webhook.site.2.png similarity index 100% rename from docs/content/en/docs/tutorials/assets/webhook.site.2.png rename to docs/content/en/docs/getting-started/assets/webhook.site.2.png diff --git a/docs/content/en/docs/tutorials/assets/webhook.site.3.png b/docs/content/en/docs/getting-started/assets/webhook.site.3.png similarity index 100% rename from docs/content/en/docs/tutorials/assets/webhook.site.3.png rename to docs/content/en/docs/getting-started/assets/webhook.site.3.png diff --git a/docs/content/en/docs/getting-started/observability/_index.md b/docs/content/en/docs/getting-started/observability/_index.md new file mode 100644 index 0000000000..91acb83755 --- /dev/null +++ b/docs/content/en/docs/getting-started/observability/_index.md @@ -0,0 +1,594 @@ +--- +title: Keptn Observability +description: Get started with the Keptn Observability feature +weight: 40 +--- + +Keptn provides sophisticated observability features +that enhance your existing cloud-native deployment environment. +These features are useful whether or not you use a GitOps strategy. + +The following is an imperative walkthrough. + +## Prerequisites + +- [Docker](https://docs.docker.com/get-started/overview/) +- [kubectl](https://kubernetes.io/docs/reference/kubectl/) +- [Helm](https://helm.sh/docs/intro/install/) +- A Kubernetes cluster >= 1.24 (we recommend [Kubernetes kind](https://kind.sigs.k8s.io/docs/user/quick-start/)) + (`kind create cluster`) + +## Objectives + +- Install Keptn on your cluster +- Annotate a namespace and deployment to enable Keptn +- Install Grafana and Observability tooling to view DORA metrics and OpenTelemetry traces + +## System Overview + +By the end of this page, here is what will be built. +The system will be built in stages. + +![system overview](assets/install01.png) + +## The Basics: A Deployment, Keptn and DORA Metrics + +To begin our exploration of the Keptn observability features, we will: + +- Deploy a simple application called `keptndemo`. + +Keptn will monitor the deployment and generate: + +- An OpenTelemetry trace per deployment +- DORA metrics + +![the basics](assets/install02.png) + +Notice though that the metrics and traces have nowhere to go. +That will be fixed in a subsequent step. + +## Step 1: Install Keptn + +Install Keptn using Helm: + +```shell +helm repo add klt https://charts.lifecycle.keptn.sh +helm repo update +helm upgrade --install keptn klt/klt -n keptn-lifecycle-toolkit-system --create-namespace --wait +``` + +Keptn will need to know where to send OpenTelemetry traces. +Of course, Jaeger is not yet installed so traces have nowhere to go (yet), +but creating this configuration now means the system is preconfigured. + +Save this file as `collectorconfig.yaml`. +It doesn't matter where this file is located on your local machine: + +```yaml +--- +apiVersion: options.keptn.sh/v1alpha1 +kind: KeptnConfig +metadata: + name: keptnconfig-sample + namespace: keptn-lifecycle-toolkit-system +spec: + OTelCollectorUrl: 'jaeger-collector.keptn-lifecycle-toolkit-system.svc.cluster.local:4317' + keptnAppCreationRequestTimeoutSeconds: 30 +``` + +Apply the file and restart Keptn to pick up the new config: + +```shell +kubectl apply -f collectorconfig.yaml +``` + +## Step 2: Create Namespace for Demo Application + +Save this file as `namespace.yaml`. +The annotation means that Keptn is active for workloads in this namespace. + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: keptndemo + annotations: + keptn.sh/lifecycle-toolkit: enabled +``` + +Create the namespace: + +```shell +kubectl apply -f namespace.yaml +``` + +## Step 3: Deploy Demo Application + +It is time to deploy the demo application. + +Save this manifest as `app.yaml`: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-deployment + namespace: keptndemo + labels: + app.kubernetes.io/name: nginx +spec: + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/name: nginx + template: + metadata: + labels: + app.kubernetes.io/part-of: keptndemoapp + app.kubernetes.io/name: nginx + app.kubernetes.io/version: 0.0.1 + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - containerPort: 80 +--- +apiVersion: apps/v1 +kind: Service +apiVersion: v1 +kind: Service +metadata: + name: nginx + namespace: keptndemo +spec: + selector: + app.kubernetes.io/name: nginx + ports: + - protocol: TCP + port: 8080 + targetPort: 80 +``` + +Now apply it: + +```shell +kubectl apply -f app.yaml +``` + +Keptn looks for these 3 labels: + +- `app.kubernetes.io/part-of` +- `app.kubernetes.io/name` +- `app.kubernetes.io/version` + +These are [Kubernetes recommended labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/#labels) +but if you want to use different labels, you can swap them for these Keptn specific labels: + +- `keptn.sh/app` instead of `app.kubernetes.io/part-of` +- `keptn.sh/workload` instead of `app.kubernetes.io/name` +- `keptn.sh/version` instead of `app.kubernetes.io/version` + +## Step 4: Explore Keptn + +Keptn is now aware of your deployments and is generating DORA statistics about them. + +Keptn has created a resource called a `KeptnApp` to track your application. +The name of which is based on the `part-of` label. + +It may take up to 30 seconds to create the `KeptnApp` so run the following command until you see the `keptnappdemo` CRD. + +```shell +kubectl -n keptndemo get keptnapp +``` + +Expected output: + +```shell +NAME AGE +keptndemoapp 2s +``` + +Keptn also creates a new application version every time you increment the `version` label. + +The `PHASE` will change as the deployment progresses. +A successful deployment is shown as `PHASE=Completed` + +```shell +kubectl -n keptndemo get keptnappversion +``` + +Expected output: + +```shell +NAME APPNAME VERSION PHASE +keptndemoapp-0.0.1-*** keptndemoapp 0.0.1 Completed +``` + +Keptn can run tasks and SLO (Service Level Objective) evaluations before and after deployment. +You haven't configured this yet, but you can see the full lifecycle for a `keptnappversion` by running: + +```shell +kubectl -n keptndemo get keptnappversion -o wide +``` + +Keptn applications are a collection of workloads. +By default, Keptn will build `KeptnApp` resources based on the labels you provide. + +In the example above, the `KeptnApp` called `keptndemoapp` contains one `KeptnWorkload` +(based on the `app.kubernetes.io/name` label): + +## Step 5: View your application + +Port-forward to expose your app on `http://localhost:8080`: + +```shell +kubectl -n keptndemo port-forward svc/nginx 8080 +``` + +Open a browser window and go to `http://localhost:8080` + +You should see the "Welcome to nginx" page. + +![nginx demo app](assets/nginx.png) + +## Step 6: View DORA Metrics + +Keptn is generating DORA metrics and OpenTelemetry traces for your deployments. + +These metrics are exposed via the Keptn lifecycle operator `/metrics` endpoint on port `2222`. + +To see these raw metrics: + +- Port forward to the lifecycle operator metrics service: + +```shell +SERVICE=$(kubectl get svc -l control-plane=lifecycle-operator -A -ojsonpath="{.items[0].metadata.name}") +kubectl -n keptn-lifecycle-toolkit-system port-forward svc/$SERVICE 2222 +``` + +Note that this command will (and should) continue to run in your terminal windows. +Open a new terminal window to continue. + +- Access metrics in Prometheus format on `http://localhost:2222/metrics` +- Look for metrics starting with `keptn_` + +![keptn prometheus metrics](assets/keptnprommetrics.png) + +Keptn emits various metrics about the state of your system. +These metrics can then be visualised in Grafana. + +For example: + +- `keptn_app_active` tracks the number of applications that Keptn manages +- `keptn_deployment_active` tracks the currently live number of deployments occurring. + Expect this metric to be `0` when everything is currently deployed. + It will occasionally rise to `n` during deployments and then fall back to `0` when deployments are completed. + +There are many other Keptn metrics. + +## Step 7: Make DORA metrics more user friendly + +It is much more user-friendly to provide dashboards for metrics, logs and traces. +So let's install new Observability components to help us: + +- [Cert manager](https://cert-manager.io): Jaeger requires cert-manager +- [Jaeger](https://jaegertracing.io): Store and view DORA deployment traces +- [Prometheus](https://prometheus.io): Store DORA metrics +- [OpenTelemetry collector](https://opentelemetry.io/docs/collector/): + Scrape metrics from the above DORA metrics endpoint & forward to Prometheus +- [Grafana](https://grafana.com) (and some prebuilt dashboards): Visualise the data + +![add observability](assets/install01.png) + +## Step 8: Install Cert Manager + +Jaeger requires Cert Manager, so install it now: + +```shell +kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.2/cert-manager.crds.yaml +helm repo add jetstack https://charts.jetstack.io +helm repo update +helm install cert-manager --namespace cert-manager --version v1.12.2 jetstack/cert-manager --create-namespace --wait +``` + +## Step 9: Install Jaeger + +Save this file as `jaeger.yaml` (it can be saved anywhere on your computer): + +```yaml +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: jaeger +spec: + strategy: allInOne +``` + +Install Jaeger to store and visualise the deployment traces generated by Keptn: + +```shell +kubectl create namespace observability +kubectl apply -f https://github.com/jaegertracing/jaeger-operator/releases/download/v1.46.0/jaeger-operator.yaml -n observability +kubectl wait --for=condition=available deployment/jaeger-operator -n observability --timeout=300s +kubectl apply -f jaeger.yaml -n keptn-lifecycle-toolkit-system +kubectl wait --for=condition=available deployment/jaeger -n keptn-lifecycle-toolkit-system --timeout=300s +``` + +Port-forward to access Jaeger: + +```shell +kubectl -n keptn-lifecycle-toolkit-system port-forward svc/jaeger-query 16686 +``` + +Jaeger is available on `http://localhost:16686` + +## Step 10: Install Grafana dashboards + +Create some Keptn Grafana dashboards that will be available when Grafana is installed and started: + + +```shell +kubectl create ns monitoring +kubectl apply -f https://raw.githubusercontent.com/keptn/lifecycle-toolkit/klt-v0.8.2/examples/support/observability/config/prometheus/grafana-config.yaml +kubectl apply -f https://raw.githubusercontent.com/keptn/lifecycle-toolkit/klt-v0.8.2/examples/support/observability/config/prometheus/grafana-dashboard-keptn-applications.yaml +kubectl apply -f https://raw.githubusercontent.com/keptn/lifecycle-toolkit/klt-v0.8.2/examples/support/observability/config/prometheus/grafana-dashboard-keptn-overview.yaml +kubectl apply -f https://raw.githubusercontent.com/keptn/lifecycle-toolkit/klt-v0.8.2/examples/support/observability/config/prometheus/grafana-dashboard-keptn-workloads.yaml +``` + + +### Install Grafana datasources + +This file will configure Grafana to look at the Jaeger service and the Prometheus service on the cluster. + +Save this file as `datasources.yaml`: + +```yaml +apiVersion: v1 +kind: Secret +type: Opaque +metadata: + labels: + grafana_datasource: "1" + name: grafana-datasources + namespace: monitoring +stringData: + datasources.yaml: |- + { + "apiVersion": 1, + "datasources": [ + { + "access": "proxy", + "editable": false, + "name": "prometheus", + "orgId": 1, + "type": "prometheus", + "url": "http://observability-stack-kube-p-prometheus.monitoring.svc:9090", + "version": 1 + }, + { + "orgId":1, + "name":"Jaeger", + "type":"jaeger", + "typeName":"Jaeger", + "typeLogoUrl":"public/app/plugins/datasource/jaeger/img/jaeger_logo.svg", + "access":"proxy", + "url":"http://jaeger-query.keptn-lifecycle-toolkit-system.svc.cluster.local:16686", + "user":"", + "database":"", + "basicAuth":false, + "isDefault":false, + "jsonData":{"spanBar":{"type":"None"}}, + "readOnly":false + } + ] + } +``` + +Now apply it: + +```shell +kubectl apply -f datasources.yaml +``` + +## Step 11: Install kube prometheus stack + +This will install: + +- Prometheus +- Prometheus Configuration +- Grafana & default dashboards + +Save this file as `values.yaml`: + +```yaml +grafana: + adminPassword: admin + sidecar.datasources.defaultDatasourceEnabled: false +prometheus: + prometheusSpec: + additionalScrapeConfigs: + - job_name: "scrape_klt" + scrape_interval: 5s + static_configs: + - targets: ['lifecycle-operator-metrics-service.keptn-lifecycle-toolkit-system.svc.cluster.local:2222'] +``` + +```shell +helm repo add prometheus-community https://prometheus-community.github.io/helm-charts +helm repo update +helm upgrade --install observability-stack prometheus-community/kube-prometheus-stack --version 48.1.1 --namespace monitoring --values=values.yaml --wait +``` + +## Step 12: Access Grafana + +```shell +kubectl -n monitoring port-forward svc/observability-stack-grafana 80 +``` + +- Grafana username: `admin` +- Grafana password: `admin` + +View the Keptn dashboards at: `http://localhost/dashboards` + +Remember that Jaeger and Grafana weren't installed during the first deployment +so expect the dashboards to look a little empty. + +## Step 13: Deploy v0.0.2 and populate Grafana + +By triggering a new deployment, Keptn will track this deployment and the Grafana dashboards will actually have data. + +Modify your `app.yaml` and change the `app.kubernetes.io/version` from `0.0.1` to `0.0.2` +(or `keptn.sh/version` if you used the Keptn specific labels earlier). + +Apply your update: + +```shell +kubectl apply -f app.yaml +``` + +After about 30 seconds you should now see two `keptnappversions`: + +```shell +kubectl -n keptndemo get keptnappversion +``` + +Expected output: + +```shell +NAME APPNAME VERSION PHASE +keptndemoapp-0.0.1-*** keptndemoapp 0.0.1 Completed +keptndemoapp-0.0.2-*** keptndemoapp 0.0.2 AppDeploy +``` + +Wait until the `PHASE` of `keptndemoapp-0.0.2` is `Completed`. +This signals that the deployment was successful and the pod is running. + +View the Keptn Applications Dashboard and you should see the DORA metrics and an OpenTelemetry trace: + +![keptn applications dashboard](assets/keptnapplications.png) + +![deployment trace](assets/deploymenttrace.png) + +## Step 14: More control over KeptnApp + +To customize workloads and checks associated with the application, we can edit the autogenerated KeptnApp or create our own. + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnApp +metadata: + name: + namespace: +spec: + version: "x.y" + revision: x + workloads: + - name: + version: + - name: + version: + preDeploymentTasks: + - + postDeploymentTasks: + - + preDeploymentEvaluations: + - + postDeploymentEvaluations: + - +``` + +## Fields + +- **apiVersion** -- API version being used. +- **kind** -- Resource type. + Must be set to `KeptnApp` + +- **metadata** + - **name** -- Unique name of this application. + Names must comply with the + [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) + specification. + +- **spec** + - **version** -- version of the Keptn application. + Changing this version number causes a new execution + of all application-level checks + - **revision** -- revision of a `version`. + The value is an integer that can be modified + to trigger another deployment of a `KeptnApp` of the same version. + For example, increment this number to restart a `KeptnApp` version + that failed to deploy, perhaps because a + `preDeploymentEvaluation` or `preDeploymentTask` failed. + See + [Restart an Application Deployment](../implementing/restart-application-deployment/) + for a longer discussion of this. + - **workloads** + - **name** - name of this Kubernetes + [workload](https://kubernetes.io/docs/concepts/workloads/). + Use the same naming rules listed above for the application name. + Provide one entry for each workload + associated with this Keptn application. + - **version** -- version number for this workload. + Changing this number causes a new execution + of checks for this workload only, + not the entire application. + +The remaining fields are required only when implementing +the release lifecycle management feature. +If used, these fields must be populated manually: + +- **preDeploymentTasks** -- list each task + to be run as part of the pre-deployment stage. + Task names must match the value of the `metadata.name` field + for the associated [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) resource. +- **postDeploymentTasks** -- list each task + to be run as part of the post-deployment stage. + Task names must match the value of the `metadata.name` field + for the associated + [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) + resource. +- **preDeploymentEvaluations** -- list each evaluation to be run + as part of the pre-deployment stage. + Evaluation names must match the value of the `metadata.name` field + for the associated + [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) + resource. +- **postDeploymentEvaluations** -- list each evaluation to be run + as part of the post-deployment stage. + Evaluation names must match the value of the `metadata.name` field + for the associated [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) + resource. + +## Example + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnApp +metadata: + name: podtato-head + namespace: podtato-kubectl +spec: + version: "latest" + workloads: + - name: podtato-head-left-arm + version: "my_vers12.5" + - name: podtato-head-left-leg + version: "my_v24" + postDeploymentTasks: + - post-deployment-hello + preDeploymentEvaluations: + - my-prometheus-definition +``` + +You may have noticed that the `KeptnApp` Custom Resources are created automatically by Keptn. + +However, you can override this automatic behaviour by creating a custom `KeptnApp` CRD. +In this way, you are in full control of what constitutes a Keptn Application. +See [KeptnApp Reference page](../yaml-crd-ref/app.md) for more information. + +## What's next? + +Keptn can run pre and post deployment tasks and SLO evaluations automatically. + +Continue the Keptn learning journey by [adding deployment tasks](../implementing/tasks). diff --git a/docs/content/en/docs/getting-started/assets/deploymenttrace.png b/docs/content/en/docs/getting-started/observability/assets/deploymenttrace.png similarity index 100% rename from docs/content/en/docs/getting-started/assets/deploymenttrace.png rename to docs/content/en/docs/getting-started/observability/assets/deploymenttrace.png diff --git a/docs/content/en/docs/getting-started/assets/grafana.png b/docs/content/en/docs/getting-started/observability/assets/grafana.png similarity index 100% rename from docs/content/en/docs/getting-started/assets/grafana.png rename to docs/content/en/docs/getting-started/observability/assets/grafana.png diff --git a/docs/content/en/docs/getting-started/assets/install01.png b/docs/content/en/docs/getting-started/observability/assets/install01.png similarity index 100% rename from docs/content/en/docs/getting-started/assets/install01.png rename to docs/content/en/docs/getting-started/observability/assets/install01.png diff --git a/docs/content/en/docs/getting-started/assets/install02.png b/docs/content/en/docs/getting-started/observability/assets/install02.png similarity index 100% rename from docs/content/en/docs/getting-started/assets/install02.png rename to docs/content/en/docs/getting-started/observability/assets/install02.png diff --git a/docs/content/en/docs/getting-started/assets/keptnapplications.png b/docs/content/en/docs/getting-started/observability/assets/keptnapplications.png similarity index 100% rename from docs/content/en/docs/getting-started/assets/keptnapplications.png rename to docs/content/en/docs/getting-started/observability/assets/keptnapplications.png diff --git a/docs/content/en/docs/getting-started/assets/keptnprommetrics.png b/docs/content/en/docs/getting-started/observability/assets/keptnprommetrics.png similarity index 100% rename from docs/content/en/docs/getting-started/assets/keptnprommetrics.png rename to docs/content/en/docs/getting-started/observability/assets/keptnprommetrics.png diff --git a/docs/content/en/docs/getting-started/assets/nginx.png b/docs/content/en/docs/getting-started/observability/assets/nginx.png similarity index 100% rename from docs/content/en/docs/getting-started/assets/nginx.png rename to docs/content/en/docs/getting-started/observability/assets/nginx.png diff --git a/docs/content/en/docs/getting-started/assets/podtatohead.png b/docs/content/en/docs/getting-started/observability/assets/podtatohead.png similarity index 100% rename from docs/content/en/docs/getting-started/assets/podtatohead.png rename to docs/content/en/docs/getting-started/observability/assets/podtatohead.png diff --git a/docs/content/en/docs/getting-started/assets/trace-failed.png b/docs/content/en/docs/getting-started/observability/assets/trace-failed.png similarity index 100% rename from docs/content/en/docs/getting-started/assets/trace-failed.png rename to docs/content/en/docs/getting-started/observability/assets/trace-failed.png diff --git a/docs/content/en/docs/tutorials/tasks/_index.md b/docs/content/en/docs/getting-started/tasks/_index.md similarity index 97% rename from docs/content/en/docs/tutorials/tasks/_index.md rename to docs/content/en/docs/getting-started/tasks/_index.md index ac2c01d092..298ed8764e 100644 --- a/docs/content/en/docs/tutorials/tasks/_index.md +++ b/docs/content/en/docs/getting-started/tasks/_index.md @@ -1,8 +1,7 @@ --- -title: Getting started with Release Lifecycle Management +title: Release Lifecycle Management description: Add KeptnTasks to deployments -weight: 25 -hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html +weight: 50 --- The Release Lifecycle Management tools run diff --git a/docs/content/en/docs/intro/usecase_metrics.md b/docs/content/en/docs/getting-started/usecase_metrics.md similarity index 98% rename from docs/content/en/docs/intro/usecase_metrics.md rename to docs/content/en/docs/getting-started/usecase_metrics.md index 6c8a8815ae..0453e4629b 100644 --- a/docs/content/en/docs/intro/usecase_metrics.md +++ b/docs/content/en/docs/getting-started/usecase_metrics.md @@ -1,10 +1,10 @@ --- -title: Custom Keptn metrics +title: Keptn metrics description: Enhance your deployment with custom Keptn metrics weight: 30 --- -The Custom Keptn metrics component +The Keptn metrics component allows you to define any type of metric from multiple instances of any type of data source in your Kubernetes cluster. @@ -29,7 +29,7 @@ Each has plugins but it is difficult to maintain them, especially if you are using multiple tools, and multiple observability platforms, and multiple instances of some tools or observability platforms. -The Custom Keptn metrics feature unites all these metrics +The Keptn metrics feature unites all these metrics integrates metrics from all these sources into a single set of metrics. ## Using this exercise From 4aa6bd78e7b8e9c68446c672f66a819e2f9c5d71 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 18 Oct 2023 15:51:01 -0700 Subject: [PATCH 2/8] fix xrefs Signed-off-by: Meg McRoberts --- .../en/docs/getting-started/observability/_index.md | 12 ++++++------ docs/content/en/docs/getting-started/tasks/_index.md | 3 ++- .../en/docs/getting-started/usecase_metrics.md | 4 ++-- docs/content/en/docs/implementing/evaluatemetrics.md | 2 +- docs/content/en/docs/intro/_index.md | 6 +++--- docs/content/en/docs/intro/usecase-orchestrate.md | 2 +- docs/content/en/docs/yaml-crd-ref/metric.md | 2 +- 7 files changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/content/en/docs/getting-started/observability/_index.md b/docs/content/en/docs/getting-started/observability/_index.md index 91acb83755..e396863710 100644 --- a/docs/content/en/docs/getting-started/observability/_index.md +++ b/docs/content/en/docs/getting-started/observability/_index.md @@ -521,7 +521,7 @@ spec: that failed to deploy, perhaps because a `preDeploymentEvaluation` or `preDeploymentTask` failed. See - [Restart an Application Deployment](../implementing/restart-application-deployment/) + [Restart an Application Deployment](../../implementing/restart-application-deployment/) for a longer discussion of this. - **workloads** - **name** - name of this Kubernetes @@ -541,23 +541,23 @@ If used, these fields must be populated manually: - **preDeploymentTasks** -- list each task to be run as part of the pre-deployment stage. Task names must match the value of the `metadata.name` field - for the associated [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) resource. + for the associated [KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md) resource. - **postDeploymentTasks** -- list each task to be run as part of the post-deployment stage. Task names must match the value of the `metadata.name` field for the associated - [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) + [KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md) resource. - **preDeploymentEvaluations** -- list each evaluation to be run as part of the pre-deployment stage. Evaluation names must match the value of the `metadata.name` field for the associated - [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) + [KeptnEvaluationDefinition](../../yaml-crd-ref/evaluationdefinition.md) resource. - **postDeploymentEvaluations** -- list each evaluation to be run as part of the post-deployment stage. Evaluation names must match the value of the `metadata.name` field - for the associated [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md) + for the associated [KeptnEvaluationDefinition](../../yaml-crd-ref/evaluationdefinition.md) resource. ## Example @@ -591,4 +591,4 @@ See [KeptnApp Reference page](../yaml-crd-ref/app.md) for more information. Keptn can run pre and post deployment tasks and SLO evaluations automatically. -Continue the Keptn learning journey by [adding deployment tasks](../implementing/tasks). +Continue the Keptn learning journey by [adding deployment tasks](../../implementing/tasks). diff --git a/docs/content/en/docs/getting-started/tasks/_index.md b/docs/content/en/docs/getting-started/tasks/_index.md index 298ed8764e..7e1293b218 100644 --- a/docs/content/en/docs/getting-started/tasks/_index.md +++ b/docs/content/en/docs/getting-started/tasks/_index.md @@ -150,7 +150,8 @@ Incidentally, this is exactly how you can use Keptn with [applications deployed Annotate the demo application `Deployment` manifest to have Keptn automatically trigger the task after every deployment. -Recall the `Deployment` from the [getting started guide](../../getting-started/_index.md#step-3-deploy-demo-application). +Recall the `Deployment` from the [Observability](../../getting-started/observability/_index.md#step-3-deploy-demo-application) +Getting started guide. Add a new label so the `labels` section looks like this: diff --git a/docs/content/en/docs/getting-started/usecase_metrics.md b/docs/content/en/docs/getting-started/usecase_metrics.md index 0453e4629b..c6b3f09873 100644 --- a/docs/content/en/docs/getting-started/usecase_metrics.md +++ b/docs/content/en/docs/getting-started/usecase_metrics.md @@ -48,11 +48,11 @@ series. After completing this exercise, you may want to do the other exercises: -- In [Standardize observability](usecase-observability.md), +- In [Standardize observability](../intro/usecase-observability.md), you learn how to standardize access to the observability data for your cluster. - In - [Manage release lifecycle](usecase-orchestrate.md), + [Manage release lifecycle](../intro/usecase-orchestrate.md), you learn how to implement pre- and post-deployment tasks and evaluations to orchestrate the flow of all the `workloads` diff --git a/docs/content/en/docs/implementing/evaluatemetrics.md b/docs/content/en/docs/implementing/evaluatemetrics.md index c539af3f18..3959a5f584 100644 --- a/docs/content/en/docs/implementing/evaluatemetrics.md +++ b/docs/content/en/docs/implementing/evaluatemetrics.md @@ -16,7 +16,7 @@ or another standard dashboard application that you configure or can be retrieved using standard Kubernetes commands. For an introduction to Keptn metrics, see -[Getting started with Keptn metrics](../intro/usecase_metrics.md). +[Getting started with Keptn metrics](../getting-started/usecase_metrics.md). ## Keptn metric basics diff --git a/docs/content/en/docs/intro/_index.md b/docs/content/en/docs/intro/_index.md index 0b78fc41ee..faf94e6468 100644 --- a/docs/content/en/docs/intro/_index.md +++ b/docs/content/en/docs/intro/_index.md @@ -47,7 +47,7 @@ simplifying configuration and integration into a single set of metrics. To learn more, see: -* [Custom Keptn metrics](usecase_metrics.md) +* [Keptn metrics](../getting-started/usecase_metrics.md) getting started guide * [Keptn Metrics](../implementing/evaluatemetrics.md) guide ## Observability @@ -86,7 +86,7 @@ to ensure that your deployments are observable. To learn more, see: -* [Getting started with Keptn Observability](../getting-started) +* [Getting started with Keptn Observability](../getting-started/observability) * [Standardize observability](usecase-observability.md/) * [DORA metrics](../implementing/dora) guide * [OpenTelemetry observability](../implementing/otel.md) guide @@ -142,7 +142,7 @@ For more information, see: To learn more, see: -* [Getting started with release lifecycle management](../tutorials/tasks/) +* [Getting started with release lifecycle management](tasks/) * [Manage release lifecycle](usecase-orchestrate.md) * [Deployment tasks](../implementing/tasks) * [Evaluations](../implementing/evaluations.md) diff --git a/docs/content/en/docs/intro/usecase-orchestrate.md b/docs/content/en/docs/intro/usecase-orchestrate.md index 7c1e95193b..1d8f32a78a 100644 --- a/docs/content/en/docs/intro/usecase-orchestrate.md +++ b/docs/content/en/docs/intro/usecase-orchestrate.md @@ -29,7 +29,7 @@ and can do the following: * Validate any Keptn metric, either pre- or post-deployment, using the metrics from the Keptn Metrics Server introduced in - [Getting started with Keptn metrics](usecase_metrics.md). + [Getting started with Keptn metrics](../getting-started/usecase_metrics.md). This means that you can be sure that the environment is healthy and has adequate resources before you begin the deployment. diff --git a/docs/content/en/docs/yaml-crd-ref/metric.md b/docs/content/en/docs/yaml-crd-ref/metric.md index af4e3862ca..dd158deb83 100644 --- a/docs/content/en/docs/yaml-crd-ref/metric.md +++ b/docs/content/en/docs/yaml-crd-ref/metric.md @@ -156,5 +156,5 @@ spec: * [KeptnEvaluationDefinition](evaluationdefinition.md) * [KeptnMetricsProvider](metricsprovider.md) * Implementing [Keptn Metrics](../implementing/evaluatemetrics.md) -* [Getting started with Keptn metrics](../intro/usecase_metrics.md) +* [Getting started with Keptn metrics](../getting-started/usecase_metrics.md) * Architecture of the [Keptn Metrics Operator](../architecture/components/metrics-operator/_index.md) From c37b25a701456c1a1a2616a11bbd79a3991509f9 Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 18 Oct 2023 16:39:16 -0700 Subject: [PATCH 3/8] more xrefs Signed-off-by: Meg McRoberts --- .../en/docs/getting-started/observability/_index.md | 2 +- docs/content/en/docs/intro/_index.md | 10 +++++----- docs/content/en/docs/intro/usecase-observability.md | 2 +- docs/content/en/docs/intro/usecase-orchestrate.md | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/content/en/docs/getting-started/observability/_index.md b/docs/content/en/docs/getting-started/observability/_index.md index e396863710..9ebaf037e7 100644 --- a/docs/content/en/docs/getting-started/observability/_index.md +++ b/docs/content/en/docs/getting-started/observability/_index.md @@ -585,7 +585,7 @@ You may have noticed that the `KeptnApp` Custom Resources are created automatica However, you can override this automatic behaviour by creating a custom `KeptnApp` CRD. In this way, you are in full control of what constitutes a Keptn Application. -See [KeptnApp Reference page](../yaml-crd-ref/app.md) for more information. +See [KeptnApp Reference page](../../yaml-crd-ref/app.md) for more information. ## What's next? diff --git a/docs/content/en/docs/intro/_index.md b/docs/content/en/docs/intro/_index.md index faf94e6468..0b41cda30b 100644 --- a/docs/content/en/docs/intro/_index.md +++ b/docs/content/en/docs/intro/_index.md @@ -134,15 +134,15 @@ or a which is a single, cohesive unit that groups multiple workloads. For more information, see: -* [Keptn tasks](../implementing/tasks) -* [Evaluations](../implementing/evaluations.md) +* [Keptn tasks](../implementing/tasks) guide +* [Evaluations](../implementing/evaluations.md) guide * [KeptnApp and KeptnWorkflow resources](../architecture/keptn-apps) ## Next steps To learn more, see: -* [Getting started with release lifecycle management](tasks/) +* [Getting started with release lifecycle management](../getting-started/tasks/) * [Manage release lifecycle](usecase-orchestrate.md) -* [Deployment tasks](../implementing/tasks) -* [Evaluations](../implementing/evaluations.md) +* [Deployment tasks](../implementing/tasks) guide +* [Evaluations](../implementing/evaluations.md) guide diff --git a/docs/content/en/docs/intro/usecase-observability.md b/docs/content/en/docs/intro/usecase-observability.md index fac1f15e9e..e0d3f57b40 100644 --- a/docs/content/en/docs/intro/usecase-observability.md +++ b/docs/content/en/docs/intro/usecase-observability.md @@ -47,7 +47,7 @@ This is the second of three exercises in the series: - In the - [Getting started with Keptn metrics](usecase_metrics.md) + [Getting started with Keptn metrics](../getting-started/usecase_metrics.md) exercise, you learn how to define and use Keptn metrics. You may want to complete that exercise before doing this exercise although that is not required. diff --git a/docs/content/en/docs/intro/usecase-orchestrate.md b/docs/content/en/docs/intro/usecase-orchestrate.md index 1d8f32a78a..f4979caede 100644 --- a/docs/content/en/docs/intro/usecase-orchestrate.md +++ b/docs/content/en/docs/intro/usecase-orchestrate.md @@ -62,7 +62,7 @@ You may want to complete the other exercises before doing this exercise although that is not required: * In the - [Getting started with Keptn metrics](usecase_metrics.md) + [Getting started with Keptn metrics](../getting-started/usecase_metrics.md) exercise, you learn how to define and use Keptn metrics. * In [Standardize observability](usecase-observability.md), you learn how to standardize access From b1d197975b412491916162edcc33ae55de71344d Mon Sep 17 00:00:00 2001 From: Meg McRoberts Date: Wed, 18 Oct 2023 16:44:09 -0700 Subject: [PATCH 4/8] yet another xref Signed-off-by: Meg McRoberts --- docs/content/en/docs/intro/usecase-observability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs/intro/usecase-observability.md b/docs/content/en/docs/intro/usecase-observability.md index e0d3f57b40..9a80078ec0 100644 --- a/docs/content/en/docs/intro/usecase-observability.md +++ b/docs/content/en/docs/intro/usecase-observability.md @@ -116,7 +116,7 @@ which allows you to trace everything done in the context of that deployment. You can supplement the DORA Metrics and OpenTelemetry information with information you explicitly define using Keptn metrics. The -[Getting started with Keptn metrics](usecase_metrics.md) +[Getting started with Keptn metrics](../getting-started/usecase_metrics.md) exercise discusses how to define Keptn metrics. ## View the results From 049263bf83d017d7027fddff3da25e0556b911dc Mon Sep 17 00:00:00 2001 From: Moritz Wiesinger Date: Tue, 24 Oct 2023 10:49:36 +0200 Subject: [PATCH 5/8] Update docs/content/en/docs/getting-started/observability/_index.md Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Signed-off-by: Moritz Wiesinger --- docs/content/en/docs/getting-started/observability/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs/getting-started/observability/_index.md b/docs/content/en/docs/getting-started/observability/_index.md index 9ebaf037e7..cc7204ee4d 100644 --- a/docs/content/en/docs/getting-started/observability/_index.md +++ b/docs/content/en/docs/getting-started/observability/_index.md @@ -176,7 +176,7 @@ Keptn is now aware of your deployments and is generating DORA statistics about t Keptn has created a resource called a `KeptnApp` to track your application. The name of which is based on the `part-of` label. -It may take up to 30 seconds to create the `KeptnApp` so run the following command until you see the `keptnappdemo` CRD. +It may take up to 30 seconds to create the `KeptnApp` so run the following command until you see the `keptnappdemo` CR. ```shell kubectl -n keptndemo get keptnapp From c37eef604da1fc5dac3982dcc448ef5065896901 Mon Sep 17 00:00:00 2001 From: Moritz Wiesinger Date: Tue, 24 Oct 2023 10:49:52 +0200 Subject: [PATCH 6/8] Update docs/content/en/docs/getting-started/observability/_index.md Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Signed-off-by: Moritz Wiesinger --- docs/content/en/docs/getting-started/observability/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs/getting-started/observability/_index.md b/docs/content/en/docs/getting-started/observability/_index.md index cc7204ee4d..b15a4fd38d 100644 --- a/docs/content/en/docs/getting-started/observability/_index.md +++ b/docs/content/en/docs/getting-started/observability/_index.md @@ -61,7 +61,7 @@ Keptn will need to know where to send OpenTelemetry traces. Of course, Jaeger is not yet installed so traces have nowhere to go (yet), but creating this configuration now means the system is preconfigured. -Save this file as `collectorconfig.yaml`. +Save this file as `keptnconfig.yaml`. It doesn't matter where this file is located on your local machine: ```yaml From 57b5859505dbaef10fd75f5ae50db6e6af48023c Mon Sep 17 00:00:00 2001 From: Moritz Wiesinger Date: Tue, 24 Oct 2023 10:50:06 +0200 Subject: [PATCH 7/8] Update docs/content/en/docs/getting-started/observability/_index.md Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Signed-off-by: Moritz Wiesinger --- docs/content/en/docs/getting-started/observability/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs/getting-started/observability/_index.md b/docs/content/en/docs/getting-started/observability/_index.md index b15a4fd38d..410c4136d5 100644 --- a/docs/content/en/docs/getting-started/observability/_index.md +++ b/docs/content/en/docs/getting-started/observability/_index.md @@ -79,7 +79,7 @@ spec: Apply the file and restart Keptn to pick up the new config: ```shell -kubectl apply -f collectorconfig.yaml +kubectl apply -f keptnconfig.yaml ``` ## Step 2: Create Namespace for Demo Application From 0206822ca93e5b8dabc19fe83c435fe47c080d88 Mon Sep 17 00:00:00 2001 From: Moritz Wiesinger Date: Tue, 24 Oct 2023 10:50:21 +0200 Subject: [PATCH 8/8] Update docs/content/en/docs/getting-started/observability/_index.md Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com> Signed-off-by: Moritz Wiesinger --- docs/content/en/docs/getting-started/observability/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs/getting-started/observability/_index.md b/docs/content/en/docs/getting-started/observability/_index.md index 410c4136d5..8f1426a37f 100644 --- a/docs/content/en/docs/getting-started/observability/_index.md +++ b/docs/content/en/docs/getting-started/observability/_index.md @@ -213,7 +213,7 @@ kubectl -n keptndemo get keptnappversion -o wide ``` Keptn applications are a collection of workloads. -By default, Keptn will build `KeptnApp` resources based on the labels you provide. +By default, Keptn will build a `KeptnApp` resource based on the labels you provide. In the example above, the `KeptnApp` called `keptndemoapp` contains one `KeptnWorkload` (based on the `app.kubernetes.io/name` label):