diff --git a/.github/workflows/CI.yaml b/.github/workflows/CI.yaml index 914a09f639..89d818f705 100644 --- a/.github/workflows/CI.yaml +++ b/.github/workflows/CI.yaml @@ -11,6 +11,7 @@ on: - 'epic/*' paths-ignore: - "docs/**" + - "docs-new/**" - "**.md" - "netlify.toml" diff --git a/docs-new/assets/javascripts/versions.js b/docs-new/assets/javascripts/versions.js index faded9764d..e6d3a2bb3f 100644 --- a/docs-new/assets/javascripts/versions.js +++ b/docs-new/assets/javascripts/versions.js @@ -1,5 +1,6 @@ // VERSION WARNINGS window.addEventListener("DOMContentLoaded", function() { + return; //TODO: decide if we want this var rtdData = window['READTHEDOCS_DATA'] || { version: 'latest' }; var margin = 30; var headerHeight = document.getElementsByClassName("md-header")[0].offsetHeight; diff --git a/docs-new/docs/assets/crd/analysis-definition.yaml b/docs-new/docs/assets/crd/analysis-definition.yaml new file mode 100644 index 0000000000..a2a0825381 --- /dev/null +++ b/docs-new/docs/assets/crd/analysis-definition.yaml @@ -0,0 +1,23 @@ +apiVersion: metrics.keptn.sh/v1beta1 +kind: AnalysisDefinition +metadata: + name: ad-my-proj-dev-svc1 + namespace: keptn-system +spec: + objectives: + - analysisValueTemplateRef: + name: response-time-p95 + namespace: keptn-system + target: + failure: + lessThan: + fixedValue: 600 + warning: + inRange: + lowBound: 300 + highBound: 500 + weight: 1 + keyObjective: false + totalScore: + passPercentage: 90 + warningPercentage: 75 diff --git a/docs-new/docs/assets/crd/analysis-template.yaml b/docs-new/docs/assets/crd/analysis-template.yaml new file mode 100644 index 0000000000..88a67f5590 --- /dev/null +++ b/docs-new/docs/assets/crd/analysis-template.yaml @@ -0,0 +1,15 @@ +apiVersion: metrics.keptn.sh/v1beta1 +kind: AnalysisValueTemplate +metadata: + labels: + app.kubernetes.io/name: analysisvaluetemplate + app.kubernetes.io/instance: analysisvaluetemplate-sample + app.kubernetes.io/part-of: metrics-operator + app.kubernetes.io/managed-by: kustomize + app.kubernetes.io/created-by: metrics-operator + name: response-time-p95 + namespace: keptn-system +spec: + provider: + name: prometheus + query: "sum(kube_pod_container_resource_limits{node='{{.nodename}}'}) - sum(kube_node_status_capacity{node='{{.nodename}}'})" diff --git a/docs-new/docs/assets/crd/analysis.yaml b/docs-new/docs/assets/crd/analysis.yaml new file mode 100644 index 0000000000..d65ee3e6ad --- /dev/null +++ b/docs-new/docs/assets/crd/analysis.yaml @@ -0,0 +1,21 @@ +apiVersion: metrics.keptn.sh/v1beta1 +kind: Analysis +metadata: + labels: + app.kubernetes.io/name: analysis + app.kubernetes.io/instance: analysis-sample + app.kubernetes.io/part-of: metrics-operator + app.kubernetes.io/managed-by: kustomize + app.kubernetes.io/created-by: metrics-operator + name: analysis-sample +spec: + timeframe: + recent: 5m + args: + project: my-project + stage: dev + service: svc1 + nodename: test # can be any key/value pair; NOT only project/stage/service + analysisDefinition: + name: ad-my-proj-dev-svc1 + namespace: keptn-system diff --git a/docs-new/docs/assets/crd/eval.yaml b/docs-new/docs/assets/crd/eval.yaml new file mode 100644 index 0000000000..4ac8a4bea8 --- /dev/null +++ b/docs-new/docs/assets/crd/eval.yaml @@ -0,0 +1,11 @@ +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnEvaluationDefinition +metadata: + name: app-pre-deploy-eval-2 + namespace: podtato-kubectl +spec: + objectives: + - keptnMetricRef: + name: available-cpus + namespace: podtato-kubectl + evaluationTarget: ">1" diff --git a/docs-new/docs/assets/crd/metric.yaml b/docs-new/docs/assets/crd/metric.yaml new file mode 100644 index 0000000000..ef2a8c2f2e --- /dev/null +++ b/docs-new/docs/assets/crd/metric.yaml @@ -0,0 +1,10 @@ +apiVersion: metrics.keptn.sh/v1beta1 +kind: KeptnMetric +metadata: + name: available-cpus + namespace: podtato-kubectl +spec: + provider: + name: my-provider + query: "sum(kube_node_status_capacity{resource='cpu'})" + fetchIntervalSeconds: 10 diff --git a/docs-new/docs/assets/crd/python-configmap.yaml b/docs-new/docs/assets/crd/python-configmap.yaml new file mode 100644 index 0000000000..d288345154 --- /dev/null +++ b/docs-new/docs/assets/crd/python-configmap.yaml @@ -0,0 +1,16 @@ +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: scheduled-deployment +spec: + python: + configMapRef: + name: python-test-cm +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: python-test-cm +data: + code: | + print("Hello, World!") diff --git a/docs-new/docs/assets/crd/python-context.yaml b/docs-new/docs/assets/crd/python-context.yaml new file mode 100644 index 0000000000..0b5206991a --- /dev/null +++ b/docs-new/docs/assets/crd/python-context.yaml @@ -0,0 +1,31 @@ +apiVersion: v1 +kind: Secret +metadata: + name: mysecret +type: Opaque +data: + SECURE_DATA: dG9rZW46IG15dG9rZW4= +--- +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: pre-deployment-hello + annotations: + python: test +spec: + python: + parameters: + map: + user: "myuser" + secureParameters: + secret: mysecret + cmdParameters: "-h" + inline: + code: | + import os + import yaml + data = os.getenv('DATA') + dct = yaml.safe_load(data) + USER= dct['user'] + PASSWORD = os.environ.get('SECURE_DATA') + print(USER,PASSWORD) diff --git a/docs-new/docs/assets/crd/python-inline.yaml b/docs-new/docs/assets/crd/python-inline.yaml new file mode 100644 index 0000000000..652b7b1b9d --- /dev/null +++ b/docs-new/docs/assets/crd/python-inline.yaml @@ -0,0 +1,14 @@ +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: scheduled-deployment-inline +spec: + python: + parameters: + map: + mydata: "my-user-defined" + inline: + code: | + # Get environment variables + data = os.getenv('DATA') + print(data) diff --git a/docs-new/docs/assets/crd/python-libs.yaml b/docs-new/docs/assets/crd/python-libs.yaml new file mode 100644 index 0000000000..7187f858d7 --- /dev/null +++ b/docs-new/docs/assets/crd/python-libs.yaml @@ -0,0 +1,34 @@ +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: python-inline +spec: + python: + inlineRef: + code: | + import sys + import json + import yaml + print("Hello, World!") + dct = yaml.safe_load(''' + name: John + age: 30 + automobiles: + - brand: Honda + type: Odyssey + year: 2018 + - brand: Toyota + type: Sienna + year: 2015 + ''') + assert dct['name'] == 'John' + assert dct['age'] == 30 + assert len(dct["automobiles"]) == 2 + assert dct["automobiles"][0]["brand"] == "Honda" + assert dct["automobiles"][1]["year"] == 2015 + # some JSON: + x = '{ "name":"John", "age":30, "city":"New York"}' + # parse x: + y = json.loads(x) + # the result is a Python dictionary: + print(y["age"]) diff --git a/docs-new/docs/assets/crd/python-recursive.yaml b/docs-new/docs/assets/crd/python-recursive.yaml new file mode 100644 index 0000000000..2d6b35b8de --- /dev/null +++ b/docs-new/docs/assets/crd/python-recursive.yaml @@ -0,0 +1,11 @@ +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: scheduled-deployment-2 +spec: + python: + parameters: + map: + mydata: "my-other-data" + functionRef: + name: scheduled-deployment-inline diff --git a/docs-new/docs/assets/crd/task-definition.yaml b/docs-new/docs/assets/crd/task-definition.yaml new file mode 100644 index 0000000000..af166c8113 --- /dev/null +++ b/docs-new/docs/assets/crd/task-definition.yaml @@ -0,0 +1,13 @@ +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: container-sleep + namespace: podtato-kubectl +spec: + container: + name: testy-test + image: busybox:1.36.1 + command: + - 'sh' + - '-c' + - 'sleep 30' diff --git a/docs-new/docs/components/certificate-operator/index.md b/docs-new/docs/components/certificate-operator/index.md new file mode 100644 index 0000000000..cd4b7806ac --- /dev/null +++ b/docs-new/docs/components/certificate-operator/index.md @@ -0,0 +1,65 @@ +# Keptn Certificate Manager + +## Keptn Cert Manager + +The Keptn Cert Manager 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 + +When a certificate is left over from an older version, +the webhook or the operator may generate errors +because of an invalid certificate. +To solve this, delete the certificate and restart the operator. + +The Keptn cert-manager certificate is stored as a secret in the +`keptn-system` namespace. +To retrieve it: + +```shell +kubectl get secrets -n keptn-system +``` + +This returns something like: + +```shell +NAME TYPE DATA AGE +keptn-certs Opaque 5 4d23h +``` + +Specify the `NAME` of the Keptn certificate (`keptn-certs` in this case) +to delete the Keptn certificate: + +```shell +kubectl delete secret keptn-certs -n keptn-system +``` diff --git a/docs-new/docs/components/index.md b/docs-new/docs/components/index.md new file mode 100644 index 0000000000..d4e457f6df --- /dev/null +++ b/docs-new/docs/components/index.md @@ -0,0 +1,24 @@ +# Components + +## Keptn Components + +Keptn consists of two main components: + +* Keptn Lifecycle Operator, which splits into two separate operators + in Release 0.7.0 and later: + * Lifecycle-Operator + * Metrics-Operator +* Keptn Lifecycle Scheduler + +```mermaid +graph TD; + KeptnComponents-->Operators; + KeptnComponents-->Scheduler + Operators-->Lifecycle-Operator + Operators-->Metrics-Operator +style KeptnComponents fill:#006bb8,stroke:#fff,stroke-width:px,color:#fff +style Operators fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8 +style Scheduler fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8 +style Lifecycle-Operator fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8 +style Metrics-Operator fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8 +``` diff --git a/docs-new/docs/components/lifecycle-operator/deployment-flow.md b/docs-new/docs/components/lifecycle-operator/deployment-flow.md new file mode 100644 index 0000000000..943de88f38 --- /dev/null +++ b/docs-new/docs/components/lifecycle-operator/deployment-flow.md @@ -0,0 +1,186 @@ +# Flow of deployment + +Keptn deploys a +[Kubernetes Workload](https://kubernetes.io/docs/concepts/workloads/) +by passing through a well-defined execution flow. + +The execution flow goes through six main phases: + +* Pre-deployments-tasks +* Pre-deployment-evaluation +* Deployment +* Post-deployment-tasks +* Post-deployment-evaluation +* Completed + +Within each phase, all tasks and evaluations for each phase +are executed in parallel. +They are not affected by the order +in which evaluations and tasks are listed in the +[KeptnApp](../../reference/crd-reference/app.md) +resource +or in the order of the pre/post-tasks and pre/post-evaluations +that are listed in the Workflow manifests. + +## Kubernetes and Cloud Events + +[Kubernetes Events](https://kubernetes.io/docs/reference/kubernetes-api/cluster-resources/event-v1/) +and [CloudEvents](https://cloudevents.io/) +are emitted at each phase +to provide additional Observability of the execution flow. + +Keptn implements a +[Permit Scheduler Plugin](https://kubernetes.io/docs/concepts/scheduling-eviction/scheduling-framework/#permit) +that blocks the binding of the pods to a node +until all the pre-conditions are fulfilled. + +A Kubernetes deployment is started by the deployment engine +that is implemented +(such as Flux or Argo) +or can be started by the following command: + +```shell +kubectl apply -f deployment.yaml +``` + +Keptn does not care how a deployment manifest is applied to the cluster. +Both `kubectl` and Flux/Argo send the manifest to the Kubernetes API +so Keptn does not differentiate the actual deployment options. +This also means that one Keptn Application +can include services that are deployed with different methods. + +The deployment is created +but the created pods are blocked and in pending state +until all the required pre-deployment tasks/evaluations +defined on either the `KeptnApp` or `KeptnWorkload` level pass. +Only then are the pods bound to a node and deployed. +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 +If all evaluations and tasks in a phase are successful, +the `KeptnApp` issues the appropriate `*Succeeded` event +and initiates the next phase. + +## Summary of deployment flow + +To view these events on your cluster, execute: + +```shell +kubectl get events -n . +``` + +### Pre-deployment phase + +Pre-deployment tasks can perform any kind of action needed +to prepare for the deployment, including unit tests, load tests or other similar tests. + +```shell +AppPreDeployTasks + AppPreDeployTasksStarted + AppPreDeployTasksSucceeded OR AppPreDeployTasksErrored +``` + +### Pre-deployment evaluation phase + +Pre-deployment evaluation can be used to assert the status of the cluster +or of services the [workload](https://kubernetes.io/docs/concepts/workloads/) depends on, +to assure it is deployed only if the specified prerequisites are met. + +```shell +AppPreDeployEvaluations + AppPreDeployEvaluationsStarted + AppPreDeployEvaluationsSucceeded OR AppPreDeployEvaluationsErrored +``` + +### Deployment phase + +The `AppDeploy` phase basically covers +the entire deployment and check phase of the [workloads](https://kubernetes.io/docs/concepts/workloads/). +The `KeptnApp` just observes whether +all pre and post-deployment tasks/evaluation are successful +and that the pods are deployed successfully. +When all activities are successful, +the `KeptnApp` issues the `AppDeploySucceeded` event +and continues to the next phase. +If any of these activities fail, +the `KeptnApp` issues the `AppDeployErrored` event +and terminates the deployment. + +```shell +AppDeploy + AppDeployStarted + WorkloadPreDeployTasks + WorkloadPreDeployTasksStarted + WorkloadPreDeployTasksSucceeded OR WorkloadPreDeployTasksErrored + WorkloadPreDeployEvaluations + WorkloadPreDeployEvaluationsStarted + WorkloadPreDeployEvaluationsSucceeded OR WorkloadPreDeployErrored + WorkloadDeploy + WorkloadDeployStarted + WorkloadDeploySucceeded OR WorkloadDeployErrored + WorkloadPostDeployTasks + WorkloadPostDeployTasksStarted + WorkloadPostDeployTasksSucceeded OR WorkloadPostDeployTasksErrored + WorkloadPostDeployEvaluations + WorkloadPostDeployEvaluationsStarted + WorkloadPostDeployEvaluationsSucceeded OR WorkloadPostDeployEvaluationsErrored + AppDeploySucceeded OR AppDeployErrored + ``` + +### Post-deployment phase + +The post-deployment phase is typically used +to run tests on the freshly deployed application, +such as gathering performance data. + +```shell +AppPostDeployTasks + AppPostDeployTasksStarted + AppPostDeployTasksSucceeded OR AppPostDeployTasksErrored +``` + +### Post-deployment evaluation phase + +The post-deployment evaluation can be used +to analyze the cluster/application status after the new workload is deployed. +The result of this phase does not revert or influence the deployment +but can be used by other external tools, for instance, to react to a failure. + +```shell +AppPostDeployEvaluations + AppPostDeployEvaluationsStarted + AppPostDeployEvaluationsSucceeded OR AppPostDeployEvaluationsErrored +``` + +### Completed phase + +```shell +Completed +``` + +## Events that are not part of the deployment flow + +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. +These include: + +```shell +CreateEvaluation +ReconcileEvaluation +ReconcileTask +CreateTask +CreateApp +CreateAppVersion +CreateWorkload +CreateWorkloadVersion +Completed +Deprecated +WorkloadDeployReconcile +WorkloadDeployReconcileErrored +``` diff --git a/docs-new/docs/components/lifecycle-operator/index.md b/docs-new/docs/components/lifecycle-operator/index.md new file mode 100644 index 0000000000..758c9be4bd --- /dev/null +++ b/docs-new/docs/components/lifecycle-operator/index.md @@ -0,0 +1,20 @@ +# Keptn Lifecycle Operator + +**Keptn's Lifecycle Operator** is +a Kubernetes [operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) +that automates the deployment and management +of the Keptn components in a Kubernetes cluster. +The Keptn Lifecycle Operator contains several controllers for **Keptn CRDs** +and a **Mutating Webhook**. + +Here's a brief overview: + +**Keptn CRDs:** Keptn Lifecycle Operator contains +several controllers that manage and reconcile different types of Keptn CRDs +such as the Project Controller, Service Controller, and Stage Controller. + +**Mutating Webhook:** automatically injects Keptn labels +and annotations into Kubernetes resources, +such as deployments and services. +These labels and annotations are used to enable Keptn's automation +and monitoring capabilities. diff --git a/docs-new/docs/components/lifecycle-operator/keptn-apps.md b/docs-new/docs/components/lifecycle-operator/keptn-apps.md new file mode 100644 index 0000000000..94839e6232 --- /dev/null +++ b/docs-new/docs/components/lifecycle-operator/keptn-apps.md @@ -0,0 +1,121 @@ +# KeptnApp and KeptnWorkload resources + +## Keptn Workloads + +A +[KeptnWorkload](../../reference/api-reference/lifecycle/v1alpha3/index.md#keptnworkload) +resource augments a Kubernetes +[Workload](https://kubernetes.io/docs/concepts/workloads/) +with the ability to handle extra phases. +It can execute the pre- and post-deployment evaluations of a Workload +and run pre- and post-deployment tasks. + +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 +whether the pods belonging to a workload +should be created and assigned to a node. +When it detects that the referenced object has reached its desired state +(e.g. all pods of a deployment are up and running), +it knows that a`PostDeploymentCheck` can be triggered. + +The `KeptnWorkload` resources are created automatically +and without delay by the mutating webhook +as soon as the workload manifest is applied. + +## Keptn Applications + +A [KeptnApp](../../reference/crd-reference/app.md) +resource combines multiple Kubernetes +[workloads](https://kubernetes.io/docs/concepts/workloads/) +into a single entity +that represent the application that is published. +Note that the Kubernetes documentation +often refers to workloads as applications, +but each workload actually corresponds to one version +of one deployable microservice, +not the amalgamation of multiple microservices +that typically comprise the released software. + +Implementing Keptn applications provides the following benefits: + +* Observability tools report on the deployment + of all workloads together rather than individually. +* You can define pre-deployment evaluations and tasks + that must all complete successfully + before the scheduler creates the pods for any of the workloads. +* You can define post-deployment evaluations and tasks + that run only after all the workloads have completed successfully. + +You control the content of a `KeptnApp` resource +with annotations or labels that are applied to each +[Workload](https://kubernetes.io/docs/concepts/workloads/) +([Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), +[StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/), +and +[DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) +plus specific tasks and evaluations that you define +for the `KeptnApp` resource itself: + +* The annotations described in + [Basic annotations](../../guides/integrate.md#basic-annotations) + are used to automatically generate `KeptnApp` resources + that contain the identifications required + to run the Keptn observability features. +* You must manually add the annotations described in + [Pre- and post-deployment checks](../../guides/integrate.md#pre--and-post-deployment-checks) + to the basic `KeptnApp` manifest to define + the evaluations and tasks you want to run pre- and post-deployment. + +The `KeptnApp` resources that are generated automatically +contain the identifications required to run the Keptn observability features. +The `spec.workloads.name` and a `spec.workloads.version` fields +that define evaluations and tasks to be run +pre- and post-deployment are not generated automatically +but must be input manually. + +By default, the `KeptnApp` resources are updated every 30 seconds +when any of the Workloads have been modified; +The timeout is provided because it may take some time +to apply all `KeptnWorkload` resources to the cluster. +This interval can be modified for the cluster by changing the value +of the `keptnAppCreationRequestTimeoutSeconds` field in the +[KeptnConfig](../../reference/crd-reference/config.md) +resource. + +## How basic annotations are implemented + +The [Basic annotations](../../guides/integrate.md#basic-annotations) +page gives instructions for applying the annotations or labels +that identify the pods that Keptn should manage. + +Three `keptn.sh` and three `app.kubernetes.io` keys are recognized. +They are equivalent; you can use either of them +and they can be implemented as either annotations or labels. +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 + in the annotations, and then in the labels. +* 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 +[KeptnApp](../../reference/crd-reference/app.md) +resources that are used for observability, +based on whether the `keptn.sh/app` or `app.kubernetes.io/part-of` +annotation/label is populated: +resource for each defined group. +that together constitute a single deployable Keptn Application. + +* If either of these labels/annotations are populated, + Keptn automatically generates a `KeptnApp` resource + that includes all workloads that have the same annotation/label, + thus creating a `KeptnApp` resource for each defined grouping + +* If only the `workload` and `version` annotations/labels are available + (in other words, neither the `keptn.sh/app` + or `app.kubernetes.io/part-of` annotation/label is populated), + one `KeptnApp` resource is created automatically for each workload. diff --git a/docs-new/docs/components/metrics-operator/index.md b/docs-new/docs/components/metrics-operator/index.md new file mode 100644 index 0000000000..d9b919067f --- /dev/null +++ b/docs-new/docs/components/metrics-operator/index.md @@ -0,0 +1,87 @@ +# Keptn Metrics Operator + +The Keptn Metrics Operator collects, processes, +and analyzes metrics data from a variety of sources. +Once collected, this data can be used +to generate a variety of reports and dashboards +that provide insights into the health and performance +of the application and infrastructure. + +While Kubernetes has ways to extend its metrics APIs, they have limitations, +especially that they only allow you to use 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. + +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. +See +[Using the HorizontalPodAutoscaler](../../use-cases/hpa.md) +for instructions. + +The Metrics Operator consists of the following components: + +* Metrics Controller +* Metrics Adapter + +```mermaid +graph TD; + Metrics-Operator-->Metrics-Adapter; + Metrics-Operator-->Metrics-Controller +style Metrics-Operator fill:#006bb8,stroke:#fff,stroke-width:px,color:#fff +style Metrics-Adapter fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8 +style Metrics-Controller fill:#d8e6f4,stroke:#fff,stroke-width:px,color:#006bb8 +``` + +The **Metrics adapter** exposes custom metrics from an application +to external monitoring and alerting tools. +The adapter exposes custom metrics on a specific endpoint +where external monitoring and alerting tools can scrape them. +It is an important component of the metrics operator +as it allows for the collection and exposure of custom metrics, +which can be used to gain insight into the behavior and performance +of applications running on a Kubernetes cluster. + +The **Metrics controller** fetches metrics from an SLI provider. +The controller reconciles a [`KeptnMetric`](../../reference/crd-reference/metric.md) +resource and updates its status with the metric value +provided by the selected metric provider. +Each `KeptnMetric` is identified by `name` +and is associated with an instance of an observability platform +that is defined in a +[KeptnMetricsProvider](../../reference/crd-reference/metricsprovider.md) +resource. + +The steps in which the controller fetches metrics are given below: + +1. When a [`KeptnMetric`](../../reference/crd-reference/metric.md) + resource is found or modified, + the controller checks whether the metric has been updated + within the interval that is defined in the `spec.fetchintervalseconds` field. + * If not, it skips the reconciliation process + and queues the request for later. + +1. 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, + the controller loads the provider and evaluates the query + defined in the `spec.query` field. + * If the evaluation is successful, + it stores the fetched value + in the `status` field of the `KeptnMetric` object. + * If the evaluation fails, + the error and reason is written to the + [KeptnMetricStatus](../../reference/api-reference/metrics/v1beta1/index.md#keptnmetricstatus) + resource. + The error is described in both human-readable language + and as raw data to help identify the source of the problem + (such as a forbidden code). diff --git a/docs-new/docs/components/scheduling/assets/gate-removed.yaml b/docs-new/docs/components/scheduling/assets/gate-removed.yaml new file mode 100644 index 0000000000..eaf4809fdc --- /dev/null +++ b/docs-new/docs/components/scheduling/assets/gate-removed.yaml @@ -0,0 +1,6 @@ +apiVersion: v1 +kind: Pod +metadata: + name: test-pod + annotations: + keptn.sh/scheduling-gate-removed: "true" diff --git a/docs-new/docs/components/scheduling/assets/gated.yaml b/docs-new/docs/components/scheduling/assets/gated.yaml new file mode 100644 index 0000000000..f986c5f3b1 --- /dev/null +++ b/docs-new/docs/components/scheduling/assets/gated.yaml @@ -0,0 +1,7 @@ +apiVersion: v1 +kind: Pod +metadata: + name: test-pod +spec: + schedulingGates: + - name: "keptn-prechecks-gate" diff --git a/docs-new/docs/components/scheduling/assets/scheduler.yaml b/docs-new/docs/components/scheduling/assets/scheduler.yaml new file mode 100644 index 0000000000..c03e3ddec6 --- /dev/null +++ b/docs-new/docs/components/scheduling/assets/scheduler.yaml @@ -0,0 +1,6 @@ +apiVersion: v1 +kind: Pod +metadata: + name: test-pod +spec: + schedulerName: keptn-scheduler diff --git a/docs-new/docs/components/scheduling/index.md b/docs-new/docs/components/scheduling/index.md new file mode 100644 index 0000000000..294fce3414 --- /dev/null +++ b/docs-new/docs/components/scheduling/index.md @@ -0,0 +1,118 @@ +# Keptn integration with Scheduling + +Keptn integrates with Kubernetes scheduling to block +the deployment of applications that do not satisfy Keptn defined pre-deployment checks. +The default scheduling paradigm is different +depending on the version of Kubernetes you are running: + +* On Kubernetes versions 1.26 and older, + Keptn uses the **Keptn Scheduler** to block application deployment when appropriate + and orchestrate the deployment process. + +* On Kubernetes version 1.27 and greater, + scheduling is implemented using + [Kubernetes scheduling gates](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-scheduling-readiness/). + +These two implementations are discussed below. + +## Keptn Scheduling Gates for K8s 1.27 and above + +When Keptn is running on Kubernetes version 1.27 and greater +and the Keptn Helm value `lifecycleOperator.schedulingGatesEnabled` is set to `true`, +Keptn uses the +[Pod Scheduling Readiness K8s API](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-scheduling-readiness) +to gate Pods until the required deployment checks pass. + +When a workload is applied to a Kubernetes cluster, +the Mutating Webhook checks each Pod for annotations. +If +[Keptn specific annotations](../../guides/integrate.md#basic-annotations) +are present, +the Webhook adds a scheduling gate to the Pod called `keptn-prechecks-gate`. +This spec tells the Kubernetes scheduling framework +to wait for the Keptn checks before binding the pod to a node. + +For example, a pod gated by Keptn looks like the following: + +{% include "./assets/gated.yaml" %} + +If the `pre-deployment` checks 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. +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: + +{% include "./assets/gate-removed.yaml" %} + +## Keptn Scheduler for K8s 1.26 and earlier + +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, +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 +scheduler has (typically CPU and memory values). + +The Keptn Scheduler uses the Kubernetes +[Scheduler Framework](https://kubernetes.io/docs/concepts/scheduling-eviction/scheduling-framework/) and is based on the +[Scheduler Plugins Repository](https://github.com/kubernetes-sigs/scheduler-plugins/tree/master). +Additionally, it registers itself as +a [Permit plugin](https://kubernetes.io/docs/concepts/scheduling-eviction/scheduling-framework/#permit). + +### How does the Keptn Scheduler works + +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. +A Pod `test-pod` modified by the Mutating Webhook looks as follows: + +{% include "./assets/scheduler.yaml" %} + +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 +need to be performed before the Pod can be scheduled. + +The Keptn Scheduler then checks the status of the WorkloadVersion CRD 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. + +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 +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/). +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/docs-new/docs/contribute/docs/contrib-guidelines-docs/index.md b/docs-new/docs/contribute/docs/contrib-guidelines-docs/index.md new file mode 100644 index 0000000000..3391288cd2 --- /dev/null +++ b/docs-new/docs/contribute/docs/contrib-guidelines-docs/index.md @@ -0,0 +1,100 @@ +# Contribution guidelines for documentation + +The [Contribution Guidelines](../../general/contrib-guidelines-gen/index.md) page +contains guidelines that are relevant +for both documentation and software contributions. +This page lists additional guidelines +that are relevant only to documentation + +## Guidelines for contributing + +* Keep your language clean and crisp. + We do not have an official *Style Guide* for Keptn but the + [Google developer documentation style guide](https://developers.google.com/style) + is a good general reference. + +* Use topic sentences for sections and paragraphs. + When reading a well-written technical document, + you should be able to read the first sentence in each paragraph + and especially in each section to get an idea of what might follow. + + Good oral presentations commonly begin with a "set-up" + where they describe a problem + and then proceed to tell how to fix that problem. + When using oral presentations as source material, + it is important to rewrite the text + so that the actual subject of discussion comes first. + +* Avoid using FAQ's in documentation. + In general, they say "here is some miscellaneous information + that I was too lazy to organize logically for you." + On rare occasions, they may be appropriate, + such as if you need a quick reference to a large, complicated document + and include links to detailed documentation about the topic. + +* We are attempting to avoid duplicated information across the doc set, + especially for information that is expected to change. + For example, information about supported Kubernetes versions + and the command sequence to install Keptn should usually be done + as references to the official installation section of the docs. + + For usability considerations, we make the following exceptions: + + * The main `README.md` file for the lifecycle-toolkit repository + includes this basic information as well as a link + to the full installation documentation which has more details. + * The Getting Started Guide also includes this information + for the same reason. + +* When you want to display a sample file that exists in the repository, + use the `embed path` shortcode syntax + (which automatically pulls the current version of the file into your document) + rather than copying the text. + This ensures that, when the sample file is updated, + your document is also updated. + + For example, to embed the `examples/sample-app/version3/app-pre-deploy-eval.yaml` file, + the syntax is: + + ```md + {%/*include "examples/sample-app/version-3/app-pre-deploy-eval.yaml"*/%} + + ``` + +* `markdownlint` enforces limits on line length. + Links to other documents are exempted from this limit + but, if a line has words before and after the long string, + `markdownlint` fails. + A good practice is to just code all links on their own page. + So, instead of coding: + + ```shell + The [Other section](long-link-to-section) page + ... + ``` + + you should code the following, + unless the link is so short + that you are sure it will not violate the line-length rules:: + + ```shell + The + [Other section](long-link-to-section) + page + ... + ``` + +* Always build the documentation locally to check the formatting + and verify that all links are working properly. + See [Build Documentation Locally](../local-building/index.md) + for details. + +* Always run the following to fix most markdown issues in your PR + and identify issues that can not be fixed automatically: + + ```shell + make markdownlint-fix + ``` + + See [Markdownlint](../linter-requirements/index.md#markdownlint) + for details. diff --git a/docs-new/docs/contribute/docs/index.md b/docs-new/docs/contribute/docs/index.md new file mode 100644 index 0000000000..90ba2d4677 --- /dev/null +++ b/docs-new/docs/contribute/docs/index.md @@ -0,0 +1,9 @@ +# Documentation contributions + +This section is under development. +Contents are not complete, +but all material here has been reviewed for technical accuracy. + +Keptn software and documentation +is developed and maintained by the Keptn community. +We invite you to join us. diff --git a/docs-new/docs/contribute/docs/linter-requirements/index.md b/docs-new/docs/contribute/docs/linter-requirements/index.md new file mode 100644 index 0000000000..1e2cc18542 --- /dev/null +++ b/docs-new/docs/contribute/docs/linter-requirements/index.md @@ -0,0 +1,95 @@ +# Linter Requirements + +This project uses a set of linters to ensure good code quality. +In order to make proper use of those linters inside an IDE, +the following configuration is required. + +## Golangci-lint + +Further information can also be found in +the [`golangci-lint` documentation](https://golangci-lint.run/usage/integrations/). + +### Visual Studio Code + +In Visual Studio Code the +[Golang](https://marketplace.visualstudio.com/items?itemName=aldijav.golangwithdidi) +extension is required. + +Adding the following lines to the `Golang` extension +configuration file enables all linters used in this project. + +```json +"go.lintTool": { + "type": "string", + "default": "golangci-lint", + "description": "GolangGCI Linter", + "scope": "resource", + "enum": [ + "golangci-lint", + ] +}, +"go.lintFlags": { + "type": "array", + "items": { + "type": "string" + }, + "default": ["--fast", "--fix"], + "description": "Flags to pass to GCI Linter", + "scope": "resource" +}, +``` + +### GoLand / IntelliJ requirements + +* Install either the **GoLand** or **IntelliJ** Integrated Development Environment +(IDE) for the Go programming language, plus the [Go Linter](https://plugins.jetbrains.com/plugin/12496-go-linter) plugin. + +* The plugin can be installed via `Settings` >> `Plugins` >> `Marketplace`, +search for `Go Linter` and install it. +Once installed, make sure that the plugin is using the `.golangci.yml` +file from the root directory. + +* The configuration of `Go Linter` can be found in the `Tools` section +of the settings. + +If you are on Windows, you need to install **make** for the above process to complete. + +> **Note** +When using the make command on Windows, you may receive an `unrecognized command` error for a command that is installed. +This usually indicates that `PATH` for the binary is not set correctly). + +## Markdownlint + +We are using [markdownlint](https://github.com/DavidAnson/markdownlint) to ensure consistent styling +within our Markdown files. +Specifically we are using [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli). + +We are using `GNU MAKE` to ensure the same functionality locally and within our CI builds. +This should allow easier debugging and problem resolution. + +### Markdownlint execution + +To verify that your markdown code conforms to the rules, run the following on your local branch: + +```shell +make markdownlint +``` + +To use the auto-fix option, run: + +```shell +make markdownlint-fix +``` + +### Markdownlint Configuration + +We use the default configuration values for `markdownlint`. + +This means: + +[.markdownlint-cli2.yaml](https://github.com/keptn/lifecycle-toolkit/blob/main/.markdownlint-cli2.yaml) +contains the rule configuration + +We use the default values, so tools like +[markdownlint for VSCode](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) +can be used without additional configuration. diff --git a/docs-new/docs/contribute/docs/local-building/index.md b/docs-new/docs/contribute/docs/local-building/index.md new file mode 100644 index 0000000000..52b37d7d77 --- /dev/null +++ b/docs-new/docs/contribute/docs/local-building/index.md @@ -0,0 +1,81 @@ +# Build Documentation Locally + +## Building the documentation locally + +You can run Docsy locally so that you can view the formatted version +of what you are writing before you push it to github. +We provide a Docsy run environment in a Docker container, +which simplifies the setup +and makes it easier to upgrade your local build environment +as the software is updated. + +To set up a local Docsy build: + +1. Install Docker Desktop: + + * [Install on macOS](https://docs.docker.com/desktop/install/mac-install/) + * [Install on Linux](https://docs.docker.com/desktop/install/linux-install/) + * [Install on Windows](https://docs.docker.com/desktop/install/windows-install/) + +1. Execute the following command from the `docs` folder of your clone: + + ```shell + make server + ``` + + It will continue running in its own shell. + + > **Note** + To utilize the `Makefile`, you must have GNU **make** + available on your local machine. + Versions are available for all the usual Operating Systems. + +1. Start contributing! +Note that Hugo updates the rendered documentation each time you write the file. + +1. Enter the following in a browser to view the website: + + `http://localhost:1314` + + > **Note** + By default, Hugo serves the local docs on port 1313. + We have modified that port for the lifecycle-toolkit docs + to avoid conflicts with the keptn.github.io docs, which use + port 1313 for local builds. + +1. Use Ctrl+C to stop the local Hugo server when you are done. + +1. To restart the continuous build: + + * Restart Docker-Desktop, if necessary + * If changes have been made to the build tools: + * make clone + * make build + * Run `make server` + +### Building markdown files without Hugo + +The Hugo generator described above only renders +the markdown files under the */content/docs* directory. +If you need to render another markdown file +(such as this *CONTRIBUTING.md* file) +to check your formatting, you have the following options: + +* If you are using an IDE to author the markdown text, + use the markdown preview browser for the IDE. +* You can push your changes to GitHub + and use the GitHub previewer (*View Page*). +* You can install and use the + [grip](https://github.com/joeyespo/grip/blob/master/README.md) previewer + to view the rendered content locally. + When *grip* is installed, + you can format the specified file locally + by running the following in its own shell: + + ```shell + grip .md + ``` + + Point your browser at `localhost:6419` to view the formatted file. + The document updates automatically + each time you write your changes to disk. diff --git a/docs-new/docs/contribute/docs/publish/index.md b/docs-new/docs/contribute/docs/publish/index.md new file mode 100644 index 0000000000..fb02893698 --- /dev/null +++ b/docs-new/docs/contribute/docs/publish/index.md @@ -0,0 +1,67 @@ +# Published Doc Structure + +New writing goes to the `main` branch and can be viewed on the Releases -> development dropdown menu. +We have staging and production levels for our documentation which are as follows: + +* **Latest:** official documentation of the current Keptn release + * [link](https://lifecycle.keptn.sh): + This is the build of the `page` branch. + +* **Development:** documentation being staged for the next Keptn release + * [link](https://main.lifecycle.keptn.sh): + This is the latest build of the `main` branch. + +* **Previous versions:** documentation for earlier releases. + These are listed at [link](https://github.com/keptn/lifecycle-toolkit/tree/page/docs/content/en). + +* **Contribute:** current version of the "Contribute" guide + that is available from a tab on the documentation site. + +Let's take a look what happens when your changes are merged in `main` and `page` branch respectively. + +## Latest -- Official documentation (Production) + +This set of documentation pertains to the latest Keptn release and resides within an +isolated branch known as `page`. +When a new version of Keptn is launched, the contents of the `development` +branch are rolled into this branch. +Additionally, it's important to recognize that any +document changes made using the "Edit this page" feature are seamlessly integrated into this branch. + +This uses the `latest` label so that links to a doc page +remain valid across software and documentation updates. + +* build: on each push to `page` with documentation changes +* build-environment: production +* config folder: [production](https://github.com/keptn/lifecycle-toolkit/tree/main/docs/config/production) + +A new version is generated when we push the `main` branch to production to release a new version of the docs page. +This means, that the content of the old version on the `page` branch will be copied over +to a `docs-` folder and the new version will be pushed into the `docs` folder. +This way, no changes or older versions get overwritten. + +## Development documentation (Staging) + +This page contains the documentation being staged for the next Keptn release. +It contains information about new and changed features and functionality +as well as general documentation improvements. +It is built regularly and can be easily accessed from the `Releases` tab on the documentation site. + +* build: on each push to `main` with documentation changes + from a user's local branch, from the github editor, or from codespaces +* build-environment: main +* config folder: [staging](https://github.com/keptn/lifecycle-toolkit/tree/main/docs/config/staging) + +This version represents the pre-release iteration of the documentation for the upcoming Keptn release. +Pull requests originating from a user's local branch, the GitHub editor, or codespaces are merged into this branch. + +When a new Keptn version is officially launched, this branch is elevated to the status of `latest`. +In exceptional cases, a pull request that includes vital documentation enhancements may be discreetly +advanced to `latest` without the need for a software release. + +## Previous Versions + +Keptn documentation is versioned. +By default, the version for the current Keptn release +is displayed on the documentation page but users can select other versions from the Releases tab. +The previous versions of the Keptn Documentation are available [here](https://github.com/keptn/lifecycle-toolkit/tree/page/docs/content/en). diff --git a/docs-new/docs/contribute/docs/source-file-structure/index.md b/docs-new/docs/contribute/docs/source-file-structure/index.md new file mode 100644 index 0000000000..894230d4cf --- /dev/null +++ b/docs-new/docs/contribute/docs/source-file-structure/index.md @@ -0,0 +1,169 @@ +# Source File Structure + +The source files for the Keptn documentation +are stored in the same github repository as the source code. +This page explains how the documentation source files are organized. + +> **Note** The structure of the documentation + and the source code for the documentation is evolving. + You may find small discrepencies between + what is documented here and what is currently implemented. + +## Primary documentation set + +The source for the +[Keptn](https://lifecycle.keptn.sh/docs) +documentation is stored under +the *docs/content/en/docs* directory in the repository. + +The subdirectories correspond to the contents listed in the right frame. +In the order they appear in the rendered docs, the subdirectories are: + +* **intro** (Introduction to the Keptn): + A brief overview of Keptn, its features and use cases, and its history +* **getting-started** (Getting started): + A hands-on exercise that demonstrates the capabilities of Keptn +* **tutorials** (Tutorials): + Additional hands-on exercises to introduce new users to Keptn +* **install** (Installation and Upgrade): + Requirements and instructions for installing and enabling Keptn +* **operate** (Operate Keptn): + Guides about running and managing the Keptn cluster +* **implementing** (User Guides): + This is currently a catch-all section + for guides and how-to material about implementing Keptn features. + It needs to be restructured and subdivided +* **architecture** (Architecture): + Information about how Keptn actually works + + * **components** (Keptn Components) + + * **lifecycle-operator** (Keptn Lifecycle Operator) + * **metrics-operator** (Keptn Metrics Operator) + * **scheduler** (Keptn integration with Scheduling) + + * **deployment-flow** (Flow of deployment) + * **keptn-apps** (KeptnApp and KeptnWorkload) + * **cert-manager** (Keptn Certificate Manager) + +* **crd-ref** (API Reference): + Comprehensive information about all the APIs that define the Keptn CRDs. + This section is auto-generated from source code + and should never be modified in the *docs* directory. + The source for the authored text can be modified + in the source code files for the APIs +* **yaml-crd-ref** (CRD Reference): + Reference pages for the CRs that users must populate. + This is a subset of the CRDs documented in the *API Reference* section +* **migrate** (Migrating to the Keptn): + Information to help users who are migrating to Keptn + from Keptn v1 + +### Working with reference pages + +The Keptn documentation includes two reference sections +that document the Keptn APIs and CRDs. +For background information, see: + +* [Kubernetes API Concepts](https://kubernetes.io/docs/reference/using-api/api-concepts/) +* [Kubernetes API Reference](https://kubernetes.io/docs/reference/kubernetes-api/) + +#### API Reference + +The +[API Reference](../../../reference/api-reference/index.md) +pages are autogenerated from the source code. +This is a comprehensive list of all APIs and resources Keptn uses, +most of which users seldom see. + +Descriptive text for the APIs is authored in the source code itself. +Each operator has its own API library with different versions. +The source locations are: + +* [Lifecycle API](https://github.com/keptn/lifecycle-toolkit/tree/main/lifecycle-operator/apis/lifecycle) +* [Metrics API](https://github.com/keptn/lifecycle-toolkit/tree/main/metrics-operator/api) +* [Options API](https://github.com/keptn/lifecycle-toolkit/tree/main/lifecycle-operator/apis/options) + +The text is coded in a limited form of markdown. + +To regenerate the autogenerated API reference docs, +execute the following script +in the root directory of your `lifecycle-toolkit` clone: + +```shell +./.github/scripts/generate-crd-docs/generate-crd-docs.sh +``` + +#### CRD Reference + +The +[CRD Reference](../../../reference/crd-reference/index.md) +pages +describe the YAML files used to populate resources +for the small set of CRDs that users must populate themselves. +These are currently authored manually +and should provide as much information as possible about the resource. +These are intended to be reference pages that are used regularly +by users after they are familiar with how to use Keptn. +For new users, the +[User Guides](https://lifecycle.keptn.sh/docs/implementing/) +provide introductory material about how to use various features. + +A template to use to create a new CRD Reference page +is available +[here](../templates/yaml-crd-ref-template.md). + +## Contributing guide + +The source for the +[Contributing to Keptn](https://lifecycle.keptn.sh/contribute/) +guides +(which are accessed from the **Contributing** tab on the documentation page) +is stored under the *docs/content/en/contribute* directory. + +The subdirectories correspond to the contents listed in the right frame. +In the order they appear, the subdirectories are: + +* **general** (General information about contributing): + Information that is applicable to all contributors, + whether contributing software or documentation + +* **software** (Software contributions): + Information that is specific to software contributions + +* **docs** (Documentation contributions): + Information that is specific to documentation contributions. + +We also have *CONTRIBUTING.md* files located in the +home directory of the *lifecycle-toolkit* repository +(general and software development information) +and in the *lifecycle-toolkit/docs* directory +(documentation development information only). +These are the traditional locations for contributing information +but the amount of content we have was making them unwieldy +so we are in the process of moving most content from these files +into the *Contributing guide*, +leaving links to the various sections in the *CONTRIBUTING.md* guides. + +## Build strategy + +This section discusses how the individual files and directories +are assembled into the documentation set. +See +[Published Doc Structure](../publish/index.md) +for information about the branches where the documentation is published. + +All files in the directories are built +except for files that are explicitly `ignored` +and files that include the `hidden: true` string in the file's metadata section. + +The order in which the files are displayed +is determined by the value of the `weight` field +in the metadata section of *_index.md*, *index.md*, +and *topic.md* files that are located throughout the directory tree. + +The metadata section of these files contains at least three fields. +As an example, the metadata section for the *Installation and upgrade* section +of the documentation includes the following fields: + +```yaml diff --git a/docs-new/docs/contribute/docs/templates/yaml-crd-ref-template.md b/docs-new/docs/contribute/docs/templates/yaml-crd-ref-template.md new file mode 100644 index 0000000000..d68094617c --- /dev/null +++ b/docs-new/docs/contribute/docs/templates/yaml-crd-ref-template.md @@ -0,0 +1,62 @@ +# CRD name + +Copy this template to create a new CRD reference page. + +1. Replace the variable text in metadata with information for this page +1. Delete these instructions from your file +1. Populate the page with appropriate content + +## Synopsis + +```yaml +apiVersion: +kind: +metadata: + name: +spec: + ... +``` + +## Fields + + + + + + + + + + + + + + + +Fields should be clearly marked as to whether they are +required or optional. +If they are optional, +text should explain the behavior when that field is not populated. + +## Usage + + + + +## Examples + +Include code snippets that illustrate +how this resource is populated. +Code examples should use be embedded links to example source code +so that they will be updated automatically when changes are made to the example. + +## Files + +* Link to subsection for this resource in the "API Reference" + +## Differences between versions + +## See also + +* Links to related reference pages +* Links to related User Guides and other documentation diff --git a/docs-new/docs/contribute/docs/word-list/index.md b/docs-new/docs/contribute/docs/word-list/index.md new file mode 100644 index 0000000000..50cf191042 --- /dev/null +++ b/docs-new/docs/contribute/docs/word-list/index.md @@ -0,0 +1,104 @@ +# Word list + +This document summarizes information +about the proper use of terminology for the Keptn project. + +The Keptn project does not maintain a formal style guide +but should adhere to recommendations in: + +* [CNCF Style Guide](https://github.com/cncf/foundation/blob/main/style-guide.md). + +* The [Kubernetes documentation](https://kubernetes.io/docs/home/) + is a good reference for Kubernetes terms. + In particular: + + * [Concepts](https://kubernetes.io/docs/concepts/) + * [Reference](https://kubernetes.io/docs/reference/) + +* The [Google developer documentation style guide](https://developers.google.com/style) + is a comprehensive reference for technical writers. + In particular: + + * [Word list](https://developers.google.com/style/word-list) + includes good information about words and phrases + that are commonly used in technical documentation + +## Keptn terminology + +### Keptn project + +This is the proper name of the project that was developed +under the code name of "Keptn Lifecycle Toolkit (KLT)". +The earlier project is called "Keptn v1". + +* Keptn is capitalized when used in prose as the name of the project, + although the logo uses a lowercase "k". + Use `keptn` if it is part of a command name, pathname, + an argument to a command or function, etc. + +* As a project name that is trademarked, + you should not use an apostrophe-s to make it a possessive ("Keptn's") + or hyphenate it (as in "Keptn-specific"). + +The Keptn project is a "toolkit" with three use cases, named: + +* Metrics (or Deployment data access) + +* Observability (or Deployment observability) + +* Release lifecycle management (or Orchestrate deployment checks) + +## Kubernetes terminology + +The Keptn documentation frequently uses Kubernetes terminology. +Here are some guidelines for using these terms in Keptn documentation. + +* Do not duplicate information from the Kubernetes documentation + into the Keptn documentation. + We should not be maintaining documentation + for software in other projects and products. + +* Kubernetes concepts and objects (such as workload, job, resource) + should be lowercase unless they are the proper name of an object. + +* The first instance of one of these terms in a section + should be a link to the relevant Kubernetes documentation. + +* Avoid using generic references to Kubernetes documentation. + Instead, link to the particular section + that contains the relevant information. + +* The dictionary of Kubernetes terms that is used by the + Spell checker + is in the `cspell` + [k8s.txt](https://github.com/streetsidesoftware/cspell-dicts/blob/main/dictionaries/k8s/dict/k8s.txt) + file. + Note that all words are listed in all lowercase + so the list can not be used to check capitalization. + +### CRD, resource, etc + +Keptn makes extensive use of Kubernetes +[Custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). +It is important to use the related terminology correctly: + +* A "Resource Definition (RD)" is the definition (or syntax) + of a resource that is part of the official Kubernetes API + +* A "Custom Resource Definition (CRD)" is the definition + (or syntax) of a resource that Keptn (or some other product) + adds to Kubernetes + +* An instance of a CRD or RD that a user creates is a custom resource + or just a resource but not a CRD or RD. + Most of the time, we recommend just using the term "resource". + +* The first occurence of a CRD name in a section should be a link to the + CRD YAML Reference under the right [component](../../../components/index.md) + page if there is one. + Otherwise, it should be a link to the appropriate spot in the + [API Reference](../../../reference/api-reference/index.md) + section. + +* Occurrences of a resource name that are not links to a reference page + should be enclosed in tics so they render as code-case. diff --git a/docs-new/docs/contribute/general/codespace/index.md b/docs-new/docs/contribute/general/codespace/index.md new file mode 100644 index 0000000000..9793e87085 --- /dev/null +++ b/docs-new/docs/contribute/general/codespace/index.md @@ -0,0 +1,42 @@ +# Codespaces + +Use GitHub codespaces as a pre-built and pre-configured development environment. +This is especially useful for Windows users +who may not have `make` installed. +It is also useful for Linux and MacOS users +who may not wish to download tools just to contribute to docs. + +Review [this video](https://www.youtube.com/watch?v=sFNzOhZw7Eg) to see how this works. + +[![Keptn + GitHub codespaces video](https://img.youtube.com/vi/sFNzOhZw7Eg/0.jpg)](https://www.youtube.com/watch?v=sFNzOhZw7Eg) + +As shown in the video, the steps to set up a new Codespace are: + +1. Create a fork of the repository. + Keptn software and documentation are in the + [link](https://github.com/keptn/lifecycle-toolkit) + repository. +1. In your fork, click the green `Code` button +1. Switch to `Codespaces` tab and create a new codespace + +You will be presented with a fully configured environment +with access to all the tools you require +to develop software or documentation for Keptn. + +The interface is similar to that of +[Visual Studio Code](https://code.visualstudio.com/). + +To develop or modify software or documentation, the steps are: + +1. Make your modifications and test those modifications +1. Go back to Codespaces and click on the "Source Control" button on the left +1. Find the file(s) that you modified and click the "**+**" button + to create a commit + - Supply a commit message, adhering to the conventions for Keptn commits + - Sign the commit by clicking the "**...**" button + and selecting "Commit -> Commit Staged" +1. Click the "**...**" button again + and select "Push" to push your changes to your fork +1. Go to the UI for your fork and create a PR in the normal way. +1. After your PR has been merged, + go to your github page, select "Codespaces", and delete this codespace. diff --git a/docs-new/docs/contribute/general/contrib-guidelines-gen/index.md b/docs-new/docs/contribute/general/contrib-guidelines-gen/index.md new file mode 100644 index 0000000000..a837f6ffba --- /dev/null +++ b/docs-new/docs/contribute/general/contrib-guidelines-gen/index.md @@ -0,0 +1,45 @@ +# Contribution Guidelines + +Before using Keptn +as a contributor to the Keptn `lifecycle-toolkit` repository, +it is expected that you comply with the guidelines while +making contributions towards the repository. + +These guidelines are appropriate for both software and documentation. +For additional guidelines that are relevant only to documentation, see +[Contribution guidelines for documentation](../../docs/contrib-guidelines-docs/index.md). + +## Guidelines for contributing + +* Always fork the repository then clone that fork to your local system + rather than clone `main` directly. + Keptn, like most open source projects, + severely restricts who can push changes directly to the `main` branch + to protect the integrity of the repository. +* Smaller PR's are easier to review and so generally get processed more quickly; + when possible, chunk your work into smallish PR's. + However, we recognize that documentation work sometimes requires larger PRs, + such as when writing a whole new section or reorganizing existing files. +* You may want to squash your commits before creating the final PR, + to avoid conflicting commits. + This is **not mandatory**; the maintainers will squash your commits + during the merge when necessary. +* Be sure that the description of the pull request itself + is meaningful and clear. + This helps reviewers understand each commit + and provides a good history after the PR is merged. +* If your PR is not reviewed in a timely fashion, + feel free to post a gentle reminder to the `#keptn-help-contributing` Slack channel. +* Resolve review comments and suggestions promptly. + +If you see a problem and are unable to fix it yourself +or have an idea for an enhancement, +please create an issue on the GitHub repository. + +* Provide specific and detailed information about the problem + and possible solutions to help others understand the issue. +* When reporting a bug, provide a detailed list of steps to reproduce the bug. + If possible, also attach screenshots that illustrate the bug. +* If you want to do the work on an issue, + include that information in your description of the issue + or in a comment to the issue. diff --git a/docs-new/docs/contribute/general/dco/index.md b/docs-new/docs/contribute/general/dco/index.md new file mode 100644 index 0000000000..d80e5c8587 --- /dev/null +++ b/docs-new/docs/contribute/general/dco/index.md @@ -0,0 +1,147 @@ +# DCO + +## Developer Certification of Origin (DCO) + +Keptn requires the Developer Certificate of Origin (DCO) process +to be followed for each commit. +With the DCO, you attest that the contribution adheres +to the terms of the Apache License that covers Keptn +and that you are granting ownership of your work to the Keptn project. + +Licensing is very important to open source projects. +It helps ensure that the software continues to be available under the +terms that the author desired. +Keptn uses [Apache License 2.0](https://github.com/keptn/lifecycle-toolkit/blob/main/LICENSE), +which strikes a balance between open contributions +and allowing you to use the software however you would like to. + +The license tells you what rights the copyright holder gives you. +It is important that the contributor fully understands +what rights they are licensing and agrees to them. +Sometimes the copyright holder is not the contributor, +such as when the contributor is doing work on behalf of a company. + +You must add a Signed-off-by statement for each commit you contribute, +thereby agreeing to the DCO. +The text of the DCO is given here +and available at : + +```text +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +## DCO Sign-Off Methods + +The DCO check runs on each PR to verify +that the commit has been signed off properly. +Your builds will fail and can not be merged if the DCO check fails. + +Do any of the following +to implement the DCO signoff on each commit: + +* [Add **-s** or **--signoff**](#sign-off-with-git-commit--s) + to your usual `git commit` commands +* [Manually add text](#manually-add-text-to-commit-description) + to your commit body +* [Automate DCO](#automate-dco) + +## Sign off with git commit -s + +Use the **-s** or **--signoff** flag to the `git commit` command +to sign off on a commit. +For example: + +```bash +git commit -s -m "my awesome contribution" +``` + +If you forget to add the sign-off, +run the following command to amend the previous commit +with the sign-off: + +```bash +git commit --amend --signoff +``` + +Use the following command +to sign off the last 2 commits you made: + +```bash +git rebase HEAD~2 --signoff +``` + +## Manually add text to commit description + +To sign off on a commit not made with the command line +(such as those made directly with the github editor +or as suggestions made to a PR during review), +you can add text like the following to the commit description block. +You must specify your real name and the email address to use: + + ```text + Signed-off-by: Humpty Dumpty + ``` + +## Automate DCO + +The DCO process is sometimes inconvenient but you can automate it +by creating a pre-commit git hook as follows: + +1. Create the hook: + + ``` bash + touch .git/hooks/prepare-commit-msg + ``` + +2. Add the following to the `prepare-commit-msg` file: + + ```bash + SOB=$(git var GIT_AUTHOR_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p') + grep -qs "^$SOB" "$1" || echo "$SOB" >> "$1" + ``` + +3. Give it execution permissions by calling: + + ```bash + chmod +x ./.git/hooks/prepare-commit-msg + ``` + +## ATTRIBUTION + +* +* +* +* diff --git a/docs-new/docs/contribute/general/git/branch-create/index.md b/docs-new/docs/contribute/general/git/branch-create/index.md new file mode 100644 index 0000000000..598dcb9ded --- /dev/null +++ b/docs-new/docs/contribute/general/git/branch-create/index.md @@ -0,0 +1,48 @@ +# Create local branch + +After you +[fork and clone](../fork-clone/index.md) +the Keptn repository and set `upstream` in your local machine, +you need to create a local branch where you will make your changes. + +## Create a new branch and make your changes + +Be sure that your branch is based on and sync'ed with `main`, +unless you intend to create a derivative PR. +The following sequence of commands does that: + +```console +git checkout main +git pull upstream main +git push origin main +git checkout -b +``` + +Execute the following and check the output +to ensure that your branch is set up correctly: + +```console +git status +``` + +Now you can make your changes, build and test them locally, +then create a PR to add these changes to the documentation set. + +* For documentation changes: + * Do the writing you want to do in your local branch + * Check the formatted version in your IDE + or at `localhost:1314/docs-dev` + to ensure that it is rendering correctly + and that all links are valid.. + See [Build Documentation Locally](../../../docs/local-building/index.md) + for more information. + * Run `make markdownlint-fix` to check and fix the markdown code. + +* For software changes: + * Create the new code in your local branch. + * Create and run unit tests for your new code. + * Run other appropriate test to ensure that your code works correctly. + +When you have completed the checking and testing of your work, +it is time to push your changes and create a PR that can be reviewed. +See [Create PR](../pr-create/index.md) for details. diff --git a/docs-new/docs/contribute/general/git/fork-clone/index.md b/docs-new/docs/contribute/general/git/fork-clone/index.md new file mode 100644 index 0000000000..f1acf6e31c --- /dev/null +++ b/docs-new/docs/contribute/general/git/fork-clone/index.md @@ -0,0 +1,55 @@ +# Fork and clone the repository + +Perform the following steps to create a copy +of the Keptn repository on your local machine: + +1. Fork the Keptn repository: + + * Log into GitHub (or create a GitHub account and then log into it). + * Go to the [Keptn lifecycle-toolkit repository](https://github.com/keptn/lifecycle-toolkit). + * Click the **Fork** button at the top of the screen. + * Choose the user for the fork from the options you are given, + usually your GitHub ID. + + A copy of this repository is now available in your GitHub account. + +2. Get the string to use when cloning your fork: + + * Click the green "Code" button on the UI page. + * Select the protocol to use for this clone (either HTTPS or SSH). + * A box is displayed that gives the URL for the selected protocol. + Click the icon at the right end of that box to copy that URL. + +3. Run the **git clone** command from the shell of a local directory + to clone the forked repository to a directory on your local machine, + pasting in the URl you saved in the previous step. + + For example, if you are using HTTPS: + + ```console + git clone https://github.com//lifecycle-toolkit + ``` + + Or if you are using SSH: + + ```console + git clone git@github.com:/lifecycle-toolkit.git + ``` + + Where <*UserName*> is your GitHub username. + The lifecycle-toolkit directory is now available in the local directory. + +4. Associate your clone with `upstream`. + + * In a shell, go to the root folder of the project + and run *git status* to confirm that you are on the `main` branch. + * Type the following to associate `upstream` with your clone, + pasting in the string for the main repo that you copied above.: + + ```console + git remote add upstream https://github.com/keptn/lifecycle-toolkit.git + ``` + +You are now ready to +[create a local branch](../branch-create/index.md) +and begin to create the software or documentation modifications. diff --git a/docs-new/docs/contribute/general/git/index.md b/docs-new/docs/contribute/general/git/index.md new file mode 100644 index 0000000000..e713764bfd --- /dev/null +++ b/docs-new/docs/contribute/general/git/index.md @@ -0,0 +1,18 @@ +# Working with Git + +Keptn source for software and documentation is stored in the +[Keptn lifecycle-toolkit repository](https://github.com/keptn/lifecycle-toolkit). +Contributions are made using standard Git practices. +This section describes the basic steps required to contribute using Git +and summarizes some standard practices we use with Keptn. + +You can also modify the source using the GitHub editor. +This is very useful when you want to fix a typo +or make some other small change +although be sure so include the DCO signoff. + +If you are doing significant work, +you should fork and clone your own copy of the repository, +make your changes in a local branch, +then push those changes to github where they can be reviewed +and ultimately merged into the product. diff --git a/docs-new/docs/contribute/general/git/pr-create/index.md b/docs-new/docs/contribute/general/git/pr-create/index.md new file mode 100644 index 0000000000..97c6d4ea65 --- /dev/null +++ b/docs-new/docs/contribute/general/git/pr-create/index.md @@ -0,0 +1,196 @@ +# Create PR + +When you have completed the checking and testing of your work +on your local branch as described in +[Create local branch](../branch-create/index.md), +it is time to push your changes and create a PR that can be reviewed. +This is a two-step process: + +1. [Push new content from your local branch](#push-new-content-from-your-local-branch) +1. [Create the PR on the github web site](#create-pr-on-the-github-web-site) + +## Push new content from your local branch + +The steps to push your new content from your local branch +to the repository are: + +1. When you have completed the writing you want to do, + close all files in your branch and run `git status` to confirm + that it correctly reflects the files you have modified, added, and deleted + and does not include any files that you do not want to push. + +1. Switch back to the `main` branch in your repository, + and ensure that it is up to date + with the `main` Keptn branch: + + ```bash + git remote add upstream https://github.com/keptn/lifecycle-toolkit.git + git checkout main + git pull upstream main + ``` + + Then update your feature branch from your local copy of `main` and push it: + + ```bash + git checkout feature/123/foo + git rebase main + git push --set-upstream origin feature/123/foo + ``` + +1. Add and commit your changes. + The `git commit -s` command commits the files + and signs that you are contributing this intellectual property + to the Keptn project. + See the DCO docs for more information. + Here, we commit all modified files but you can specify individual files + to the `git add` command. + + ```console + git add . + git commit -s + ``` + + Use vi commands to add a description of the PR + (should be 80 characters or less) to the commit. + The title text should be prefixed with an appropriate + [commit type](#commit-types) + to conform to our semantic commit scheme. + This title is displayed as the title of the PR in listings. + + You can add multiple lines explaining the PR here but, in general, + it is better to only supply the PR title here; + you can add more information and edit the PR title + when you create the PR on the GitHub UI page. + +1. Push your branch to github. + If you cloned your fork to use SSH, the command is: + + ```console + git push --set-upstream origin + ``` + + > **Note** + You can just issue the `git push` command. + Git responds with an error message + that gives you the full command line to use; + you can copy this command and paste it into your shell to push the content. + +## Create PR on the github web site + +To create the actual PR that can be reviewed +and eventually merged, go to the + page. +You should see a yellow box that identifies your recent pushes. +Click the `Compare & pull request` button in that box +to open a PR template that you can populate. + +> **Note** + The PR template can also be found at `.github/pull_request_template.md`. + +You need to provide the following information: + +* Title for the PR. + Follow the + [conventional commit guidelines](https://www.conventionalcommits.org/en/v1.0.0/) + for your PR title. + * Title should begin with an appropriate + [commit type](#commit-types).feature type. + * The first word after the feature type should be lowercase. + + An example for a pull request title is: + + ```bash + feat(api): new endpoint for feature X + ``` + +* Full description of what the PR is about. + + * Link to relevant GitHub issue(s). + Use the phrase `Closes ` for this link; + is ensures that the issue is closed when this PR is merged. + this PR does not completely satisfy the issue, + e some other phrasing for the link to the issue. + * Describe what this PR does, + including related work that will be in other PRs. + * If you changed something that is visible to the user, + add a screenshot. + * Describe tests that are included or were run to test this PR. + * Anything else that will help reviewers understand + the scope and purpose of this PR. + +* If you have **breaking changes** in your PR, + it is important to note them in both the PR description + and in the merge commit for that PR. + + When pressing "squash and merge", + you have the option to fill out the commit message. + Please use that feature to add the breaking changes according to the + [conventional commit guidelines](https://www.conventionalcommits.org/en/v1.0.0/). + Also, please remove the PR number at the end and just add the issue number. + + An example for a PR with breaking changes and the according merge commit: + + ```bash + feat(bridge): New button that breaks other things (#345) + + BREAKING CHANGE: The new button added with #345 introduces + new functionality that is not compatible with the previous + type of sent events. + ``` + + If your breaking change can be explained in a single line, + you can also use this form: + + ```bash + feat(bridge)!: New button that breaks other things (#345) + ``` + + Following these guidelines helps us create automated releases + where the commit and PR messages are directly used in the changelog. + +When you have filled in the PR template, +you should also quickly scroll down to see the changes +that are being made with this commit +to ensure that this PR contains what you want reviewed. + +When you are satisfied that your PR is ready for review, +click the `Create pull request` button. + +### Commit Types + +**Type** can be: + +* `feat`: a new feature +* `fix`: a bug fix +* `build`: changes that affect the build system or external dependencies +* `chore`: other changes that don't modify source or test files +* `ci`: changes to our CI configuration files and scripts +* `docs`: documentation only changes +* `perf`: a code change that improves performance +* `refactor`: a code change that neither fixes a bug nor adds a feature +* `revert`: reverts a previous commit +* `style`: changes that do not affect the meaning of the code +* `test`: adding missing tests or correcting existing tests + +## Check PR build + +As soon as you create the PR, +a number of tests and checks are run. +Be sure to check the results immediately +and fix any problems that are found. +Click the `Details` link on the line for each each failed test +to get details about the errors found. + +The most common errors for documentation PRs are: + +* Markdown errors found by `markdownlint`. + Most of these can be fixed + by running `make markdownlint-fix` on your local branch + then pushes the changes. +* Cross-reference errors. + To quickly find the errors in the report, + search for the `dead` string on the `Details` page. + +When you have resolved all build errors +you move into the +[PR review process](../review/index.md). diff --git a/docs-new/docs/contribute/general/git/review/index.md b/docs-new/docs/contribute/general/git/review/index.md new file mode 100644 index 0000000000..cb980c1d11 --- /dev/null +++ b/docs-new/docs/contribute/general/git/review/index.md @@ -0,0 +1,67 @@ +# PR review process + +After you +[create your PR](../pr-create/index.md), +your PR must be approved and then merged +before it becomes part of the Keptn product. +This page discusses what you need to do during the review phase. + +GitHub automatically assigns reviewers to your PR. +You can also tag other people in the description or comments. + +Your PR will usually be reviewed within a couple of days, +but feel free to let us know about your PR +[via Slack](https://cloud-native.slack.com/channels/keptn-lifecycle-toolkit-dev). + +You may want to record the PR number somewhere for future reference +although you can always find the PR in the GitHub lists of open and closed PRs. + +## Draft (WIP) PRs + +You may want to create a PR with work that is not ready for final review. +This happens when you want people to provide feedback on some of the work +before you finish the PR +or to protect the work you have done. + +If this PR is not ready for review, click the "Still in progress? +s Convert to draft" string under the list of reviewers. +People can review the content but can not merge the PR +until you remove the "Draft" status. +The block of the PR that reports on checks will include the following item: + +```console +This pull request is still a work in progress +Draft pull requests cannot be merged. +``` + +When the PR is ready to be reviewed, approved, and merged, +click the "Ready to review" button to remove the "Draft" status. +If you added "WIP" or "Draft" to the PR title, remove it now. + +## Respond to review comments and suggestions + +Watch for any comments that may be added by reviewers and implement or +respond to the recommended changes as soon as possible. +You should also check the build reports daily +to ensure that all tests are still passing. + +* If a reviewer makes a GitHub suggestion and you agree with the change, + click "Accept this change" to create a commit for that modification. + Remember to include the DCO sign-off information in the commit message. + +* You can make other changes using the GitHub editor. + +* You can also work in your local branch to make modifications. + However, if the PR has been modified on github, + be sure to `pull` the changes back to your local branch + before working in your local branch. + +When your PR has the appropriate approvals, +it will be merged and the revised content should be published on the +website (as part of the `development` release) +within a few minutes. +You can now delete your local branch with the following command: + +```console +git branch -d +``` diff --git a/docs-new/docs/contribute/general/index.md b/docs-new/docs/contribute/general/index.md new file mode 100644 index 0000000000..7ecb26a0ba --- /dev/null +++ b/docs-new/docs/contribute/general/index.md @@ -0,0 +1,9 @@ +# General information about contributing + +This section is under development. +Contents are not complete, +but all material here has been reviewed for technical accuracy. + +Keptn software and documentation +is developed and maintained by the Keptn community. +We invite you to join us. diff --git a/docs-new/docs/contribute/general/technologies/index.md b/docs-new/docs/contribute/general/technologies/index.md new file mode 100644 index 0000000000..64b2acfca4 --- /dev/null +++ b/docs-new/docs/contribute/general/technologies/index.md @@ -0,0 +1,63 @@ +# Technologies and concepts you should know + +You should understand some related technologies +to effectively use and contribute to Keptn. +This section provides links to some materials that can help your learning. +The information has been gathered from the community and is subject to alteration. +If you have suggestions about additional content that should be included in this list, +please submit an issue. + +## Kubernetes + +Keptn runs on Kubernetes and primarily works with deployments that run on Kubernetes +so a good understanding of Kubernetes is essential +for working with and contributing to Keptn. + +* **Understand the basics of Kubernetes** + * [ ] [Kubernetes official documentation](https://kubernetes.io/docs/concepts/overview/) + * [ ] [Kubernetes For Beginner](https://youtu.be/X48VuDVv0do) +* **Kubernetes Architecture** + * [ ] [Philosophy](https://youtu.be/ZuIQurh_kDk) + * [ ] [Kubernetes Deconstructed: Understanding Kubernetes by Breaking It Down](https://www.youtube.com/watch?v=90kZRyPcRZw) +* **CRD** + * [ ] [Custom Resource Definition (CRD)](https://www.youtube.com/watch?v=xGafiZEX0YA) + * [ ] [Kubernetes Operator simply explained in 10 mins](https://www.youtube.com/watch?v=ha3LjlD6g7g) + * [ ] [Writing Kubernetes Controllers for CRDs](https://www.youtube.com/watch?v=7wdUa4Ulwxg) +* **Kube-builder Tutorial** + * [ ] [book.kubebuilder.io](https://book.kubebuilder.io/introduction.html) +* **Isitobservable** + * [ ] Keptn has tight integrations with Observability tools and therefore knowing how to _Observe a System_ is important. + * [ ] [Isitobservable website](https://isitobservable.io/) + * [ ] [Is it Observable? + with Henrik Rexed](https://www.youtube.com/watch?v=aMwk2qo0v40) + +## Development tools + +* **Go language** + Most of the Keptn software and many of the test tools + are written in the Go language. + * [ ] [Go web page](https://go.dev/) + has tutorials and documentation. + * [ ] [Ginkgo library](https://github.com/onsi/ginkgo/blob/master/README.md) + is used with the + [Gomega matcher](https://onsi.github.io/gomega/) + to implement component tests and end-to-end tests. +* **KUTTL (KUbernetes Test TooL)** + Some test tools are written in KUTTL + * [ ] [KUTTL web page](https://kuttl.dev/) + has information to get you started +* **Markdown** + Keptn documentation is authored in Markdown + and processed with Hugo using the `docsy` theme. + * [ ] [Markdown Guide](https://www.markdownguide.org/) + +## Understanding SLO, SLA, SLIs + +* **Overview** + * [ ] [Overview](https://www.youtube.com/watch?v=tEylFyxbDLE) + * [ ] [The Art of SLOs (Service Level Objectives)](https://www.youtube.com/watch?v=E3ReKuJ8ewA) + +### Operator SDK + +* **Go-based Operators** + * [ ] [Go operator tutorial from RedHat](https://docs.okd.io/latest/operators/operator_sdk/golang/osdk-golang-tutorial.html) diff --git a/docs-new/docs/contribute/index.md b/docs-new/docs/contribute/index.md new file mode 100644 index 0000000000..70d2f86e4b --- /dev/null +++ b/docs-new/docs/contribute/index.md @@ -0,0 +1,9 @@ +# Contributing to Keptn + +This section is under development. +Contents are not complete, +but all material here has been reviewed for technical accuracy. + +Keptn software and documentation +is developed and maintained by the Keptn community. +We invite you to join us. diff --git a/docs-new/docs/contribute/software/dev-environ/index.md b/docs-new/docs/contribute/software/dev-environ/index.md new file mode 100644 index 0000000000..ade32b05f2 --- /dev/null +++ b/docs-new/docs/contribute/software/dev-environ/index.md @@ -0,0 +1,177 @@ +# Software development environment + +This page gives instructions and hints for setting up a development environment +and then develop, test, and deploy your software changes in that environment. +This material was presented at the +11 September 2023 New Contributors meeting. +You can view the video +[here](https://www.youtube.com/watch?v=UcmULstMYXQ). + +To prepare to contribute to the Keptn project, we recommend that you: + +* Study the [Keptn documentation](https://lifecycle.keptn.sh/docs/) + to understand what Keptn does and how it works. +* Familiarize yourself with the + [lifecycle-toolkit](https://github.com/keptn/lifecycle-toolkit) + repository, which is the primary repository for + Keptn software and documentation. + In particular, study the sections for the four main Keptn components: + + * [lifecycle-operator](https://github.com/keptn/lifecycle-toolkit/tree/main/lifecycle-operator) + * [metrics-operator](https://github.com/keptn/lifecycle-toolkit/tree/main/metrics-operator) + * [scheduler](https://github.com/keptn/lifecycle-toolkit/tree/main/scheduler) + * [keptn-cert-manager](https://github.com/keptn/lifecycle-toolkit/tree/main/keptn-cert-manager) + + Each of these is described in the + [Architecture](../../../components/index.md) + section of the documentation + and most include a *README* file with more information. +* Study the material in + [Technologies and concepts you should know](../../general/technologies/index.md). +* Create an account for yourself on + [GitHub](https://github.com) + if you do not already have an account. +* Set up a fork of the [lifecycle-toolkit](https://github.com/keptn/lifecycle-toolkit) repository to use with your development. + +## View repository + +When you view the +[lifecycle-toolkit](https://github.com/keptn/lifecycle-toolkit) +repository, you see that Keptn is composed of multiple components, +each of which is discussed in the Architecture +[Architecture](../../../components/index.md) +documentation: + +* Three Kubernetes operators + * `metrics-operator` + * `lifecycle-operatory` + * `cert-manager` +* Keptn `scheduler` + +At the top level of the repository, +you also see the `runtimes` directory. +This defines the runners that you can use when defining +tasks to be run either pre- or post-deployment. +These are discussed in +[Runners and containers](../../../guides/tasks.md#runners-and-containers). + +## Install software + +To test and develop software for the Keptn project, +you need to install the following on your system: + +* [**Docker**](https://docs.docker.com/get-docker/): a tool for containerization, + which allows software applications to run in isolated environments + and makes it easier to deploy and manage them. +* A Kubernetes cluster running an appropriate version of Kubernetes. + See [Supported Kubernetes versions](../../../installation/index.md#supported-kubernetes-versions) + for details. + Most contributors create a local + Kubernetes-in-Docker(KinD) cluster. + This is adequate for developing software for Keptn. + See + [Kubernetes cluster](../../../installation/k8s.md#create-local-kubernetes-cluster) + for instructions. +* [**kubectl**](https://kubernetes.io/docs/tasks/tools/): + a command-line interface tool used for deploying + and managing applications on Kubernetes clusters. +* [**kustomize**](https://kustomize.io/): a tool used + for customizing Kubernetes resource configurations + and generating manifests. +* [**Helm**](https://helm.sh/): a package manager for Kubernetes + that simplifies the deployment and management of applications + on a Kubernetes cluster. +* [**Go-lang**](https://go.dev/): the language used to code the Keptn software. + +## First steps + +1. Follow the instructions in + [Fork and clone the repository](../../general/git/fork-clone/index.md) + to get a local copy of the software. + +1. Keptn provides a tool that deploys the development version of the software + on your Kubernetes cluster and pushes the built image to your private repository. + You identify your private repository with the `RELEASE_REGISTRY=` argument + and can add any `TAG` arguments you like. + For example, the following command builds the environment + and pushes the image to the `docker.io/exampleuser` github repository: + + ```shell + make build-deploy-dev-environment RELEASE_REGISTRY=docker.io/exampleuser TAG=main + ``` + + The build commands are defined in the + [Makefile](https://github.com/keptn/lifecycle-toolkit/blob/main/Makefile) + located in the root directory of your clone. + This file includes a number of environment variables + that can be specified as required. + +1. After this runs, verify that pods are running on your Kubernetes cluster + for the four components of the product. + +## Code your changes + +You are now ready to make your changes to the source code. + +1. Follow the instructions in + [Create local branch](../../general/git/branch-create/index.md) + to create a branch for your changes. + +1. Make your changes to the appropriate component. + +1. Deploy the component you modified and push the image to your private Github repository. + Note that you do not need to rebuild all components, + only the one you modified. + For example, if your modifications are to the `metrics-operator`, run: + + ```shell + make build-deploy-metrics-operator RELEASE_REGISTRY=docker.io/exampleuser TAG=my-feature + ``` + +## Testing + +Keptn includes a set of tests that are run on each PR that is submitted. +We require that all changes pass +unit tests, component tests, end-to-end tests, and integration tests +before you create a PR with your changes. + +If your change introduces a new feature, +you may need to update the test suites to cover your changes. +These tests use basic go-library, Ginkgo or KUTTL tests. +You can ask the maintainers to tell you where to put your additional test data. + +Tests are run on your local machine. +Study the detailed log that is produced to identify why the test failed. +Study these errors, modify your code, and rerun the test until it passes. + +1. Use your IDE to run unit tests on your code. + +1. Run the integration tests from the root directory of your clone: + + ```shell + make integration-test-local + ``` + + `integration-test-local` cleans up after the test. + +1. From the `lifecycle-operator` directory, run the component test: + + ```shell + make component-test + ``` + +1. From the `lifecycle-operator` directory, run the end-to-end tests: + + ```shell + make e2e-test + ``` + +## Create and manage the PR + +When all the tests have passed, +you can follow the instructions in +[Create PR](../../general/git/pr-create/index.md) +to create your PR. +Be sure to monitor your PR as discussed in +[PR review process](../../general/git/review/index.md) +until it is merged. diff --git a/docs-new/docs/contribute/software/index.md b/docs-new/docs/contribute/software/index.md new file mode 100644 index 0000000000..95afc8b807 --- /dev/null +++ b/docs-new/docs/contribute/software/index.md @@ -0,0 +1,9 @@ +# Software contributions + +This section is under development. +Contents are not complete, +but all material here has been reviewed for technical accuracy. + +Keptn software and documentation +is developed and maintained by the Keptn community. +We invite you to join us. diff --git a/docs-new/docs/core-concepts/assets/dynatrace_dora_dashboard.png b/docs-new/docs/core-concepts/assets/dynatrace_dora_dashboard.png new file mode 100644 index 0000000000..3318a4303f Binary files /dev/null and b/docs-new/docs/core-concepts/assets/dynatrace_dora_dashboard.png differ diff --git a/docs-new/docs/core-concepts/index.md b/docs-new/docs/core-concepts/index.md new file mode 100644 index 0000000000..e1bffa6a7f --- /dev/null +++ b/docs-new/docs/core-concepts/index.md @@ -0,0 +1,137 @@ +# Core Concepts + +Keptn integrates seamlessly with cloud-native deployment tools +such as ArgoCD, Flux, and Gitlab +to bring application awareness to your Kubernetes cluster. +Keptn supplements the standard deployment tools +with features to help you ensure that your deployments are in +a healthy state. + +For information about the history of the Keptn project, see the +[Keptn Lifecycle Toolkit is now Keptn!](https://medium.com/keptn/keptn-lifecycle-toolkit-is-now-keptn-e0812217bf46) +blog. + +Keptn includes multiple features +that can be implemented independently or together. +It targets three main use cases: +Metrics, Observability, and Release lifecycle management. + +## Metrics + +The Keptn metrics feature extends the functionality of +[Kubernetes metrics](https://kubernetes.io/docs/concepts/cluster-administration/system-metrics/): + +* Allows you to define metrics + from multiple data sources in your Kubernetes cluster. + +* Supports deployment tools like Argo, Flux, KEDA, HPA, or + Keptn for automated decision-making based on observability data. + +* Handles observability data from multiple instances + of multiple observability solutions + – Prometheus, Dynatrace, Datadog and others – + as well as data that comes directly from your cloud provider + such as AWS, Google, or Azure. + +* Enhances the Kubernetes + [Horizontal Pod Autoscaling](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) + facility. + +The Keptn metrics server unifies and standardizes +access to data from various sources, +simplifying configuration and integration into a single set of metrics. + +To learn more, see: + +* [Getting started with Keptn metrics](../getting-started/metrics.md) +* [Keptn Metrics](../guides/evaluatemetrics.md) User Guide + +## Observability + +Keptn ensures observability for Kubernetes deployments +by creating a comprehensive trace +of all Kubernetes activities within a deployment. +Keptn observability makes it easy to understand +deployment durations and failures across multiple deployment strategies. + +* Provides observability data for standard Kubernetes [workload](https://kubernetes.io/docs/concepts/workloads/) resources + as well as + [KeptnApp](../reference/crd-reference/app.md) + resources (which connect logically related [workloads](https://kubernetes.io/docs/concepts/workloads/)) + using different deployment strategies. + +* Captures + [DORA metrics](../guides/dora.md) + and exposes them as OpenTelemetry metrics out of the box. + +* Reports traces and custom Keptn metrics from configured data providers + using OpenTelemetry. + +* Enables monitoring of new logs from log monitoring solutions. + +* Information can be displayed on standard dashboard tools + like Grafana. + +Keptn is tool- and vendor neutral +and does not depend on particular tooling. +Keptn emits signals at every stage +([Kubernetes events](https://kubernetes.io/docs/reference/kubernetes-api/cluster-resources/event-v1/), +[CloudEvents](https://cloudevents.io/), and +OpenTelemetry metrics and traces) +to ensure that your deployments are observable. + +To learn more, see: + +* [Getting started with Keptn Observability](../getting-started/observability.md) +* [Standardize observability](usecase-observability.md/) +* [DORA metrics](../guides/dora.md) User Guide +* [OpenTelemetry observability](../guides/otel.md) User Guide + +## Release lifecycle management + +The Release lifecycle management tools run in conjunction +with the standard Kubernetes deployment tools +to make deployments more robust. +Keptn "wraps" a standard Kubernetes deployment +with the capability to automatically handle issues +before and after the actual deployment. + +These tools run checks and tasks before or after deployment initiation. + +* Pre-deployment tasks such as checking for dependent services, + image scanning, and setting the cluster to be ready for the deployment. + +* Pre-deployment evaluations such as checking whether the cluster + has enough resources for the deployment. + +* Post-deployment tasks such as triggering tests, + triggering a deployment to another cluster, + or sending notifications that the deployment succeeded or failed. + +* Post-deployment evaluations to evaluate the deployment, + evaluate test results, + or confirm software health against SLOs + like performance and user experience. + +All `KeptnTask` resources that are defined by `KeptnTaskDefinition` resources +at the same level (either pre-deployment or post-deployment) run in parallel. +Task sequences that are not part of the lifecycle workflow +should be handled by the pipeline engine tools rather than Keptn. +A `KeptnTask` resource can be defined to run multiple executables +(functions, programs, and scripts) +that are part of the lifecycle workflow. +The executables within a `KeptnTask` resource +run in sequential order. + +Keptn tasks and evaluations can be run +for either a Kubernetes [workload](https://kubernetes.io/docs/concepts/workloads/) (single service) resource +or a +[KeptnApp](../reference/crd-reference/app.md) resource, +which is a single, cohesive unit that groups multiple [workloads](https://kubernetes.io/docs/concepts/workloads/). +For more information, see: + +* [Getting started with release lifecycle management](../getting-started/lifecycle-management.md) +* [Deployment tasks](../guides/tasks.md) User Guide +* [Evaluations](../guides/evaluations.md) User Guide +* [Manage release lifecycle](usecase-orchestrate.md) +* [KeptnApp and KeptnWorkload resources](../components/lifecycle-operator/keptn-apps.md) diff --git a/docs-new/docs/core-concepts/usecase-observability.md b/docs-new/docs/core-concepts/usecase-observability.md new file mode 100644 index 0000000000..a30ef12224 --- /dev/null +++ b/docs-new/docs/core-concepts/usecase-observability.md @@ -0,0 +1,143 @@ +# Standardize observability + +Keptn makes any Kubernetes deployment observable. +In other words, it creates a distributed, end-to-end trace +of everything Kubernetes does in the context of a Deployment. +It provides this information +for all applications running in your cluster, +and includes information about +everything Kubernetes does in the context of a deployment. +To do this, +Keptn introduces the concept of an `application`, +which is an abstraction that connects multiple +workloads that logically belong together, +even if they use different deployment strategies. + +This means that: + +- You can readily see why a deployment takes so long + or why it fails, even when using multiple deployment strategies. +- Keptn can capture DORA metrics and expose them as OpenTelemetry metrics + +The observability data is an amalgamation of the following: + +- DORA metrics are collected out of the box when Keptn is enabled +- OpenTelemetry runs traces that show + everything that happens in the Kubernetes cluster +- Custom Keptn metrics that you can use to monitor + information from all the data providers configured in your cluster + +All this information can be displayed with dashboard tools +such as Grafana. + +## Using this exercise + +This exercise shows how to standardize access +to the observability data for your cluster. +It is based on the +[simplenode-dev](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd) +example. + +This is the second of three exercises in the +[Introducing Keptn](index.md) +series: + +- In the + [Getting started with Keptn metrics](../getting-started/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. +- In + [Manage release lifecycle](usecase-orchestrate.md), + you learn how to implement + pre- and post-deployment tasks and evaluations + to orchestrate the flow of all the [workloads](https://kubernetes.io/docs/concepts/workloads/) + that are part of your `application`. + +This exercise shows how to standardize access +to the observability data for your cluster. + +If you are installing Keptn on an existing cluster +or on a local cluster you are creating for this exercise, +you need to do the following: + +1. Follow the instructions in + [Install and update](../installation/index.md) + to install and enable Keptn on your cluster. +1. Follow the instructions in + [Basic annotations](../guides/integrate.md#basic-annotations) + to integrate Keptn into your Kubernetes cluster + by applying basic annotations + to your [workload](https://kubernetes.io/docs/concepts/workloads/) resources. + and to create appropriate + [KeptnApp](../reference/crd-reference/app.md) + resources that aggregate + all the [workloads](https://kubernetes.io/docs/concepts/workloads/) for a logical deployment into a single resource. + +## DORA metrics + +DORA metrics are an industry-standard set of measurements +about your deployments. + +Keptn starts collecting these metrics +as soon as you annotate the `Deployment` resource. +See +[DORA metrics](../guides/dora.md) +for more details. + +## Using OpenTelemetry + +Keptn extends the Kubernetes +primitives to create OpenTelemetry data +that connects all your deployment and observability tools +without worrying about where it is stored and where it is managed. +OpenTelemetry traces collect data as Kubernetes is deploying the changes, +which allows you to trace everything done in the context of that deployment. + +- You must have an OpenTelemetry collector installed on your cluster. + See + [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) + for more information. +- Follow the instructions in + [OpenTelemetry observability](../guides/otel.md) + to configure where your OpenTelemetry data is sent. + This requires you to define a [KeptnConfig](../reference/crd-reference/config.md) resource + that defines the URL and port of the OpenTelemetry collector. + For our example, this is in the + [keptnconfig.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/setup/keptn/keptnconfig.yaml) + file. + +## Keptn metrics + +You can supplement the DORA Metrics and OpenTelemetry information +with information you explicitly define using Keptn metrics. +The +[Getting started with Keptn metrics](../getting-started/metrics.md) +exercise discusses how to define Keptn metrics. + +## View the results + +To start feeding observability data for your deployments +onto a dashboard of your choice: + +1. Modify either your `Deployment` or `KeptnApp` resource yaml file + to increment the version number +1. Commit that change to your repository. + +Note that, from the `KeptnApp` YAML file, +you can either increment the version number of the application +(which causes all [workloads](https://kubernetes.io/docs/concepts/workloads/) to be rerun and produce observability data) +or you can increment the version number of a single [workload](https://kubernetes.io/docs/concepts/workloads/), +(which causes just that [workload](https://kubernetes.io/docs/concepts/workloads/) +to be rerun and produce observability data). + +The videos that go with this exercise show how the +DORA, OpenTelemetry, and Keptn metrics information +appears on a Grafana dashboard with +[Jaeger](https://grafana.com/docs/grafana-cloud/data-configuration/metrics/prometheus-config-examples/the-jaeger-authors-jaeger/). + +If you also have the Jaeger extension for Grafana installed on your cluster, +you can view the full end-to-end trace for everything +that happens in your deployment. +For more information, see +[Monitoring Jaeger](https://www.jaegertracing.io/docs/1.45/monitoring/). diff --git a/docs-new/docs/core-concepts/usecase-orchestrate.md b/docs-new/docs/core-concepts/usecase-orchestrate.md new file mode 100644 index 0000000000..50a01832e9 --- /dev/null +++ b/docs-new/docs/core-concepts/usecase-orchestrate.md @@ -0,0 +1,178 @@ +# Manage release lifecycle + +In this exercise, we will configure Keptn +to run deployment checks as part of your deployment. +Whether you are deploying your software with +Argo, Flux, another deployment engine, or even `kubectl apply`, +Keptn can do the following: + +* Pre-deploy: Validate external dependencies, + confirm that images are scanned, and so forth + +* Post-deploy: Execute tests, notify stakeholders, + promote to the next stage + +* Automatically validate against your SLO (Service Level Objectives) + +Keptn sits on top of the Kubernetes scheduler +and can do the following: + +* Trace the deployment from start to end +* Keptn is application aware, + so can extend the deployment with tasks and evaluations that + are run either before or after your whole application starts the deployment + or at the individual [workload](https://kubernetes.io/docs/concepts/workloads/) level. +* Validate any Keptn metric, + either pre- or post-deployment, + using the metrics from the Keptn Metrics Server introduced in + [Getting started with Keptn metrics](../getting-started/metrics.md). + +This means that you can be sure that the environment is healthy +and has adequate resources before you begin the deployment. +After the deployment succeeds, +use Keptn metrics to confirm that your deployed software is really healthy -- +not just that the pods are running but validate against SLOs +such as performance and user experience. +You can also check for new logs that came in from a log monitoring solution. + +## Using this exercise + +This exercise shows how to implement +pre- and post-deployment evaluations and tasks +for your application. +It is based on the +[simplenode-dev](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd) +example. + +The steps to implement pre- and post-deployment orchestration are: + +* [Using this exercise](#using-this-exercise) +* [Define evaluations to be performed pre- and post-deployment](#define-evaluations-to-be-performed-pre--and-post-deployment) +* [Define tasks to be performed pre- and post-deployment](#define-tasks-to-be-performed-pre--and-post-deployment) +* [Integrate evaluations and tasks into the cluster](#integrate-evaluations-and-tasks-into-the-cluster) + +This is the third of three exercises in the +[Introducing Keptn](index.md) +series. +You may want to complete the other exercises before doing this exercise +although that is not required: + +* In the + [Getting started with Keptn metrics](../getting-started/metrics.md) + exercise, you learn how to define and use Keptn metrics. +* In [Standardize observability](usecase-observability.md), + you learn how to standardize access + to the observability data for your cluster. + +If you are installing Keptn on an existing cluster +or in a local cluster you are creating for this exercise +and did not previously set up your cluster for the +[Standardize observability](usecase-observability.md) exercise, +you need to do the following: + +1. Follow the instructions in + [Install and update](../installation/index.md) + to install and enable Keptn on your cluster. +1. Follow the instructions in + [Annotate workload](../guides/integrate.md#basic-annotations) + to integrate Keptn into your Kubernetes cluster + by applying basic annotations to your `Deployment` resource. + This also creates appropriate + [KeptnApp](../reference/crd-reference/app.md) resources + which aggregate [workloads](https://kubernetes.io/docs/concepts/workloads/) that are combined into the released product, + regardless of the tools being used. + +## Define evaluations to be performed pre- and post-deployment + +An `evaluation` is a KeptnMetric that has a defined target value. +Evaluations are resources that are defined in a +[KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) +yaml file. +In our example, evaluations are defined in the +[keptn-evaluations.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-evaluations.yaml) +file. +For example, the definition of the `evaluate-dependencies` evaluation +looks like this: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnEvaluationDefinition +metadata: + name: evaluate-dependencies + namespace: simplenode-dev +spec: + objectives: + - keptnMetricRef: + name: available-cpus + namespace: simplenode-dev + evaluationTarget: ">4" +``` + +You see that the `available-cpus` metric is defined in the +[keptn-metric.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-metric.yaml) +file. +The `evaluationTarget` is set to be `>4`, +so this evaluation makes sure that more than 4 CPUs are available. +You could include objectives and additional metrics in this evaluation. + +## Define tasks to be performed pre- and post-deployment + +Tasks are resources that are defined in a +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) +file. +In our example, the tasks are defined in the +[keptn-tasks.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-tasks.yaml) +file. +As an example, +we have a `notify` task that composes some Markdown text +to be sent as Slack notifications +The `KeptnTaskDefinition` looks like this: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: notify +spec: + function: + inline: + code: | + + secureParameters: + secret: slack-notification +``` + +The code to be executed is expressed as a +[Deno](https://deno.com) +script, which uses JavaScript syntax. +It can be embedded in the definition file +or pulled in from a remote webserver that is specified. +For this example, the code to be executed is embedded in this file +although, in practice, +this script would probably be located on a remote webserver. + +Note that, beginning with Keptn 0.8.0, +you can also use Python 3 to define your task, +or you can define a standard Kubernetes container +that uses the image, runner, and runtime dependencies that you choose. +For more information, see +[Working with Keptn tasks](../guides/tasks.md). + +You can view the actual JavaScript code for the task in the repository. +You see that "context" is important in this code. +This refers to the context in which this code executes -- +for which application, for which version, for which workload. + +Because the slack server that is required to execute this task +is protected by a secret, the task definition also specifies that secret. + +## Integrate evaluations and tasks into the cluster + +Follow the instructions in +[Annotate workload](../guides/integrate.md#pre--and-post-deployment-checks) +to integrate the evaluations and tasks you defined +into the cluster +by applying annotations to the `Deployment` resource. +See the +[simplenode-dev-deployment.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/simplenode-dev-deployment.yaml) +file for an example. diff --git a/docs-new/docs/getting-started/assets/deploymenttrace.png b/docs-new/docs/getting-started/assets/deploymenttrace.png new file mode 100644 index 0000000000..0cf22269df Binary files /dev/null and b/docs-new/docs/getting-started/assets/deploymenttrace.png differ diff --git a/docs-new/docs/getting-started/assets/grafana.png b/docs-new/docs/getting-started/assets/grafana.png new file mode 100644 index 0000000000..730c03dd8e Binary files /dev/null and b/docs-new/docs/getting-started/assets/grafana.png differ diff --git a/docs-new/docs/getting-started/assets/install01.png b/docs-new/docs/getting-started/assets/install01.png new file mode 100644 index 0000000000..a793d6a16e Binary files /dev/null and b/docs-new/docs/getting-started/assets/install01.png differ diff --git a/docs-new/docs/getting-started/assets/install02.png b/docs-new/docs/getting-started/assets/install02.png new file mode 100644 index 0000000000..9ad850ad9f Binary files /dev/null and b/docs-new/docs/getting-started/assets/install02.png differ diff --git a/docs-new/docs/getting-started/assets/keptnapplications.png b/docs-new/docs/getting-started/assets/keptnapplications.png new file mode 100644 index 0000000000..c2824b30b8 Binary files /dev/null and b/docs-new/docs/getting-started/assets/keptnapplications.png differ diff --git a/docs-new/docs/getting-started/assets/keptnprommetrics.png b/docs-new/docs/getting-started/assets/keptnprommetrics.png new file mode 100644 index 0000000000..8d6c2cf650 Binary files /dev/null and b/docs-new/docs/getting-started/assets/keptnprommetrics.png differ diff --git a/docs-new/docs/getting-started/assets/nginx.png b/docs-new/docs/getting-started/assets/nginx.png new file mode 100644 index 0000000000..8ae885f9a0 Binary files /dev/null and b/docs-new/docs/getting-started/assets/nginx.png differ diff --git a/docs-new/docs/getting-started/assets/podtatohead.png b/docs-new/docs/getting-started/assets/podtatohead.png new file mode 100644 index 0000000000..440d9d995d Binary files /dev/null and b/docs-new/docs/getting-started/assets/podtatohead.png differ diff --git a/docs-new/docs/getting-started/assets/trace-failed.png b/docs-new/docs/getting-started/assets/trace-failed.png new file mode 100644 index 0000000000..99b342470a Binary files /dev/null and b/docs-new/docs/getting-started/assets/trace-failed.png differ diff --git a/docs-new/docs/getting-started/assets/webhook.site.1.png b/docs-new/docs/getting-started/assets/webhook.site.1.png new file mode 100644 index 0000000000..7e739e43c0 Binary files /dev/null and b/docs-new/docs/getting-started/assets/webhook.site.1.png differ diff --git a/docs-new/docs/getting-started/assets/webhook.site.2.png b/docs-new/docs/getting-started/assets/webhook.site.2.png new file mode 100644 index 0000000000..c11786f89b Binary files /dev/null and b/docs-new/docs/getting-started/assets/webhook.site.2.png differ diff --git a/docs-new/docs/getting-started/assets/webhook.site.3.png b/docs-new/docs/getting-started/assets/webhook.site.3.png new file mode 100644 index 0000000000..c5529601c4 Binary files /dev/null and b/docs-new/docs/getting-started/assets/webhook.site.3.png differ diff --git a/docs-new/docs/getting-started/index.md b/docs-new/docs/getting-started/index.md new file mode 100644 index 0000000000..59db870733 --- /dev/null +++ b/docs-new/docs/getting-started/index.md @@ -0,0 +1 @@ +# Get started diff --git a/docs-new/docs/getting-started/lifecycle-management.md b/docs-new/docs/getting-started/lifecycle-management.md new file mode 100644 index 0000000000..f77ebe9c25 --- /dev/null +++ b/docs-new/docs/getting-started/lifecycle-management.md @@ -0,0 +1,224 @@ +# Release Lifecycle Management + +The Release Lifecycle Management tools run +pre- and post-deployment tasks and checks +for your existing cloud-native deployments +to make them more robust. +This tutorial introduces these tools. + +> This tutorial assumes you have already completed the +[Getting started with Keptn Observability](../getting-started/index.md) +exercise. +> Please ensure you've finished that before attempting this guide. + +## Keptn Pre and Post Deployment Tasks + +When Keptn is successfully monitoring your deployments, it can also run arbitrary tasks and SLO evaluations: + +- pre-deployment (before the pod is scheduled) and +- post-deployment (after the post is scheduled) + +> Pre and post deployments can also run on a KeptnApp level. +> See [annotations to KeptnApp](../guides/integrate.md#annotations-to-keptnapp) + +## Prerequisites: Deploy webhook sink + +During this exercise, you will configure Keptn to trigger a webhook before and after a deployment has successfully completed. + +For demo purposes, a place is required to send those request. +Install the [open source webhook.site tool](https://github.com/webhooksite/webhook.site/tree/master/kubernetes) now. + +This will provide a place, on cluster, to send (and view) web requests. + +> Note: If you have your own endpoint, you can skip this step. + +```shell +kubectl apply -f https://raw.githubusercontent.com/webhooksite/webhook.site/master/kubernetes/namespace.yml +kubectl apply -f https://raw.githubusercontent.com/webhooksite/webhook.site/master/kubernetes/redis.deployment.yml +kubectl apply -f https://raw.githubusercontent.com/webhooksite/webhook.site/master/kubernetes/laravel-echo-server.deployment.yml +kubectl apply -f https://raw.githubusercontent.com/webhooksite/webhook.site/master/kubernetes/webhook.deployment.yml +kubectl apply -f https://raw.githubusercontent.com/webhooksite/webhook.site/master/kubernetes/service.yml +``` + +Wait until all pods are running in the `webhook` namespace then port-forward and view the webhook sink page: + +```shell +kubectl -n webhook wait --for=condition=Ready pods --all +kubectl -n webhook port-forward svc/webhook 8084 +``` + +Open a browser and go to `http://localhost:8084` + +You should see a page like this with a unique URL (your ID will be different). + +![webhook.site page](./assets/webhook.site.1.png) + +Make a note of that unique URL. + +### Verify Webhook Sink + +Open a new browser table and go to your unique URL. +The page should remain blank, but when toggling back to `http://localhost:8084`, you should see a new entry. + +Every request sent to that unique URL will be logged here. + +![webhook.site entry](./assets/webhook.site.2.png) + +## Add a Post Deployment Task + +Add a task which will trigger after a deployment. + +Change `UUID` to whatever value you have. +Apply this manifest: + +```yaml +--- +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: send-event + namespace: keptndemo +spec: + retries: 0 + timeout: 5s + container: + name: curlcontainer + image: curlimages/curl:latest + args: [ + '-X', + 'POST', + 'http://webhook.webhook.svc.cluster.local:8084/YOUR-UUID-HERE', + '-H', + 'Content-Type: application/json', + '-d', + '{ "from": "keptn send-event" }' + ] +``` + +### Verify it works + +Verify that the KeptnTaskDefinition above actually works. + +Trigger an on-demand task execution to verify that the job and pod function correctly. + +In the following steps we will have Keptn orchestrate this for us automatically. + +Apply this manifest: + +```yaml +--- +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTask +metadata: + name: runsendevent1 + namespace: keptndemo +spec: + taskDefinition: send-event + context: + appName: "my-test-app" + appVersion: "1.0.0" + objectType: "" + taskType: "" + workloadName: "my-test-workload" + workloadVersion: "1.0.0" +``` + +If it works, `kubectl -n keptndemo get jobs` should show: + +```shell +NAME COMPLETIONS DURATION AGE +runsendevent1-***** 1/1 6s 2m +``` + +`kubectl -n keptndemo get pods` will show the successfully executed pod. + +The webhook sync should show this: + +![webhook sync](./assets/webhook.site.3.png) + +Incidentally, this is exactly how you can use Keptn with [applications deployed outside of Kubernetes](../use-cases/non-k8s.md). + +> Note: If you want to trigger this multiple times, you must change the KeptnTask name. +> +> For example, by changing `runsendevent1` to `runsendevent2` + +## Ask Keptn to trigger task after Deployment + +Annotate the demo application `Deployment` manifest to have Keptn automatically trigger the task after every deployment. + +Recall the `Deployment` from the [Observability](../getting-started/observability.md#step-3-deploy-demo-application) +Getting started guide. + +Add a new label so the `labels` section looks like this: + +```yaml +... +labels: + app.kubernetes.io/part-of: keptndemoapp + app.kubernetes.io/name: nginx + app.kubernetes.io/version: 0.0.2 + keptn.sh/post-deployment-tasks: "send-event" +... +``` + +Increase the version number to `0.0.2` and re-apply the manifest. + +Here is a full version of the new 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.2 + keptn.sh/post-deployment-tasks: "send-event" + spec: + containers: + - name: nginx + image: nginx:1.14.2 + ports: + - containerPort: 80 +``` + +> Best Practice: Start with post deployment tasks. +> Pre-deployment tasks can potentially block deployments (see below). + +### What Happens Next? + +1. The deployment will be applied +1. When the pods are running, Keptn will automatically create a `KeptnTask` resource for version `0.0.2` of this KeptnApp +1. The `KeptnTask` will create a Kubernetes Job +1. The Kubernetes Job will create a Pod +1. The pod will run curl and send a new event to the event sink + +### Pre-deployment Tasks + +Keptn Tasks can also be executed pre-deployment (before the pods are scheduled). +Do this by using the `keptn.sh/pre-deployment-tasks` label. + +> Note: If a pre-deployment task fails, the pod will remain in a Pending state. + +## Further Information + +There is a lot more you can do with KeptnTasks. +See [pre and post deployment checks page](../guides/integrate.md#pre--and-post-deployment-checks) to find out more. + +## What's next? + +Keptn can also run pre and post deployment SLO evaluations. + +Continue the Keptn learning journey by adding evaluations. diff --git a/docs-new/docs/getting-started/metrics.md b/docs-new/docs/getting-started/metrics.md new file mode 100644 index 0000000000..24b600c526 --- /dev/null +++ b/docs-new/docs/getting-started/metrics.md @@ -0,0 +1,286 @@ +# Keptn Metrics + +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. +You may have deployment tools like Argo, Flux, KEDA, HPA, or Keptn +that need observability data to make automated decisions +such as whether a rollout is good, or whether to scale up or down. + +Your observability data may come +from multiple observability solutions -- +Prometheus, Dynatrace, Datadog and others -- +or may be data that comes directly +from your cloud provider such as AWS, Google, or Azure. +The Keptn Metrics Server unifies and standardizes access to all this data. +Minimal configuration is required +because Keptn hooks directly into Kubernetes primitives. + +The +[Kubernetes metric server](https://github.com/kubernetes-sigs/metrics-server) +requires that you maintain point-to-point integrations +from Argo Rollouts, Flux, KEDA, and HPA. +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 Keptn metrics feature unites all these metrics +integrates metrics from all these sources into a single set of metrics. + +## Using this exercise + +This exercise is based on the +[simplenode-dev](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd) +example. +You can clone that repo to access it locally +or just look at it for examples +as you implement the functionality "from scratch" +on your local Kubernetes deployment cluster. + +This is the first of three exercises in the +[Introducing Keptn](index.md) +series. +After completing this exercise, +you may want to do the other exercises: + +- In [Standardize observability](../core-concepts/usecase-observability.md), + you learn how to standardize access + to the observability data for your cluster. +- In + [Manage release lifecycle](../core-concepts/usecase-orchestrate.md), + you learn how to implement + pre- and post-deployment tasks and evaluations + to orchestrate the flow of all the [workloads](https://kubernetes.io/docs/concepts/workloads/) + that are part of your `application`. + +The steps to implement metrics in an existing cluster are: + +1. [Install Keptn](../installation/index.md) +1. Configure the metrics you want to use: + - [Define metrics providers](#define-metrics-providers) + - [Define KeptnMetric information](#define-keptnmetric-information) + +If you want to create your own cluster to run this exercise, +follow the instructions in [Installation](../installation/index.md). + +## Define metrics to use + +You need to define the external observability platforms +from which you want to pull data +and then the specific data you want to pull. +This data is pulled and fetched continuously +at an interval you specify for each specific bit of data. +Data is available through the resource and through the data provider itself, +as well as the Kubernetes CLI. + +### Define metrics providers + +Populate a +[KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) +resource for each external observability platform you want to use. + +For our example, we define two observability platforms: + +- `dev-prometheus` +- `dev-dynatrace` + +You can specify a virtually unlimited number of providers, +including multiple instances of each observability platform. +Each one must be assigned a unique name, +identified by the type of platform it is +and the URL of the target server. +If the target server is protected by a `secret`, +provide information about the token and key. + +> Note: The video and example application use an older syntax + of the `KeptnMetricsProvider` and `KeptnMetric` resources. + The syntax shown in this document and the reference page + is correct for v0.7.1 and later. + +Definition of +[dev-prometheus](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-prometheus-provider.yaml) +data source: + +```yaml +kind: KeptnMetricsProvider +metadata: + name: dev-prometheus + namespace: simplenode-dev +spec: + type: prometheus + targetserver: "http://prometheus-k8s-monitoring-svc.cluster.local:9090" +``` + +Definition of the +[dev-dynatrace](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/dynatrace-provider.yaml.tmp) +data source. +Note that the `dev-dynatrace` server is protected by a secret key +so that information is included in the provider definition: + +```yaml +kind: KeptnMetricsProvider +metadata: + name: dev-dynatrace + namespace: simplenode-dev +spec: + type: dynatrace + targetServer: "https://hci34192.live.dynatrace.com" + secretKeyRef: + name: dynatrace + key: DT_TOKEN +... +``` + +### Define KeptnMetric information + +The [KeptnMetric](../reference/crd-reference/metric.md) resource +defines the information you want to gather, +specified as a query for the particular observability platform +you are using. +You can define any type of metric from any data source. + +In our example, we define two bits of information to retrieve: + +- Number of CPUs, derived from the `dev-prometheus` data platform +- `availability` SLO, derived from the `dev-dynatrace` data platform + +Each of these are configured to fetch data every 10 seconds +but you could configure a different `fetchIntervalSeconds` value +for each metric. + +The +[keptn-metric.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-metric.yaml) +file for our example looks like: + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: Keptnmetric +metadata: + name: available-cpus + namespace: simplenode-dev +spec: + provider: + name: dev-prometheus + query: "sum(kube_node_status_capacity{resources`cpu`})" + fetchIntervalSeconds: 10 +--- +apiVersion: metrics.keptn.sh/v1beta1 +kind: Keptnmetric +metadata: + name: availability-slo + namespace: simplenode-dev +spec: + provider: + name: dev-dynatrace + query: "func:slo.availability_simplenodeservice" + fetchIntervalSeconds: 10 +``` + +Note the following: + +- Populate one YAML file per metric + then apply all of them. +- Each metric is assigned a unique `name`. +- The value of the `spec.provider.name` field + must correspond to the name assigned in + the `metadata.name` field of a `KeptnMetricsProvider` resource. +- Information is fetched in on a continuous basis + at a rate specified + by the value of the `spec.fetchIntervalSeconds` field. + +### View available metrics + +Use the following command to view +the metrics that are configured in your cluster. +This example displays the two metrics we configured above: + +```shell +kubectl get KeptnMetrics -A +``` + +```shell +NAMESPACE NAME PROVIDER QUERY +simplenode-dev availability-slo dev-dynatrace func:slo.availability_simplenodeservice +simplenode-dev available-cpus dev-prometheus sum(kube_node_status_capacity{resource=`cpu`}) +``` + +## Run the metrics + +As soon as you define your `KeptnMetricsProvider` and `KeptnMetric` resources, +Keptn begins collecting the metrics you defined. +You do not need to do anything else. + +## Observing the metrics + +The metrics can be retrieved +through CRs and through the Kubernetes Metric API. + +The syntax to retrieve metrics from the CR is: + +```shell +kubectl get keptnmetrics.metrics.keptn.sh -n +``` + +For example, the output for the `available-cpus` metric looks like: + +```shell +$ kubectl get keptnmetrics.metrics.keptn.sh -n simplenode-dev available-cpus + +NAME PROVIDER QUERY VALUE +cpu-throttling my-provider sum(kube_node_status_capacity{resource=`cpu`}) 6.000 +``` + +The syntax to retrieve metrics through the Kubernetes API is: + +```yaml +kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces//keptnmetrics.metrics.sh//" +``` + +For example, the output for the `available-cpus` looks like: + +```yaml +$ kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/simplenode-dev/keptnmetrics.metrics.sh/available-cpus/available-cpus" + +{ + "kind": "MetricValueList", + "apiVersion": "custom.metrics.k8s.io/v1beta2", + "metadata": {}, + "items": [ + { + "describedObject": { + "kind": "KeptnMetric", + "namespace": "simplenode-dev", + "name": "available-cpus", + "apiVersion": "metrics.keptn.sh/v1beta1" + }, + "metric": { + "name": "available-cpus", + "selector": {} + }, + "timestamp": "2023-05-11T08:05:36Z", + "value": "6" + } + ] +} +``` + +You can also display the metrics graphically using a dashboard such as Grafana. + +## Implementing autoscaling with HPA + +The Kubernetes HorizontalPodAutoscaler (HPA) +uses metrics to provide autoscaling for the cluster. +HPA can retrieve KeptnMetrics and use those metrics to implement HPA. +See +Using the [HorizontalPodAutoscaler](../use-cases/hpa.md) +for detailed information. + +## Learn more + +To learn more about the Keptn Metrics Server, see: + +- Architecture: + [Keptn Metrics Operator](../components/metrics-operator/index.md) +- More information about implementing Keptn Metrics: + [Keptn Metrics](../guides/evaluatemetrics.md) diff --git a/docs-new/docs/getting-started/observability.md b/docs-new/docs/getting-started/observability.md new file mode 100644 index 0000000000..dc2ea221a5 --- /dev/null +++ b/docs-new/docs/getting-started/observability.md @@ -0,0 +1,594 @@ +# Keptn Observability + +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 keptn https://charts.lifecycle.keptn.sh +helm repo update +helm upgrade --install keptn keptn/keptn -n keptn-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 `keptnconfig.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-system +spec: + OTelCollectorUrl: 'jaeger-collector.keptn-system.svc.cluster.local:4317' + keptnAppCreationRequestTimeoutSeconds: 30 +``` + +Apply the file and wait for Keptn to pick up the new configuration: + +```shell +kubectl apply -f keptnconfig.yaml +``` + +Keptn reacts immediately to a configuration change. +although the speed depends on the Kubernetes API server signaling updates +and can be influenced by network latency. + +## 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` CR. + +```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 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): + +## 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-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-system +kubectl wait --for=condition=available deployment/jaeger -n keptn-system --timeout=300s +``` + +Port-forward to access Jaeger: + +```shell +kubectl -n keptn-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-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-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](../guides/restart-application-deployment.md) + 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](../reference/crd-reference/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](../reference/crd-reference/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](../reference/crd-reference/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](../reference/crd-reference/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](../reference/crd-reference/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](../guides/tasks.md). diff --git a/docs-new/docs/guides/assets/dynatrace_dora_dashboard.png b/docs-new/docs/guides/assets/dynatrace_dora_dashboard.png new file mode 100644 index 0000000000..3318a4303f Binary files /dev/null and b/docs-new/docs/guides/assets/dynatrace_dora_dashboard.png differ diff --git a/docs-new/docs/guides/assets/trace.png b/docs-new/docs/guides/assets/trace.png new file mode 100644 index 0000000000..84254826c9 Binary files /dev/null and b/docs-new/docs/guides/assets/trace.png differ diff --git a/docs-new/docs/guides/auto-app-discovery.md b/docs-new/docs/guides/auto-app-discovery.md new file mode 100644 index 0000000000..4331fd83a4 --- /dev/null +++ b/docs-new/docs/guides/auto-app-discovery.md @@ -0,0 +1,110 @@ +# Auto app discovery + +The automatically generated `KeptnApp` file +aggregates the workloads to include in the application, +based on annotations made to the workloads themselves. +This enables you to run Keptn observability features on your cluster. + +Afterward, you can monitor the status of the deployment using +a command like the following: + +```shell +kubectl get keptnworkloadversion -n podtato-kubectl -w +``` + +The generated `KeptnApp` file includes `metadata` +that names this `KeptnApp` and identifies the Namespace where it resides. + +```yaml +metadata: + name: simpleapp + namespace: simplenode-dev +``` + +It also includes a `spec.workloads` list +that defines the workloads to be included. + +Pre-/post-deployment tasks and evaluations for the `KeptnApp` +can also be added to this resource manually +but this is not required for observability. + +As an example, consider the following application, +consisting of multiple deployments, +which is going to be deployed into a Keptn-enabled namespace. +Note that: + +1. Keptn is enabled for the namespace where your application runs. +1. The `Deployment` workloads are annotated appropriately. + This example does not use other workloads. + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: podtato-kubectl + annotations: + keptn.sh/lifecycle-toolkit: "enabled" + +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: podtato-head-frontend + namespace: podtato-kubectl +spec: + template: + metadata: + labels: + app.kubernetes.io/name: podtato-head-frontend + app.kubernetes.io/part-of: podtato-head + app.kubernetes.io/version: 0.1.0 + spec: + containers: + - name: podtato-head-frontend + image: podtato-head-frontend +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: podtato-head-hat + namespace: podtato-kubectl +spec: + replicas: 1 + template: + metadata: + labels: + app.kubernetes.io/name: podtato-head-hat + app.kubernetes.io/part-of: podtato-head + app.kubernetes.io/version: 0.1.1 + spec: + containers: + - name: podtato-head-hat + image: podtato-head-hat +``` + +Applying these resources results in the creation +of the following `KeptnApp` resource: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha2 +kind: KeptnApp +metadata: + name: podtato-head + namespace: podtato-kubectl + annotations: + app.kubernetes.io/managed-by: "keptn" +spec: + version: "" + workloads: + - name: podtato-head-frontend + version: 0.1.0 + - name: podtato-head-hat + version: 1.1.1 +``` + +With the `KeptnApp` resource created, +you get observability of your application's deployments +by using the OpenTelemetry tracing features +that are provided by Keptn: + +![Application deployment trace](./assets/trace.png) diff --git a/docs-new/docs/guides/dora.md b/docs-new/docs/guides/dora.md new file mode 100644 index 0000000000..b51b707f85 --- /dev/null +++ b/docs-new/docs/guides/dora.md @@ -0,0 +1,60 @@ +# DORA metrics + +DORA metrics are an industry-standard set of measurements +that are included in Keptn; +see the following for a description: + +- [What are DORA Metrics and Why Do They Matter?](https://codeclimate.com/blog/dora-metrics) +- [Are you an Elite DevOps Performer? + Find out with the Four Keys Project](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance) + +DORA metrics provide information such as: + +- How many deployments happened in the last six hours? +- Time between deployments +- Deployment time between versions +- Average time between versions. + +Keptn starts collecting these metrics +as soon as you apply +[basic annotations](./integrate.md#basic-annotations) +to the +[workload](https://kubernetes.io/docs/concepts/workloads/) +resources +([Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), +[StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/), +[DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), +and +[ReplicaSets](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/) +or +[Pods](https://kubernetes.io/docs/concepts/workloads/pods/)). + +Metrics are collected only for the resources that are annotated. + +To view DORA metrics, run the following two commands: + +- Retrieve the service name with: + + ```shell + kubectl -n keptn-system get service \ + -l control-plane=lifecycle-operator + ``` + +- Then port-forward to the name of your service: + + ```shell + kubectl -n keptn-system port-forward \ + service/ 2222 + ``` + +Then view the metrics at: + + ```shell + http://localhost:2222/metrics + ``` + +DORA metrics are also displayed on Grafana +or whatever dashboard application you choose. +For example: + +![DORA metrics](./assets/dynatrace_dora_dashboard.png) diff --git a/docs-new/docs/guides/evaluatemetrics.md b/docs-new/docs/guides/evaluatemetrics.md new file mode 100644 index 0000000000..354ac507a0 --- /dev/null +++ b/docs-new/docs/guides/evaluatemetrics.md @@ -0,0 +1,265 @@ +# Keptn Metrics + +The Keptn Metrics Operator provides a single entry point +to all metrics in the cluster +and allows you to define metrics based on multiple data platforms +and multiple instances of any data platform. +Metrics are fetched independently +and can be used for an evaluation at [workload-](https://kubernetes.io/docs/concepts/workloads/) +and application-level, or for scaling your [workloads](https://kubernetes.io/docs/concepts/workloads/). + +This data can be displayed on Grafana +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](../getting-started/metrics.md). + +## Keptn metric basics + +Keptn metrics are implemented with two resources: + +* [KeptnMetric](../reference/crd-reference/metric.md) -- + define the metric to report +* [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) -- + define the configuration for a data provider + +As soon as you define and apply +your `KeptnMetricsProvider` and `KeptnMetric` resources, +Keptn begins collecting the metrics you defined. +You do not need to do anything else. + +### Define KeptnMetricsProvider resources + +You must define a +[KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) resource +for each instance of each data provider you are using. + +Note the following: + +* Each `KeptnMetricsProvider` resource is bound to a specific namespace. +* Each `KeptnMetric` resource must be located in the same namespace + as the associated `KeptnMetricsProvider` resource. +* `KeptnEvaluationDefinition` resources can reference metrics + from any namespace in the cluster. +* To define metrics that can be used in evaluations + on all namespaces in the cluster, + create `KeptnMetricsProvider` and `KeptnMetric` resources + in a centralized namespace + such as `keptn-system`. + +To configure a data provider into your Keptn cluster: + +1. Create a secret if your data provider uses one. + See + [Create secret text](./tasks.md#create-secret-text). +1. Install and configure each instance of each data provider + into your Keptn cluster, + following the instructions provided by the data source provider. + See + [Prepare your cluster for Keptn](../installation/k8s.md/#prepare-your-cluster-for-keptn) +for links. + Keptn supports using multiple instances of multiple data providers. +1. Define a + [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) + resource for each data source. + +For example, the `KeptnMetricProvider` resource +for a Prometheus data source that does not use a secret +could look like: + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: KeptnMetricsProvider +metadata: + name: prometheus-provider + namespace: simplenode-dev +spec: + type: prometheus + targetServer: "http://prometheus-k8s.monitoring.svc.cluster.local:9090" +``` + +The `KeptnMetricProvider` resource for a Dynatrace provider +that uses a secret could look like: + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: KeptnMetricsProvider +metadata: + name: dynatrace-provider + namespace: podtato-kubectl +spec: + type: dynatrace + targetServer: "" + secretKeyRef: + name: dt-api-token + key: DT_TOKEN +``` + +### Define KeptnMetric information + +The [KeptnMetric](../reference/crd-reference/metric.md) resource +defines the information you want to gather, +specified as a query for the particular observability platform +you are using. +You can define any type of metric from any data source. + +In our example, we define two bits of information to retrieve: + +* Number of CPUs, fetched from the `dev-prometheus` data platform +* `availability` SLO, fetched from the `dev-dynatrace` data platform + +Each of these are configured to fetch data every 10 seconds +but you could configure a different `fetchIntervalSeconds` value +for each metric. + +The +[keptn-metric.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-metric.yaml) +file for our example looks like: + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: Keptnmetric +metadata: + name: available-cpus + namespace: simplenode-dev +spec: + provider: + name: dev-prometheus + query: "sum(kube_node_status_capacity{resources`cpu`})" + fetchIntervalSeconds: 10 +--- +apiVersion: metrics.keptn.sh/v1beta1 +kind: Keptnmetric +metadata: + name: availability-slo + namespace: simplenode-dev +spec: + provider: + name: dev-dynatrace + query: "func:slo.availability_simplenodeservice" + fetchIntervalSeconds: 10 +``` + +Note the following: + +* Each metric should have a unique `name`. +* The value of the `spec.provider.name` field + must correspond to the name assigned in + the `metadata.name` field of a `KeptnMetricsProvider` resource. +* Information is fetched in on a continuous basis + at a rate specified + by the value of the `spec.fetchIntervalSeconds` field. + +## Observing the metrics + +### Accessing Metrics via the Kubernetes Custom Metrics API + +`KeptnMetrics` can be retrieved using the `kubectl` command and the +[KeptnMetric](../reference/crd-reference/metric.md) +API. +This section shows how to do that. + +Metrics can also be displayed on a Grafana or other dashboard +or they can be exposed as OpenTelemetry metrics; see +[Access Keptn metrics as OpenTelemetry metrics](otel.md/#access-keptn-metrics-as-opentelemetry-metrics) +for instructions. + +### Retrieve KeptnMetric values with kubectl and the KeptnMetric API + +Use the `kubectl get --raw` command +to retrieve the values of a `KeptnMetric` resource, +as in the following example: + +```shell +$ kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/podtato-kubectl/keptnmetrics.metrics.sh/keptnmetric-sample/keptnmetric-sample" | jq . + +{ + "kind": "MetricValueList", + "apiVersion": "custom.metrics.k8s.io/v1beta2", + "metadata": {}, + "items": [ + { + "describedObject": { + "kind": "KeptnMetric", + "namespace": "podtato-kubectl", + "name": "keptnmetric-sample", + "apiVersion": "metrics.keptn.sh/v1beta1" + }, + "metric": { + "name": "keptnmetric-sample", + "selector": { + "matchLabels": { + "app": "frontend" + } + } + }, + "timestamp": "2023-01-25T09:26:15Z", + "value": "10" + } + ] +} +``` + +### Filter on matching labels + +You can filter based on matching labels. +For example, to retrieve all metrics +that are labelled with `app=frontend`, +use the following command: + +```shell +$ kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/podtato-kubectl/keptnmetrics.metrics.sh/*/*?labelSelector=app%3Dfrontend" | jq . + +{ + "kind": "MetricValueList", + "apiVersion": "custom.metrics.k8s.io/v1beta2", + "metadata": {}, + "items": [ + { + "describedObject": { + "kind": "KeptnMetric", + "namespace": "keptn-system", + "name": "keptnmetric-sample", + "apiVersion": "metrics.keptn.sh/v1beta1" + }, + "metric": { + "name": "keptnmetric-sample", + "selector": { + "matchLabels": { + "app": "frontend" + } + } + }, + "timestamp": "2023-01-25T09:26:15Z", + "value": "10" + } + ] +} +``` + +### Query Metrics over a Timerange + +You can query metrics over a specified timeframe. +For example, if you set the `range.interval` field +in the `KeptnMetric` resource to be `3m`, +the Keptn Metrics Operator queries the metrics for the +last 3 minutes. +In other words, the span is +`from = currentTime - range.interval` and `to = currentTime`. + +The default value is set to be `5m` if the `range.interval` is not set. + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: KeptnMetric +metadata: + name: good-metric +spec: + provider: + name: my-provider + query: "sum(kube_pod_container_resource_limits{resource='cpu'})" + fetchIntervalSeconds: 10 + range: + interval: "3m" +``` diff --git a/docs-new/docs/guides/evaluations.md b/docs-new/docs/guides/evaluations.md new file mode 100644 index 0000000000..9631957d07 --- /dev/null +++ b/docs-new/docs/guides/evaluations.md @@ -0,0 +1,68 @@ +# Evaluations + +A +[KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) +resource contains a list of `objectives`, +each of which checks whether a defined `KeptnMetric` resource +meets a defined target value. +The example +[app-pre-deploy-eval.yaml](https://github.com/keptn/lifecycle-toolkit/blob/main/examples/sample-app/version-3/app-pre-deploy-eval.yaml) +file specifies the `app-pre-deploy-eval-2` evaluation as follows: +{% include "../assets/crd/eval.yaml" %} + +The `evaluationTarget` is set to be `>1`, +so this evaluation ensures that more than 1 CPU is available +before the [workload](https://kubernetes.io/docs/concepts/workloads/) or application is deployed. + +This evaluation references the +[KeptnMetric](../reference/crd-reference/metric.md) resource +that is named `available-cpus`. +This is defined in the example +[metric.yaml](https://github.com/keptn/lifecycle-toolkit/blob/main/examples/sample-app/base/metric.yaml) +file: +{% include "../assets/crd/metric.yaml" %} + +To run an evaluation on one of your +[Workloads](https://kubernetes.io/docs/concepts/workloads/) +([Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), +[StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/), +[DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), +or +[ReplicaSets](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/), +you must: + +* Annotate your [workloads](https://kubernetes.io/docs/concepts/workloads/) + to identify the `KeptnEvaluationDefinition` resource you want to run + pre- and post-deployment for the specific [workloads](https://kubernetes.io/docs/concepts/workloads/). +* Manually edit all + [KeptnApp](../reference/crd-reference/app.md) resources + to specify the `KeptnEvaluationDefinition` to be run + pre- and post-deployment evaluations for the `KeptnApp` itself. + +See +[Pre- and post-deployment checks](./integrate.md#pre--and-post-deployment-checks) +for details. + +Note the following: + +* One `KeptnEvaluationDefinition` resource can include + multiple `objective` fields that reference additional metrics. + In this example, you might want to also query + available memory, disk space, and other resources + that are required for the deployment. +* The `KeptnMetric` resources that are referenced + in a `KeptnEvaluationDefinition` resource + * can be defined on different namespaces in the cluster + * can query different instances of different types of metric providers +* All objectives within a `KeptnEvaluationDefinition` resource + are evaluated in order. + If the evaluation of any objective fails, + the `KeptnEvaluation` itself fails. +* You can define multiple evaluations + for each stage (pre- and post-deployment). + These evaluations run in parallel so the failure of one evaluation + has no effect on whether other evaluations are completed. +* The results of each evaluation + is written to a + [KeptnEvaluation](../reference/api-reference/lifecycle/v1alpha3/index.md#keptnevaluation) + resource. diff --git a/docs-new/docs/guides/index.md b/docs-new/docs/guides/index.md new file mode 100644 index 0000000000..50a86734ff --- /dev/null +++ b/docs-new/docs/guides/index.md @@ -0,0 +1 @@ +# Guides diff --git a/docs-new/docs/guides/integrate.md b/docs-new/docs/guides/integrate.md new file mode 100644 index 0000000000..1b5380c190 --- /dev/null +++ b/docs-new/docs/guides/integrate.md @@ -0,0 +1,270 @@ +# Integrate Keptn with your Applications + +Keptn works +on top of the default scheduler for the cluster, +so it can trace all activities of all deployment workloads on the cluster, +no matter what tool is used for the deployment. +This same mechanism allows Keptn to inject pre- and post-deployment checks +into all deployment workloads. +Keptn monitors resources +that have been applied into the Kubernetes cluster +and reacts if it finds a workload with special annotations/labels. +Keptn uses metadata +that is added to the Kubernetes workloads +to identify the workloads of interest. + +To integrate Keptn with your applications: + +* You must first +[install and enable](../installation/index.md#basic-installation) +Keptn. +* Annotate or label your workloads +with either Keptn or Kubernetes keys. + * [Basic annotations](#basic-annotations) + or labels + are required for all Keptn features except Keptn metrics. + * [Pre- and post-deployment checks](#basic-annotations) + are required only for the Release lifecycle management feature. + +Keptn uses these annotations to the Kubernetes workloads to create the +[KeptnWorkload](../reference/api-reference/lifecycle/v1alpha3/index.md#keptnworkload) +and +[KeptnApp](../reference/crd-reference/app.md) +resources that it uses to provide observability +and release lifecycle management. + +> Note: Annotations are not required if you are only using the + `metrics-operator` component of Keptn + to observe Keptn metrics. + +## Basic annotations + +Keptn automatically discovers `KeptnApp` resources, +based on the annotations or labels. +This enables the Keptn observability features +(based on OpenTelemetry) for existing applications, +without additional Keptn configuration. + +Keptn monitors your +[Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), +[StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/), +and +[ReplicaSets](https://kubernetes.io/docs/concepts/workloads/controllers/replicaset/), +and +[DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) +resources in the namespaces where Keptn is enabled. +If Keptn finds any of these resources and the resource has either +the `keptn.sh` or the `kubernetes` annotations/labels, +it creates appropriate +[KeptnWorkload](../reference/api-reference/lifecycle/v1alpha3/index.md#keptnworkload) +and +[KeptnApp](../reference/crd-reference/app.md) +resources for the version it detects. + +The basic keptn.sh keys that can be used for annotations or labels are: + +```yaml +keptn.sh/workload: myAwesomeWorkload +keptn.sh/version: myAwesomeWorkloadVersion +keptn.sh/app: myAwesomeAppName +keptn.sh/container: myAwesomeContainer +``` + +Alternatively, you can use Kubernetes keys for annotations or labels. +These are part of the Kubernetes +[Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/): + +```yaml +app.kubernetes.io/name: myAwesomeWorkload +app.kubernetes.io/version: myAwesomeWorkloadVersion +app.kubernetes.io/part-of: myAwesomeAppName +``` + +These keys are defined as: + +* `keptn.sh/workload` or `app.kubernetes.io/name`: Determines the name + of the generated + [KeptnWorkload](../reference/api-reference/lifecycle/v1alpha3/index.md#keptnworkload) + resource. +* `keptn.sh/version` or `app.kubernetes.io/version`: + Determines the version of the `KeptnWorkload` + that represents the Workload. + If the Workload has no `version` annotation/labels + and the pod has only one container, + Keptn takes the image tag as version + (unless it is "latest"). +* `keptn.sh/app` or `app.kubernetes.io/part-of`: Determines the name + of the generated `KeptnApp` representing your Application. + All workloads that share the same value for this label + are consolidated into the same `KeptnApp` resource. +* `keptn.sh/container`: Determines the name of the container in the workload, + from which Keptn extracts the version. + This applies to single- and multi-container + workloads. + If the given container name does not match any container in the workload + no version can be determined. + Note that there is no equivalent `app.kubernetes.io/` annotation/label for this label. + +Keptn automatically generates appropriate +[KeptnApp](../reference/crd-reference/app.md) +resources that are used for observability, +based on whether the `keptn.sh/app` or `app.kubernetes.io/part-of` +annotation/label is populated: + +* If either of these annotations/labels are populated, + Keptn automatically generates a `KeptnApp` resource + that includes all workloads that have the same annotation/label, + thus creating a `KeptnApp` resource for each defined grouping + +* If only the `workload` and `version` annotations/labels are available + (in other words, neither the `keptn.sh/app` + or `app.kubernetes.io/part-of` annotation/label is populated), + Keptn creates a `KeptnApp` resource for each `KeptnWorkload` + and your observability output traces the individual `Keptnworkload` resources + but not the combined workloads that constitute your deployed application. + +See +[Keptn Applications and Keptn Workloads](../components/lifecycle-operator/keptn-apps.md) +for architectural information about how `KeptnApp` and `KeptnWorkloads` +are implemented. + +## Annotations vs. labels + +The same keys can be used as +[annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) +or +[labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/). +Both annotations and labels are can be attached to Kubernetes objects. +Some key differences between the two: + +* Annotations + * Are not used to identify and select objects + * Can contain up to 262144 chars + * Metadata in an annotation can be small or large, + structured or unstructured, + and can include characters not permitted by labels + +* Labels + * Can be used to select objects + and to find collections of objects that satisfy certain conditions + * Can contain up to 63 chars + * Are appropriate for identifying attributes of objects + that are meaningful and relevant to users + but do not directly imply semantics to the core system + +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 + in the annotations, and then in the labels. +* If neither is the case, it looks for the `app.kubernetes.io` equivalent, + again first in the annotations, then in the labels. + +In general, annotations are more appropriate than labels +for integrating Keptn with your applications +because they store references, names, and version information +so the 63 char limitation is quite restrictive. +However, labels can be used if you specifically need them +and can accommodate the size restriction. + +## Pre- and post-deployment checks + +To implement the Keptn Release Lifecycle feature +that handles pre- and post-deployment evaluations and tasks, +do the following: + +* Define the + [KeptnMetric](../reference/crd-reference/metric.md) + and + [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) + resources for each evaluation you want. + A `KeptnEvaluationDefinition` compares the value + of a `KeptnMetric` to the threshold that is specified. +* You will also need to define the necessary + [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) + and + resource for each instance of each data source + used for the `KeptnEvaluationDefinition` resources you define. +* Define a + [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) + resource for each task you want to execute. + `KeptnTaskDefinition` resources contain re-usable "functions" + that can execute before and after the deployment. + For example, before the deployment starts, + you might run a check for open problems in your infrastructure + and invoke a pipeline to run performance tests. + The deployment is kept in a pending state + until the infrastructure is capable of accepting deployments again. + See + [Working with Keptn tasks](./tasks.md) + for more information. +* Annotate your [Workloads](https://kubernetes.io/docs/concepts/workloads/) + [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), + [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/), + and + [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) + to include each evaluation and task you want run + for specific workloads. +* Manually edit all + [KeptnApp](../reference/crd-reference/app.md) resources + to specify evaluations and tasks to be run for the `KeptnApp` itself. + +### Annotations to KeptnApp + +The annotations to workloads do not define the tasks and evaluations +to be run for `KeptnApp` resources themselves. +To define pre- and post-deployment evaluations and tasks for a `KeptnApp`, +you must manually edit the YAML file to add them. + +Specify one of the following annotations/labels +for each evaluation or task you want to execute: + +```yaml +keptn.sh/pre-deployment-evaluations: <`EvaluationDefinition`-name> +keptn.sh/pre-deployment-tasks: <`TaskDefinition`-name> +keptn.sh/post-deployment-evaluations: <`EvaluationDefinition`-name> +keptn.sh/post-deployment-tasks: <`TaskDefinition`-name> +``` + +The value of these annotations corresponds to the name of +Keptn [resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) +called +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) +resources +These resources contain re-usable "functions" +that can execute before and after the deployment. +For example, before the deployment starts, +you might run a check for open problems in your infrastructure +and invoke a pipeline to run performance tests. +The deployment is kept in a pending state +until the infrastructure is capable of accepting deployments again. + +If everything is fine, the deployment continues and afterward, +a Slack notification is sent with the result of the deployment + +## Example of pre- and post-deployment actions + +A comprehensive example of pre- and post-deployment +evaluations and tasks can be found in our +[examples folder](https://github.com/keptn/lifecycle-toolkit/tree/main/examples/sample-app), +where we use [Podtato-Head](https://github.com/podtato-head/podtato-head) +to run some simple pre-deployment checks. + +To run the example, use the following commands: + +```shell +cd ./examples/podtatohead-deployment/ +kubectl apply -f . +``` + +Afterward, you can monitor the status of the deployment using + +```shell +kubectl get keptnworkloadversion -n podtato-kubectl -w +``` + +The deployment for a Workload stays in a `Pending` +state until the respective pre-deployment check is successfully completed. +Afterwards, the deployment starts and when the workload is deployed, +the post-deployment checks start. diff --git a/docs-new/docs/guides/otel.md b/docs-new/docs/guides/otel.md new file mode 100644 index 0000000000..e3495266f6 --- /dev/null +++ b/docs-new/docs/guides/otel.md @@ -0,0 +1,158 @@ +# OpenTelemetry observability + +Keptn makes any Kubernetes deployment observable. +In other words, it creates a distributed, end-to-end trace +of what Kubernetes does in the context of a Deployment. +To do this, +Keptn introduces the concept of an `application`, +which is an abstraction that connects multiple +[Workloads](https://kubernetes.io/docs/concepts/workloads/) that logically belong together, +even if they use different deployment strategies. + +This means that: + +- You can readily see why a deployment takes so long + or why it fails, even when using multiple deployment strategies. +- Keptn can capture DORA metrics and expose them as OpenTelemetry metrics + +The observability data is an amalgamation of the following: + +- [DORA metrics](dora.md) + are collected out of the box when Keptn is enabled +- [OpenTelemetry](https://opentelemetry.io/) + runs traces that show everything that happens in the Kubernetes cluster +- Custom + [Keptn metrics](evaluatemetrics.md) + that you can use to monitor information + from all the data providers configured in your cluster + +All this information can be displayed with dashboard tools +such as Grafana. + +For an introduction to using OpenTelemetry with Keptn metrics, see the +[Keptn Observability](../getting-started/observability.md) +getting started guide. + +## Requirements for OpenTelemetry + +To access OpenTelemetry metrics with Keptn, +you must have the following on your cluster: + +- An OpenTelemetry collector. + See + [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) + for more information. +- A Prometheus Operator. + See [Prometheus Operator Setup](https://github.com/prometheus-operator/kube-prometheus/blob/main/docs/customizing.md). + + - The Prometheus Operator must have the required permissions + to watch resources of your Keptn namespace + (default is `keptn-system`). + See + [Setup for Monitoring other Namespaces](https://prometheus-operator.dev/docs/kube/monitoring-other-namespaces/)). + + - To install Prometheus into the `monitoring` namespace + using the example configuration included with Keptn, + use the following command sequence. + You can modify these commands to define a different configuration: + + > **Note** + You must clone the `lifecycle-toolkit` repository + and `cd` into the correct directory + (`examples/support/observability`) before running the following commands. + + ```shell + kubectl create namespace monitoring + kubectl apply --server-side -f config/prometheus/setup/ + kubectl apply -f config/prometheus/ + ``` + +- If you want a dashboard for reviewing metrics and traces: + + - Install + [Grafana](https://grafana.com/grafana/) + or the visualization tool of your choice, following the instructions in + [Grafana Setup](https://grafana.com/docs/grafana/latest/setup-grafana/). + - Install + [Jaeger](https://www.jaegertracing.io/) + or a similar tool for traces following the instructions in + [Jaeger Setup](https://www.jaegertracing.io/docs/1.50/getting-started/). + + - Follow the instructions in the Grafana + [README](https://github.com/keptn/lifecycle-toolkit/blob/main/dashboards/grafana/README.md) + file to configure the Grafana dashboard(s) for Keptn.. + + Metrics can also be retrieved without a dashboard. + See + [Accessing Metrics via the Kubernetes Custom Metrics API](evaluatemetrics.md/#accessing-metrics-via-the-kubernetes-custom-metrics-api) + +## Integrate OpenTelemetry into Keptn + +To integrate OpenTelemetry into Keptn: + +- Apply + [basic annotations](./integrate.md#basic-annotations) + for the `Deployment` resource(s) + to integrate Keptn into your Kubernetes cluster. +- To expose OpenTelemetry metrics, + define a [KeptnConfig](../reference/crd-reference/config.md) resource + that has the `spec.OTelCollectorUrl` field populated + with the URL of the OpenTelemetry collector. + +The +[otel-collector.yaml](https://github.com/keptn/lifecycle-toolkit/blob/main/examples/support/observability/config/otel-collector.yaml) +is the OpenTelemetry manifest file for the PodtatoHead example, +located in the `config` directory. +To deploy and configure the OpenTelemetry collector +using this manifest, the command is: + +```shell +kubectl apply -f config/otel-collector.yaml \ + -n keptn-system +``` + +Use the following command to confirm that the pod +for the `otel-collector` deployment is up and running: + +```shell +$ kubectl get pods -lapp=opentelemetry \ + -n keptn-system + +NAME READY STATUS RESTARTS AGE +otel-collector-6fc4cc84d6-7hnvp 1/1 Running 0 92m +``` + +If you want to extend the OTel Collector configuration +to send your telemetry data to other Observability platform, +you can edit the Collector `ConfigMap` with the following command: + +```shell +kubectl edit configmap otel-collector-conf \ + -n keptn-system +``` + +When the `otel-collector` pod is up and running, +restart the `keptn-scheduler` (if installed) and `lifecycle-operator` +so they can pick up the new configuration: + +```shell +kubectl rollout restart deployment \ + -n keptn-system keptn-scheduler lifecycle-operator +``` + +Keptn begins to collect OpenTelemetry metrics +as soon as the `Deployment` resource +has the basic annotations to integrate Keptn in the cluster. + +## Access Keptn metrics as OpenTelemetry metrics + +Keptn metrics can be exposed as OpenTelemetry (OTel) metrics +via port `9999` of the Keptn metrics-operator. + +To access the metrics, use the following command: + +```shell +kubectl port-forward deployment/metrics-operator 9999 -n keptn-system +``` + +You can access the metrics from your browser at: `http://localhost:9999` diff --git a/docs-new/docs/guides/restart-application-deployment.md b/docs-new/docs/guides/restart-application-deployment.md new file mode 100644 index 0000000000..fe9ba38c2c --- /dev/null +++ b/docs-new/docs/guides/restart-application-deployment.md @@ -0,0 +1,196 @@ +# Redeploy/Restart an Application + +A [KeptnApp](../reference/crd-reference/app.md) can fail +because of an unsuccessful pre-deployment evaluation +or pre-deployment task. +For example, this happens if the target value of a +[KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) +resource is misconfigured +or a pre-deployment evaluation checks the wrong URL. + +After you fix the configuration +that caused the pre-deployment evaluation or task to fail, +you can increment the `spec.revision` value +and apply the updated `KeptnApp` manifest +to create a new revision of the `KeptnApp` +without modifying the `version`. + +Afterwards, all related `KeptnWorkloadVersions` +automatically refer to the newly created revision of the `KeptnAppVersion` +to determine whether they are allowed +to enter their respective deployment phases. + +To illustrate this, consider the following example: + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: restartable-apps + annotations: + keptn.sh/lifecycle-toolkit: "enabled" +--- +apiVersion: lifecycle.keptn.sh/v1alpha2 +kind: KeptnApp +metadata: + name: podtato-head + namespace: restartable-apps +spec: + version: "0.1.1" + revision: 1 + workloads: + - name: podtato-head-entry + version: "0.1.2" + preDeploymentTasks: + - pre-deployment-check +--- +apiVersion: lifecycle.keptn.sh/v1alpha2 +kind: KeptnTaskDefinition +metadata: + name: pre-deployment-check + namespace: restartable-apps +spec: + function: + inline: + code: | + console.error("I failed") + process.exit(1) +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: podtato-head-entry + namespace: restartable-apps + labels: + app: podtato-head +spec: + selector: + matchLabels: + component: podtato-head-entry + template: + metadata: + labels: + component: podtato-head-entry + keptn.sh/workload: podtato-head-entry + keptn.sh/app: podtato-head + keptn.sh/version: "0.1.2" + spec: + terminationGracePeriodSeconds: 5 + containers: + - name: server + image: ghcr.io/podtato-head/entry:0.2.7 + imagePullPolicy: Always + ports: + - containerPort: 9000 + env: + - name: PODTATO_PORT + value: "9000" +``` + +In this example, the `KeptnApp` executes a pre-deployment check +which clearly fails because of the `pre-deployment-check` task, +and therefore is not able to proceed with the deployment. + +After applying this manifest, +you can inspect the status of the created `KeptnAppVersion`: + +```shell +$ kubectl get keptnappversions.lifecycle.keptn.sh -n restartable-apps +NAME APPNAME VERSION PHASE +podtato-head-0.1.1-1 podtato-head 0.1.1 AppPreDeployTasks +``` + +Notice that the `KeptnAppVersion` stays +in the `AppPreDeployTasks` phase for a while, +due to the pre-check trying to run +until the failure threshold is reached. +Eventually, the `KeptnAppVersion`'s `PredeploymentPhase` +is in a `Failed` state, with the remaining phases being `Deprecated`. + + +```shell +$ kubectl get keptnappversions.lifecycle.keptn.sh -n restartable-apps -owide +NAME APPNAME VERSION PHASE PREDEPLOYMENTSTATUS PREDEPLOYMENTEVALUATIONSTATUS WORKLOADOVERALLSTATUS POSTDEPLOYMENTSTATUS POSTDEPLOYMENTEVALUATIONSTATUS +podtato-head-0.1.1-1 podtato-head 0.1.1 AppPreDeployTasks Failed Deprecated Deprecated Deprecated Deprecated +``` + + +To fix the deployment of this application, +we first need to fix the task that has failed earlier. +To do so, edit the `pre-deployment-check` `KeptnTaskDefinition`: + +```shell +kubectl -n restartable-apps edit keptntaskdefinitions.lifecycle.keptn.sh pre-deployment-check +``` + +Modify the manifest to look like this: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha2 +kind: KeptnTaskDefinition +metadata: + name: pre-deployment-check + namespace: restartable-apps +spec: + function: + inline: + code: | + console.error("Success") +``` + +To restart the deployment of our `KeptnApplication`, +edit the manifest: + +```shell +kubectl -n restartable-apps edit keptnapps.lifecycle.keptn.sh podtato-head +``` + +Increment the value of the `spec.revision` field by one: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha2 +kind: KeptnApp +metadata: + name: podtato-head + namespace: restartable-apps +spec: + version: "0.1.1" + revision: 2 # Increased this value from 1 to 2 + workloads: + - name: podtato-head-entry + version: "0.1.2" + preDeploymentTasks: + - pre-deployment-check +``` + +After those changes have been made, +you will notice a new revision of the `podtato-head` `KeptnAppVersion`: + +```shell +$ kubectl get keptnappversions.lifecycle.keptn.sh -n restartable-apps +NAME APPNAME VERSION PHASE +podtato-head-0.1.1-1 podtato-head 0.1.1 AppPreDeployTasks +podtato-head-0.1.1-2 podtato-head 0.1.1 AppDeploy +``` + +See that the newly created revision `podtato-head-0.1.1-2` +has made it beyond the pre-deployment check phase +and has reached its `AppDeployPhase`. + +You can also verify the execution of the `pre-deployment-check` +by retrieving the list of `KeptnTasks` in +the `restartable-apps` namespace: + + +```shell +$ kubectl get keptntasks.lifecycle.keptn.sh -n restartable-apps +NAME APPNAME APPVERSION WORKLOADNAME WORKLOADVERSION JOB NAME STATUS +pre-pre-deployment-check-49827 podtato-head 0.1.1 klc-pre-pre-deployment-check--77601 Failed +pre-pre-deployment-check-65056 podtato-head 0.1.1 klc-pre-pre-deployment-check--57313 Succeeded +``` + + +Notice that the previous failed instances are still available +for both `KeptnAppVersions` and `KeptnTasks`. +This may be useful historical data to keep track of +what went wrong during earlier deployment attempts. diff --git a/docs-new/docs/guides/slo.md b/docs-new/docs/guides/slo.md new file mode 100644 index 0000000000..d9767d86f4 --- /dev/null +++ b/docs-new/docs/guides/slo.md @@ -0,0 +1,167 @@ +# Analysis + +The Keptn Metrics Operator Analysis feature +allows you to validate a deployment or release +using data from the observability data provider(s) +that are configured for Keptn Metrics. +You define the quality criteria for the analysis with SLIs and SLOs: + +* A Service Level Input (SLI) identifies the data to be analysed + as a query to a data provider +* A Service Level Objective (SLO) defines the quality criteria + you define for each SLI. + +You can specify multiple Service Level Objectives (SLOs) +that are evaluated in your Analysis +and you can weight the different analyses appropriately. +At the end of the analysis, +the status returns whether your objective failed, passed, +or passed with a warning. +This is similar to the functionality provided by the Keptn v1 +[Quality Gates](https://keptn.sh/docs/1.0.x/define/quality-gates/) +feature. + +Converters are provided to +to migrate most Keptn v1 +[SLIs](https://keptn.sh/docs/1.0.x/reference/files/sli/) +and +[SLOs](https://keptn.sh/docs/1.0.x/reference/files/slo/) +to Keptn Analysis SLIs and SLOs. +For more information,see: + +* [SLO converter](https://github.com/keptn/lifecycle-toolkit/blob/main/metrics-operator/converter/slo_converter.md#slo-converter) +* [SLI converter](https://github.com/keptn/lifecycle-toolkit/blob/main/metrics-operator/converter/sli_converter.md#sli-converter) +* [Migrate Quality Gates](../migrate/metrics-observe.md) + +The Analysis result is exposed as an OpenTelemetry metric +and can be displayed on dashboard tools, such as Grafana. + +> **Note** A preliminary release of the Keptn Analysis feature + is included in Keptn v0.8.3 and v0.9.0 but is hidden behind a feature flag. + See the + [Analysis](../reference/crd-reference/analysis.md/#differences-between-versions) + reference page for instructions to activate the preview of this feature. + +## Keptn Analysis basics + +A Keptn Analysis is implemented with three resources: + +* [AnalysisValueTemplate](../reference/crd-reference/analysisvaluetemplate.md) + defines the SLI with the `KeptnMetricsProvider` (data source) + and the query to perform for each SLI + + Each `AnalysisValueTemplate` resource identifies the data source + and the query for the analysis of the SLI. + One `Analysis` can use data from multiple instances + of multiple types of data provider; + you must define a + [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) + resource for each instance of each data provider you are using. + The template refers to that provider and queries it. + +* [AnalysisDefinition](../reference/crd-reference/analysisdefinition.md) + define the list of SLOs for an `Analysis` + + An `AnalysisDefinition` resource contains a list of objectives to satisfy. + Each of these objectives must specify: + + * Failure or warning target criteria + * Whether the objective is a key objective + meaning that its failure fails the Analysis + * Weight of the objective on the overall Analysis + * The `AnalysisValueTemplate` resource that contains the SLIs, + defining the data provider from which to gather the data + and how to compute the Analysis + +* [Analysis](../reference/crd-reference/analysis.md) + define the specific configurations and the Analysis to report. + + An `Analysis` resource customizes the templates + defined inside an `AnalysisDefinition` resource + by adding configuration information such as: + + * Timeframe that specifies the range to use + for the corresponding query in the `AnalysisValueTemplate` + * Map of key/value pairs that can be used + to substitute placeholders in the `AnalysisValueTemplate` + +## Example Analysis + +Consider the following `Analysis` resource: + +{% include "../assets/crd/analysis.yaml" %} + +This `Analysis` resource: + +* Defines the `timeframe` for which the analysis is done + as between 5 am and 10 am on the 5th of May 2023 +* Adds a few specific key-value pairs that will be substituted in the query. + For instance, the query could contain the `{{.nodename}}` variable. + The value of the `args.nodename` field (`test`) + will be substituted for this string. + +The `AnalysisDefinition` resource references this `Analysis` resource +by its `name` and `namespace` and can be seen here: + +{% include "../assets/crd/analysis-definition.yaml" %} + +This simple definition contains a single objective, `response-time-p95`. +For this objective, both failure and warning criteria are defined: + +* The objective fails if the percentile 95 is less than 600 +* A warning is issued when the value is between 300 and 500 + +The total score shows that this `Analysis` +should have an overall score of 90% to pass or 75% to get a warning. +Since only one objective is defined, +this means that the analysis either passes with 100% +(response time is less than 600) +or fails with 0% (slower response time). + +The objective points to the corresponding `AnalysisValueTemplate` resource: +{% include "../assets/crd/analysis-template.yaml" %} + +This template defines a query to a provider called `prometheus`: + +```shell + sum(kube_pod_container_resource_limits{node='{{.nodename}}'}) - sum(kube_node_status_capacity{node='{{.nodename}}'}) +``` + +At runtime, the metrics operator tries to substitute +everything in`{{.variableName}}` format +with a key-value pair specified in the `Analysis` resource, +so, in this case, the query becomes: + +```shell + sum(kube_pod_container_resource_limits{node='test'}) - sum(kube_node_status_capacity{node='test'}) +``` + +The other key-value pairs such as 'project' and 'stage' are just examples of how one could pass to the provider +information similar to Keptn v1 objectives. +For a working example you can +check [here](https://github.com/keptn/lifecycle-toolkit/tree/main/test/testanalysis/analysis-controller-multiple-providers). + +## Accessing Analysis + +### Retrieve KeptnMetric values with kubectl + +Use the `kubectl get` command to retrieve all the `Analysis` resources +in your cluster: + +```shell +kubectl get analyses.metrics.keptn.sh -A + +``` + +This returns something like + +```shell +NAMESPACE NAME ANALYSISDEFINITION STATE WARNING PASS +default analysis-sample ed-my-proj-dev-svc1 +``` + +You can then describe the `Analysis` with: + +```shell +kubectl describe analyses.metrics.keptn.sh analysis-sample -n=default +``` diff --git a/docs-new/docs/guides/tasks.md b/docs-new/docs/guides/tasks.md new file mode 100644 index 0000000000..5c75dd8bc2 --- /dev/null +++ b/docs-new/docs/guides/tasks.md @@ -0,0 +1,319 @@ +# Deployment tasks + +A +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) +resource defines one or more "executables" +(functions, programs, scripts, etc) +that Keptn runs +as part of the pre- and post-deployment phases of a +[KeptnApp](../reference/crd-reference/app.md) or +[KeptnWorkload](../reference/api-reference/lifecycle/v1alpha3/index.md#keptnworkload). + +- pre-deployment (before the pod is scheduled) +- post-deployment (after the pod is scheduled) + +These `KeptnTask` resources and the +`KeptnEvaluation` resources (discussed in +[Evaluations](./evaluations.md)) +are part of the Keptn Release Lifecycle Management. + +A +[KeptnTask](../reference/api-reference/lifecycle/v1alpha3/index.md#keptntask) +executes as a runner in an application +[container](https://kubernetes.io/docs/concepts/containers/), +which runs as part of a Kubernetes +[job](https://kubernetes.io/docs/concepts/workloads/controllers/job/). +A `KeptnTaskDefinition` includes calls to executables to be run. + +To implement a `KeptnTask`: + +- Define a + [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) + resource that defines the runner to use for the container + and the executables to be run +pre- and post-deployment +- Apply [basic-annotations](./integrate.md#basic-annotations) + to your workloads to integrate your task with Kubernetes and, + if desired, creates a `KeptnApp` resource + that consolidates multiple workloads into a single application +- Annotate the appropriate + [KeptnApp](../reference/crd-reference/app.md) + resource to associate your `KeptnTaskDefinition` + with the pre- and post-deployment tasks that should be run; + see + [Pre- and post-deployment tasks and checks](./integrate.md#pre--and-post-deployment-checks) + for more information + +This page provides information to help you create your tasks: + +- Code your task in an appropriate [runner](#runners-and-containers) +- How to control the + [execution order](#executing-sequential-tasks) + of functions, programs, and scripts + since all `KeptnTask` resources at the same level run in parallel +- Understand how to use [Context](#context) + that contains a Kubernetes cluster, a user, a namespace, + the application name, workload name, and version. +- Use [parameterized functions](#parameterized-functions) + if your task requires input parameters +- [Create secret text](#create-secret-text) + and [pass secrets to a function](#pass-secrets-to-a-function) + if necessary. + +## Runners and containers + +Each `KeptnTaskDefinition` can use exactly one container with one runner. +The runner you use determines the language you can use +to define the task. +The `spec` section of the `KeptnTaskDefinition` +defines the runner to use for the container: + +Keptn provides a general Kubernetes that you can configure +to do almost anything you want: + +- The `container-runtime` runner provides + a pure custom Kubernetes application container + that you define to includes a runtime, an application + and its runtime dependencies. + This gives you the greatest flexibility + to define tasks using the language and facilities of your choice + +Keptn also includes two "pre-defined" runners: + +- Use the `deno-runtime` runner to define tasks using Deno scripts, + which use JavaScript/Typescript syntax with a few limitations. + You can use this to specify simple actions + without having to define a container. +- Use the `python-runtime` runner + to define your task using Python 3. + +For the pre-defined runners (`deno-runtime` and `python-runtime`), +the actual code to be executed +can be configured in one of four different ways: + +- inline +- referring to an HTTP script +- referring to another `KeptnTaskDefinition` +- referring to a + [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) + resource that is populated with the function to execute + +See the +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) +reference page for the synopsis and examples for each runner. + +## Executing sequential tasks + +All `KeptnTask` resources that are defined by +`KeptnTaskDefinition` resources at the same level +(either pre-deployment or post-deployment) execute in parallel. +This is by design, because Keptn is not a pipeline engine. +**Task sequences that are not part of the lifecycle workflow +should not be handled by Keptn** +but should instead be handled by the pipeline engine tools being used +such as Jenkins, Argo Workflows, Flux, and Tekton. + +If your lifecycle workflow includes +a sequence of executables that need to be run in order, +you can put them all in one `KeptnTaskDefinition` resource, +which can execute a virtually unlimited number +of programs, scripts, and functions, +as long as they are all using the same runner. +You have the following options: + +- Encode all your steps in the language of your choice + and build an image + that Keptn executes in a `container-runtime` runner. + This is often the best solution if you need to execute complex sequences + because it gives you the most flexibility.. + +- Use the `inline` syntax for one of the Keptn pre-defined runners + (either `deno-runtime` or `python-runtime`) + to code the actual calls inline in the `KeptnTaskDefinition` resource. + See + [Fields for pre-defined containers](../reference/crd-reference/taskdefinition.md/#fields-for-pre-defined-containers) + for more information. + +- Create a script that calls the functions, programs, and scripts + that need to execute sequentially + and install this on a remote webserver that Keptn can access. + Then use the `httpRef` syntax for one of the pre-defined runners + to call this script from your `KeptnTaskDefinition`, + which can set parameters for the script if appropriate. + +For more details about implementing these options, see the +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) +page. + +## Context + +A Kubernetes context is a set of access parameters +that contains a Kubernetes cluster, a user, a namespace, +the application name, workload name, and version. +For more information, see +[Configure Access to Multiple Clusters](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/). + +You may need to include context information in the `function` code +included in the YAML file that defines a +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) +resource. +For an example of how to do this, see the +[keptn-tasks.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-tasks.yaml) +file. + +A context environment variable is available via `Deno.env.get("KEPTN_CONTEXT")`. +It can be used like this: + +```javascript +let context = Deno.env.get("KEPTN_CONTEXT"); + +if (context.objectType == "Application") { + let application_name = contextdata.appName; + let application_version = contextdata.appVersion; +} + +if (context.objectType == "Workload") { + let application_name = contextdata.appName; + let workload_name = contextdata.workloadName; + let workload_version = contextdata.workloadVersion; +} +``` + +## Parameterized functions + +`KeptnTaskDefinition`s can use input parameters. +Simple parameters are passed as a single map of key values, +while the `secret` parameters refer to a single Kubernetes `secret`. + +Consider the following example: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha2 +kind: KeptnTaskDefinition +metadata: + name: slack-notification-dev +spec: + function: + functionRef: + name: slack-notification + parameters: + map: + textMessage: "This is my configuration" + secureParameters: + secret: slack-token +``` + +Note the following about using parameters with functions: + +- Keptn passes the values + defined inside the `map` field as a JSON object. +- Multi-level maps are not currently supported. +- The JSON object can be read through the environment variable `DATA` + using `Deno.env.get("DATA");`. +- Currently only one secret can be passed. + The secret must have a `key` called `SECURE_DATA`. + It can be accessed via the environment variable `Deno.env.get("SECURE_DATA")`. + +## Working with secrets + +A special case of parameterized functions +is to pass secrets that may be required +to access data that your task requires. + +### Create secret text + +To create a secret to use in a `KeptnTaskDefinition`, +execute this command: + +```shell +kubectl create secret generic my-secret --from-literal=SECURE_DATA=foo +``` + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: dummy-task + namespace: "default" +spec: + function: + secureParameters: + secret: my-secret + inline: + code: | + let secret_text = Deno.env.get("SECURE_DATA"); + // secret_text = "foo" +``` + +To pass multiple variables +you can create a Kubernetes secret using a JSON string: + +```shell +kubectl create secret generic my-secret \ +--from-literal=SECURE_DATA="{\"foo\": \"bar\", \"foo2\": \"bar2\"}" +``` + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: dummy-task + namespace: "default" +spec: + function: + secureParameters: + secret: my-secret + inline: + code: | + let secret_text = Deno.env.get("SECURE_DATA"); + let secret_text_obj = JSON.parse(secret_text); + // secret_text_obj["foo"] = "bar" + // secret_text_obj["foo2"] = "bar2" +``` + +### Pass secrets to a function + +[Kubernetes secrets](https://kubernetes.io/docs/concepts/configuration/secret/) +can be passed to the function +using the `secureParameters` field. + +Here, the `secret` value is the name of the Kubernetes secret, +which contains a field with the key `SECURE_DATA`. +The value of that field is then available to the function's runtime +via an environment variable called `SECURE_DATA`. + +For example, if you have a task function that should make use of secret data, +you must first ensure that the secret containing the `SECURE_DATA` key exists +For example: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: deno-demo-secret + namespace: default +type: Opaque +data: + SECURE_DATA: YmFyCg== # base64 encoded string, e.g. 'bar' +``` + +Then, you can make use of that secret as follows: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: deployment-hello + namespace: "default" +spec: + function: + secureParameters: + secret: deno-demo-secret + inline: + code: | + console.log("Deployment Hello Task has been executed"); + + let foo = Deno.env.get('SECURE_DATA'); + console.log(foo); + Deno.exit(0); +``` diff --git a/docs-new/docs/installation/assets/values-advance-changes.yaml b/docs-new/docs/installation/assets/values-advance-changes.yaml new file mode 100644 index 0000000000..7dfbcd8df1 --- /dev/null +++ b/docs-new/docs/installation/assets/values-advance-changes.yaml @@ -0,0 +1,16 @@ +global: + # change all installed operator registries + # e.g. the metrics operator image will be localhost:5000/keptn/metrics-operator:v0.0.0 + imageRegistry: "localhost:5000" + commonLabels: + app.kubernetes.io/version: myversion # this label will be added to all installed resources + +certManager: + enabled: true +lifecycleOperator: + enabled: false # lifecycle operator won't be installed +metricsOperator: + enabled: true + image: + tag: v0.0.0 # metrics operator will use this image tag + imagePullPolicy: Never diff --git a/docs-new/docs/installation/assets/values-only-lifecycle.yaml b/docs-new/docs/installation/assets/values-only-lifecycle.yaml new file mode 100644 index 0000000000..87444f3bb5 --- /dev/null +++ b/docs-new/docs/installation/assets/values-only-lifecycle.yaml @@ -0,0 +1,6 @@ +certManager: + enabled: true +lifecycleOperator: + enabled: true +metricsOperator: + enabled: false diff --git a/docs-new/docs/installation/assets/values-only-metrics.yaml b/docs-new/docs/installation/assets/values-only-metrics.yaml new file mode 100644 index 0000000000..b57f3179d5 --- /dev/null +++ b/docs-new/docs/installation/assets/values-only-metrics.yaml @@ -0,0 +1,6 @@ +certManager: + enabled: true +lifecycleOperator: + enabled: false +metricsOperator: + enabled: true diff --git a/docs-new/docs/installation/assets/values-remove-certmanager.yaml b/docs-new/docs/installation/assets/values-remove-certmanager.yaml new file mode 100644 index 0000000000..83c6407c06 --- /dev/null +++ b/docs-new/docs/installation/assets/values-remove-certmanager.yaml @@ -0,0 +1,2 @@ +certManager: + enabled: false diff --git a/docs-new/docs/installation/configuration/cert-manager.md b/docs-new/docs/installation/configuration/cert-manager.md new file mode 100644 index 0000000000..af8cd65785 --- /dev/null +++ b/docs-new/docs/installation/configuration/cert-manager.md @@ -0,0 +1,65 @@ +# Keptn + cert-manager.io + +Keptn includes +a light-weight, customized cert-manager +that is used to register Webhooks to the [KubeAPI](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/). +Bundling the cert-manager simplifies the installation for new users +and provides the functionality Keptn needs +without the overhead of other cert-managers. +For a description of the architecture, see +[Keptn Certificate Manager](../../components/certificate-operator/index.md). + +Keptn also works well with `cert-manager.io`. +If you are already using `cert-manager.io`, +you can continue to use it for other components +and use the Keptn cert-manager just for Keptn activities +or you can disable the Keptn cert-manager +and configure Keptn to use `cert-manager.io`. + +If you want Keptn to use `cert-manager.io`, +you must configure it *before* you install Keptn. +The steps are: + +* Install `cert-manager.io` if it is not already installed. +* Add the `Certificate` and `Issuer` CRs for `cert-manager.io`. +* (optional) Install Keptn without the built-in `keptn-cert-manager` via Helm + +## Add the CR(s) for cert-manager.io + +These are the CRs for `cert-manager.io` to be applied to your cluster: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: keptn-certs + namespace: +spec: + dnsNames: + - lifecycle-webhook-service..svc + - lifecycle-webhook-service..svc.cluster.local + - metrics-webhook-service..svc + - metrics-webhook-service..svc.cluster.local + issuerRef: + kind: Issuer + name: keptn-selfsigned-issuer + secretName: keptn-certs +--- +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: keptn-selfsigned-issuer + namespace: +spec: + selfSigned: {} +``` + +Note the following about these fields: + +* The `apiVersion` field refers to the API for the cert-manager. +* The value of the `.spec.secretName` field as well as the `.metadata.name` of the `Certificate` CR + must be `keptn-certs`. +* Substitute the namespace placeholders with your namespace, where Keptn is installed. + +See the [CA Injector](https://cert-manager.io/docs/concepts/ca-injector/) +documentation for more details. diff --git a/docs-new/docs/installation/configuration/index.md b/docs-new/docs/installation/configuration/index.md new file mode 100644 index 0000000000..a025a48b1b --- /dev/null +++ b/docs-new/docs/installation/configuration/index.md @@ -0,0 +1 @@ +# Configuration diff --git a/docs-new/docs/installation/configuration/namespace.md b/docs-new/docs/installation/configuration/namespace.md new file mode 100644 index 0000000000..b8d1bf8aa1 --- /dev/null +++ b/docs-new/docs/installation/configuration/namespace.md @@ -0,0 +1,74 @@ +# How to structure your namespaces + +You have significant flexibility to decide how many namespaces to use +and how to set them up. +See the Kubernetes +[Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) +documentation for some basic information. +You can also search and find many "Best Practices for Namespaces" +documents published on the web. + +Some considerations for Keptn: + +* Keptn primarily operates on Kubernetes + [Workload](https://kubernetes.io/docs/concepts/workloads/) + resources and + [KeptnApp](../../reference/crd-reference/app.md) + [KeptnApp](../../reference/crd-reference/app.md) + resources + that are activated and defined by annotations to each workload. +* [KeptnMetricsProvider](../../reference/crd-reference/metricsprovider.md) + resources need to be located + in the same namespace as the associated + [KeptnMetric](../../reference/crd-reference/metric.md) + resources. + But + [KeptnEvaluationDefinition](../../reference/crd-reference/evaluationdefinition.md) + resources that are used for pre- and post-deployment + can reference metrics from any namespace. + So you can create `KeptnMetrics` in a centralized namespace + (such as `keptn-system`) + and access those metrics in evaluations on all namespaces in the cluster. +* Analysis related resources + ([Analysis](../../reference/crd-reference/analysis.md), + [AnalysisDefinition](../../reference/crd-reference/analysisdefinition.md), + and + [AnalysisValueTemplate](../../reference/crd-reference/analysisvaluetemplate.md)) + reference each other via a `name` and, optionally, a `namespace` field. + The `Analysis` resource references the `AnalysisDefinition` resource, + which then references the `AnalysisValueTemplate` resources. + + * If the `namespace` in the reference is not set explicitly, + the `AnalysisDefinition` and `AnalysisValueTemplate` resources + must reside in the same namespace as the `Analysis` resource. + * If the `namespace` in the reference is set for the resources, + the `Analysis`, `AnalysisDefinition`, and `AnalysisValueTemplate` resources + can each reside in different namespaces. + + This provides configuration options such as the following: + + * You can have one namespace + with all of your `AnalysisDefinition` and `AnalysisValueTemplate` resources + and reuse them in the different namespaces where you run analyses. + + * You can have everything strictly namespaced + and always put the `AnalysisDefinition`, `AnalysisValueTemplate` + and the `Analysis` resources into the same namespace, + without adding the explicit namespace selectors + when creating references between those objects. + +* Each `KeptnApp` resource identifies the namespace to which it belongs. + If you configure multiple namespaces, + you can have `KeptnApp` resources with the same name + in multiple namespaces without having them conflict. +* You do not need separate namespaces for separate versions of your application. + The `KeptnApp` resource includes fields to define + the `version` as well as a `revision` + (used if you have to rerun a deployment + but want to retain the version number). + +So, possible namespace designs run the gamut: + +* Run all your Keptn work in a single namespace +* Create a separate namespace for each logical grouping of your Keptn work +* Create a separate namespace for each [workload](https://kubernetes.io/docs/concepts/workloads/) diff --git a/docs-new/docs/installation/configuration/vcluster.md b/docs-new/docs/installation/configuration/vcluster.md new file mode 100644 index 0000000000..544ec5153f --- /dev/null +++ b/docs-new/docs/installation/configuration/vcluster.md @@ -0,0 +1,27 @@ +# vCluster installation + +Keptn running on Kubernetes versions 1.26 and older +uses a custom +[scheduler](../../components/scheduling/index.md), +so it does not work with +[Virtual Kubernetes Clusters](https://www.vcluster.com/) +("vClusters") out of the box. +This is also an issue +if the `lifecycleOperator.schedulingGatesEnabled` Helm value is set to `false` +for Kubernetes version 1.27 and later. +See +[Keptn integration with Scheduling](../../components/scheduling/index.md) +for details. + +To solve this problem: + +1. Follow the instructions in + [Separate vCluster Scheduler](https://www.vcluster.com/docs/architecture/scheduling#separate-vcluster-scheduler) + to modify the vCluster `values.yaml` file + to use a virtual scheduler. + +1. Create or upgrade the vCluster, + following the instructions in that same document. + +1. Follow the instructions in the section below + to install Keptn in that vCluster. diff --git a/docs-new/docs/installation/index.md b/docs-new/docs/installation/index.md new file mode 100644 index 0000000000..12eae42aab --- /dev/null +++ b/docs-new/docs/installation/index.md @@ -0,0 +1,239 @@ +# Installation + +Keptn must be installed onto each Kubernetes cluster you want to monitor. +Additionally, Keptn needs to be enabled on your namespaces. +This gives you flexibility in how and where you want to use Keptn. + +Keptn v0.9.0 and later is installed using [Helm](https://helm.sh/). + +> **Note** Earlier releases could also be installed using the manifest. +> See +[Upgrade to Helm from a manifest installation](upgrade.md/#upgrade-to-helm-from-a-manifest-installation) +> if you need to upgrade from a manifest installation. + +After you install Keptn, you are ready to +[Integrate Keptn with your applications](../guides/integrate.md). + +## Supported Kubernetes versions + +Keptn requires Kubernetes v1.24.0 or later. + +Run the following to ensure that both client and server versions +are running Kubernetes versions greater than or equal to v1.24. +In this example, both client and server are at v1.24.0 +so Keptn will work. + +```shell +kubectl version --short +``` + +```shell +Client Version: v1.24.0 +Kustomize Version: v4.5.4 +Server Version: v1.24.0 +``` + +Keptn makes use of a custom scheduler +when running on Kubernetes v1.26 and earlier. +For Kubernetes v1.27 and later, scheduling is +implemented using +[Kubernetes scheduling gates](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-scheduling-readiness/), +unless the `schedulingGatesEnabled` Helm value is set to `false`. +See +[Keptn integration with Scheduling](../components/scheduling/index.md) +for details. + +If Keptn is installed on a [vCluster](https://www.vcluster.com/) with +Kubernetes v1.26 or earlier, some extra configuration +needs to be added for full compatibility. +See +[Running Keptn with vCluster](./configuration/vcluster.md) +for more information. + +## Basic installation + +Keptn is installed onto an existing Kubernetes cluster +using a Helm chart. +To modify the Keptn configuration, +you must modify the `values.yaml` file of the chart. + +The command sequence to fetch and install the latest release of Keptn is: + +```shell +helm repo add keptn https://charts.lifecycle.keptn.sh +helm repo update +helm upgrade --install keptn keptn/keptn \ + -n keptn-system --create-namespace --wait +``` + +If you want to use Keptn to observe your deployments +or to enhance them with lifecycle management +you must enable Keptn in your +[Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) +via annotations. +For example, for the `testy-test` namespace: + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: testy-test + annotations: + keptn.sh/lifecycle-toolkit: "enabled" # this tells Keptn to watch the namespace +``` + +Some helpful hints: + +* Use the `--version ` flag on the + `helm upgrade --install` command to specify a different Keptn Helm chart version. + + To get the appropriate chart version for the Keptn version you want, + use the following command: + + ```shell + helm search repo keptn --versions + ``` + + You see that the "CHART VERSION" for `keptn/keptn` v0.9.0 is 0.3.0 + so use the following command to explicitly installs Keptn v0.9.0: + + ```shell + helm upgrade --install keptn keptn/keptn \ + --version 0.3.0 \ + -n keptn-system --create-namespace --wait + ``` + +* To view which Keptn components are installed in your cluster + and verify that they are the correct ones, + run the following command: + + ```shell + kubectl get pods -n keptn-system + ``` + + The output shows all Keptn components that are running on your cluster. + +## Keptn Helm configuration + +The Keptn configuration is controlled by a set of Helm value files, +summarized in the following table. +The Keptn Helm chart is an umbrella chart +that contains subcharts for all components of Keptn. +Each component has its own Helm values file +(documented in its own README file), +that defines configurations specific to that component. + +All configuration changes for all components +can be made in one `values.yaml` file. +This is discussed more in +[Customizing the configuration of components](#customizing-the-configuration-of-components) +below. + +The following table summarizes the Keptn `values.yaml` files. + +* The "Component" column leads you to the + README files for each component where + all Helm values are documented +* The "Configuration file" column leads you to + the Helm values files for each component + +| Component | Used for | Configuration file | +|----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| --------------------| +| [Keptn](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn/README.md) | Installs subcharts, global configuration | [keptn/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn/values.yaml) | +| [lifecycle-operator](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-lifecycle-operator/README.md) | [Observability](../guides/otel.md), [Release Lifecycle Management](../core-concepts/index.md#release-lifecycle-management) | [keptn-lifecycle-operator/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-lifecycle-operator/values.yaml) | +| [metrics-operator](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-metrics-operator/README.md) | [Keptn metrics](../guides/evaluatemetrics.md), [Analysis](../guides/slo.md) | [keptn-metrics-operator/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-metrics-operator/values.yaml) | +| [cert-manager](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-cert-manager/README.md) | [TLS Certificate management for all Keptn components](../components/certificate-operator/index.md) | [keptn-cert-manager/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-cert-manager/values.yaml) | + +## Customizing the configuration of components + +To modify configuration of the subcomponents of Keptn, +use the corresponding Helm values in your `values.yaml` file. +Use the subcomponent's parent value as the root for your configuration. + +Here is an example `values.yaml` altering global and metrics operator values: + +{{< docsembed path="content/en/docs/installation/assets/values-advance-changes.yaml" >}} + +Note the additional values that are specified +in the `metricsOperator` section. +These are documented in the README file for that operator, +which is linked from the `metrics-operator` item under "Component" +in the table above. +To implement this: + +* Go into the `values.yaml` file linked under "Configuration file" +* Copy the lines for the values you want to modify +* Paste those lines into your `values.yaml` file + and modify their values in that file. + +### Modify Helm values + +To modify Helm values: + +1. Download a copy of the Helm values file: + + ```shell + helm show values keptn/keptn > values.yaml + ``` + +1. Edit your local copy to modify some values + +1. Add the following string + to your `helm upgrade` command to install Keptn + with your configuration changes: + + ```shell + --values=values.yaml + ``` + + For example, if you create a `my.values.yaml` + and modify some configuration values, + use the following command to apply your configuration: + + ```shell + helm upgrade --install keptn keptn/keptn \ + --values my.values.yaml \ + -n keptn-system --create-namespace --wait + ``` + + You can also use the `--set` flag + to specify a value change for the `helm upgrade --install` command. + Helm values are specified using the format: + + ```shell + --set key1=value1 \ + --set key2=value2 ... + ``` + +## Control what components are installed + +By default, all components are included when you install Keptn. +To specify the components that are included, +you need to modify the Keptn `values.yaml` file +to disable the components you do not want to install. + +Note that the Keptn Helm chart is quite flexible. +You can install all Keptn components on your cluster, +then modify the configuration to exclude some components +and update your installation. +Conversely, you can exclude some components when you install Keptn +then later add them in. + +### Disable Keptn Certificate Manager (Certificates) + +If you wish to use your custom certificate manager, +you can disable Keptn `cert-manager` by setting the +`certificateManager.enabled` Helm value to `false`: + +{% include "./assets/values-remove-certmanager.yaml" %} + +For more information on using `cert-manager` with Keptn, see +[Use Keptn with cert-manager.io](../components/certificate-operator/index.md). + +For the full list of Helm values, see the +[keptn-cert-manager Helm chart README](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-cert-manager/README.md). + +## Uninstalling Keptn + +To uninstall Keptn from your cluster, please follow the steps +on the [Uninstall page](./uninstall.md). diff --git a/docs-new/docs/installation/k8s.md b/docs-new/docs/installation/k8s.md new file mode 100644 index 0000000000..d4327f51e3 --- /dev/null +++ b/docs-new/docs/installation/k8s.md @@ -0,0 +1,109 @@ +# Kubernetes cluster + +Keptn is meant to be installed +into an existing Kubernetes cluster +that runs your deployment software. +See [Requirements](index.md#supported-kubernetes-versions) for information about supported releases +and advice about resources required. + +## Create local Kubernetes cluster + +You can also create a local cluster using packages such as +[KinD](https://kind.sigs.k8s.io/), +[k3d](https://k3d.io/), +[k3s](https://k3s.io/), +and [Minikube](https://minikube.sigs.k8s.io/docs/) +to set up a local, lightweight Kubernetes cluster +where you can install Keptn +for personal study, demonstrations, and testing. +For more information, see the Kubernetes +[Install Tools](https://kubernetes.io/docs/tasks/tools/) +documentation. + +The [Keptn: Installation and KeptnTask Creation in Minutes](https://www.youtube.com/watch?v=Hh01bBwZ_qM) +video demonstrates how to create a KinD cluster. +on which you can install Keptn. +The basic steps are: + +1. Download, install, and run [Docker](https://docs.docker.com/get-docker/) +2. Download [KinD](https://kind.sigs.k8s.io/) +3. Create the local KinD cluster with the following command: + + ```shell + kind create cluster + ``` + + See the + [KinD Quick Start Guide](https://kind.sigs.k8s.io/docs/user/quick-start/) + for more information + +4. When the cluster has been created, + run the following to verify that the cluster is working + and that it is running a supported version of Kubernetes + with the following command: + + ```shell + kubectl version --short + ``` + +## Prepare your cluster for Keptn + +Keptn installs into an existing Kubernetes cluster. +When setting up a local Kubernetes cluster to study or demonstrate Keptn, +you need to provide these components. + +Your cluster should include the following: + +* A supported version of Kubernetes. + See [Supported Kubernetes versions](index.md#supported-kubernetes-versions) + for details. + +* The + [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) + CLI that is used to interact with Kubernetes clusters. + +* The + [Helm](https://helm.sh/docs/intro/install/) + CLI that is used to install and configure Keptn. + +* Deployment tools of your choice, + such as + [Argo CD](https://argo-cd.readthedocs.io/en/stable/) or + [Flux](https://fluxcd.io/). + Alternatively, Keptn also works with just `kubectl apply` for deployment. + +* At least one observability data provider such as + [Prometheus](https://prometheus.io/), + [Dynatrace](https://www.dynatrace.com/), + or [Datadog](https://www.datadoghq.com/); + you can use multiple instances of different data providers. + These provide: + + * Metrics used for + [Keptn Metrics](../guides/evaluatemetrics.md/) + * Metrics used for + [OpenTelemetry](../guides/otel.md/) + observability + * SLIs for pre- and post-deployment + [evaluations](../guides/evaluations.md/) + * SLIs used for + [analyses](../guides/slo.md) + +* If you want to use the standardized observability feature, + you must have an OpenTelemetry collector + as well as a Prometheus operator installed on your cluster. + For more information, see + [Requirements for OpenTelemetry](../guides/otel.md/#requirements-for-opentelemetry). + +* If you want a dashboard for reviewing metrics and traces, + install the dashboard tools of your choice; + we primarily use Grafana. + For more information, see + [Requirements for Open Telemetry](../guides/otel.md/#requirements-for-opentelemetry). + +* Keptn includes a lightweight `cert-manager` that, by default, + is installed as part of the Keptn software. + If you are using another certificate manager in the cluster, + you can configure Keptn to instead use your cert-manager. + See [Use Keptn with cert-manager.io](./configuration/cert-manager.md) + for detailed instructions. diff --git a/docs-new/docs/installation/tips-tricks.md b/docs-new/docs/installation/tips-tricks.md new file mode 100644 index 0000000000..ae67287c77 --- /dev/null +++ b/docs-new/docs/installation/tips-tricks.md @@ -0,0 +1,143 @@ +# Installation Tips and Tricks + +The +[Install Keptn](index.md) +page documents how to install Keptn. +This page provides some background and more examples +that supplement that information. + +## Umbrella chart + +Keptn v0.9.0 and later is installed using a Helm umbrella chart. +This means that the Helm Chart that installs all of Keptn +actually groups subcharts for individual components +and you can install individual components +without installing all of Keptn. + +Keptn is installed using the +[Keptn](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn) +umbrella Helm chart. +Each subchart has its own README file describing possible configuration options, +but configuration changes for the subcharts are added to a single `values.yaml` file. +See +[Customizing the configuration of components](index.md#customizing-the-configuration-of-components) +for an example. + +## Installing older versions of Keptn + +Installation of Keptn v0.9.0 has two significant differences +compared to the installation of earlier releases: + +* Keptn v0.9.0 and later releases use + the umbrella charts whereas earlier versions did not +* Keptn v0.9.0 and later releases use + the `keptn` Helm chart, whereas earlier + releases used the `klt` chart. + +To install a version prior to v0.9.0, +use the install command sequence that is documented for that release. +To install the latest version, use the installation commands on the +[Install Keptn](index.md#basic-installation) +[Install Keptn](index.md#basic-installation) +page. + +To install an older release, +specify the chart version with the `--version` flag +in the `helm upgrade --install` command for the release you are installing. + +## Example configurations by use-case + +[Control what components are installed](index.md#customizing-the-configuration-of-components) +discusses how to configure Keptn to include only the components you want. +The following sections summarize and give examples +of the configurations needed for different use cases. + +### Enable Keptn Lifecycle Operator (Observability and/or Release Lifecycle) + +If you only want to run the Keptn Observability +and/or Release Lifecycle use-cases in your cluster, +you do not need to install the Keptn Metrics Operator. +To disable it, set the `metricsOperator.enabled` value +to `false` as in the following: + +{% include "./assets/values-only-lifecycle.yaml" %} + +Note that, if you want to run pre- and/or post-deployment +[evaluations](../guides/evaluations.md) +as part of the Release Lifecycle use-case, +you need to have the Keptn Metrics Operator installed. + +You must also enable Keptn for each +[namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) +on which you want to run either +the Observability or Release Lifecycle use-case. + +To enable Keptn, annotate the appropriate `Namespace` resource(s). +For example, for the `simplenode-dev` namespace, +the annotation looks like this: + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: simplenode-dev + annotations: + keptn.sh/lifecycle-toolkit: "enabled" +``` + +You see the annotation line `keptn.sh/lifecycle-toolkit: "enabled"`. + +After enabling Keptn for your namespace(s), +you are ready to +[Integrate Keptn with your applications](../guides/integrate.md). + +For more information about implementing Observability, see the +[Observability User Guide](../guides/otel.md). + +For more information about implementing Keptn Release Lifecycle, see the +[Deployment tasks](../guides/tasks.md) +and +[Evaluations](../guides/evaluations.md) +User Guides. + +### Enable Keptn Metrics Operator (Metrics) + +If you are only interested in Metrics, +you do not need the Keptn Lifecycle Operator. +Disable it using the following values.yaml: + +{% include "./assets/values-only-metrics.yaml" %} + +For more information about implementing Metrics, see the +[Metrics User Guide](../guides/evaluatemetrics.md). + +### Enable Keptn Analysis (SLOs/SLIs) + +To enable Keptn Analysis in your cluster, +you again do not need the Keptn Lifcycle Operator. +Disable it using the following values.yaml: + +{% include "./assets/values-only-metrics.yaml" %} + +> **Note** A preliminary release of the Keptn Analysis feature + is included in Keptn v0.8.3 and v0.9.0 but is hidden behind a feature flag. + See the + [Analysis](../reference/crd-reference/analysis.md/#differences-between-versions) + reference page for how to activate the preview of this feature. +> + +For more information about implementing Keptn Analysis, see the +[Analysis User Guide](../guides/slo.md). + +### Disable Keptn Certificate Manager (Certificates) + +If you wish to use your own custom certificate manager, +you can disable the Keptn `cert-manager` by using the +`--set certificateManager.enabled=false` argument +to the `helm upgrade` command line +or you can modify the `values.yaml` file: + +{% include "./assets/values-remove-certmanager.yaml" %} + +For more information about using `cert-manager` with Keptn, see +[Use Keptn with cert-manager.io](./configuration/cert-manager.md). diff --git a/docs-new/docs/installation/troubleshooting.md b/docs-new/docs/installation/troubleshooting.md new file mode 100644 index 0000000000..ce3d8a81be --- /dev/null +++ b/docs-new/docs/installation/troubleshooting.md @@ -0,0 +1,69 @@ +# Troubleshooting Guide + +Welcome to the Keptn troubleshooting guide. + +This guide will help you address common issues that you might encounter while using Keptn +for managing your [workloads](https://kubernetes.io/docs/concepts/workloads/). +Below are some common problems and their solutions: + +## Keptn is installed but it is not aware of my workloads + +If you are facing an issue where Keptn is installed but does not seem to be aware of your +[workloads](https://kubernetes.io/docs/concepts/workloads/), follow these steps: + +1. Ensure that the namespace you wish to target is [annotated correctly](index.md#basic-installation). +2. Make sure your [workloads](https://kubernetes.io/docs/concepts/workloads/) + (e.g., Deployment manifests) have the [three required annotations](https://lifecycle.keptn.sh/docs/implementing/integrate/#annotate-workloads). + +## Keptn is causing my pods to be pending + +If your pods are stuck in a pending state and Keptn seems to be the cause, it might be due +to a pre-deployment task or evaluation. +Follow these steps: + +The most probable reason is that a pre-deployment task in your +[workload](https://kubernetes.io/docs/concepts/workloads/) is either failing or has not completed yet. + +Failing pre-deployment evaluation tasks will prevent a pod from being scheduled. + +Check the logs of the pre-deployment task Kubernetes Jobs for insights. + +For instance, if +your application is in the `prod` namespace: + +```shell +kubectl -n prod get pods +kubectl -n prod logs job/... +``` + +## I have pending Pods after Keptn is uninstalled + +> **Note**_ This section particularly affects clusters managed by ArgoCD. + +If you have uninstalled Keptn and are now facing issues scheduling or deleting pods, follow these steps: + +ArgoCD does not delete various CRDs and webhooks, when uninstalling applications, causing lingering resources. + +### For cleanup instructions + +1. Install Keptn & CRDs w/ Argo +2. Uninstall Keptn via Argo +3. Cluster is frozen, Pods cannot be deleted or scheduled + +Trying to schedule a new pod results an `mpod.keptn.sh` error. + +Reason: Argo doesn't remove the CRDs and global objects (mutating webhooks) and the +[default failurePolicy is to fail](https://github.com/keptn/lifecycle-toolkit/blob/650ecba95624ed3dc2bd61bf1f86578f450223a5/operator/config/webhook/manifests.yaml#L17). + +to get further information refer to this [issue](https://github.com/keptn/lifecycle-toolkit/issues/1828). + +## I cannot see DORA metrics or OpenTelemetry traces + +Keptn will automatically generate DORA metrics and OTel traces for every deployment, but +by default it does not know where to send them. + +You need an OpenTelemetry collector +installed and configured on the cluster. + +[The OpenTelemetry observability page](https://lifecycle.keptn.sh/docs/implementing/otel/) +contains more information on how to configure this. diff --git a/docs-new/docs/installation/uninstall.md b/docs-new/docs/installation/uninstall.md new file mode 100644 index 0000000000..d7008b335e --- /dev/null +++ b/docs-new/docs/installation/uninstall.md @@ -0,0 +1,17 @@ +# Uninstall + +> **Warning** +Please be aware that uninstalling Keptn from your cluster +will cause loss of all your Keptn data. + +If you installed the previous version of Keptn using `helm`, +you can uninstall it together with all CRDs, webhooks and +custom resources with using the following command: + +```shell +helm uninstall keptn -n keptn-system +``` + +If your Keptn instance is not installed in the +`keptn-system` namespace, please substitute +it with your custom one. diff --git a/docs-new/docs/installation/upgrade.md b/docs-new/docs/installation/upgrade.md new file mode 100644 index 0000000000..bce427c570 --- /dev/null +++ b/docs-new/docs/installation/upgrade.md @@ -0,0 +1,96 @@ +# Upgrade + +If you installed the previous version of Keptn using `helm`, +you can upgrade to the latest version +by running the same command sequence used to install Keptn: + +```shell +helm repo add keptn https://charts.lifecycle.keptn.sh +helm repo update +helm upgrade --install keptn keptn/keptn \ + -n keptn-system --create-namespace --wait +``` + +Use the `--set` flag or download and edit the `values.yaml` file +to modify the configuration as discussed on the +[Install Keptn](./index.md) page. + +> **Warning** +If you installed your Keptn instance from the Manifest, +additional steps are required to use the Helm Chart to upgrade. +Contact us on Slack for assistance. + +## Upgrade to Helm from a manifest installation + +> **Warning** +Upgrade to Helm from a manifest installation can cause loss +of Keptn custom resources. + +Keptn v.0.7.0 and later can be installed with Helm charts; +Keptn v.0.8.3 can only be installed with Helm. +If you previously installed Keptn from manifests, +you can not directly upgrade with Helm but must back up your manifests, +then reinstall Keptn from a Helm chart and re-apply your manifests. + +To start the upgrade process, follow the steps below: + +1. To not loose all of your data, we encourage you to do a backup of the manifests, +which you applied to the cluster (`Pods`, `Deployments`, +`StatefulSets`, `DaemonSets`, `KeptnApps`,... ). +After the re-installation of Keptn with Helm, you can re-apply +these manifests and restart the Keptn deployment process. + +1. Completely remove your Keptn installation with the following command sequence: + +```shell +your-keptn-version= +kubectl delete -f \ + https://github.com/keptn/lifecycle-toolkit/releases/download/$your-keptn-version/manifest.yaml +``` + +1. Use Helm to install a clean version of Keptn: + +```shell +helm repo add keptn https://charts.lifecycle.keptn.sh +helm repo update +helm upgrade --install keptn keptn/keptn -n keptn-system --create-namespace --wait +``` + +For information about advanced installation options, refer to +[Modify Helm configuration options](./index.md). + +1. After the installation finishes, restore the manifests from you backup + +> **Warning** Please be aware that Keptn applications will start the deployment process from the +beginning and the system is not guaranteed to return +to the exact state it was in before re-installation, even if you created the backup correctly. + +## Migrate from v0.6.0 to v0.7.0 + +Keptn Version v0.7.0 +introduces the `metrics-operator`, +which is now separate from the `lifecycle-operator`. +Some functionality and behavior has been moved, changed, or renamed. + +Specifically, the `KeptnMetricsProvider` CRD replaces +the now-deprecated `KeptnEvaluationProvider` CRD. +Consequently, you must manually migrate the existing functionality +to the `KeptnMetricsProvider` CRD. +Execute the following external bash script to do this: + +```shell +curl -sL https://raw.githubusercontent.com/keptn/lifecycle-toolkit/main/.github/scripts/keptnevaluationprovider_migrator.sh | bash +``` + +This fetches and migrates all `KeptnEvaluationProvider` CRs +for the cluster at which your kubernetes context is pointing. +If you have multiple clusters, +you must run this command for each one. + +This script does the following: + +* Fetch all existing `KeptnEvaluationProvider` CRs +* Migrate each to `KeptnMetricsProvider` CRs +* Store the migrated manifests in the current working directory +* Ask the user to apply the created manifests + and delete the deprecated `KeptnEvaluationProvider` CRs. diff --git a/docs-new/docs/migrate/index.md b/docs-new/docs/migrate/index.md new file mode 100644 index 0000000000..30ab2a351f --- /dev/null +++ b/docs-new/docs/migrate/index.md @@ -0,0 +1,12 @@ +# Migrating to Keptn + +Keptn uses a different paradigm than that used for Keptn v1 +and so migration from Keptn v1 is not a straight-forward process. +In this section, we will assemble information to help people +who want to move from Keptn v1. + +These instructions mostly assume that you want to utilize +all Keptn features. +Note, however, that you can install and use some functionality +such as Keptn Metrics and Observability +without implementing all Keptn features. diff --git a/docs-new/docs/migrate/metrics-observe.md b/docs-new/docs/migrate/metrics-observe.md new file mode 100644 index 0000000000..e8d9ecce23 --- /dev/null +++ b/docs-new/docs/migrate/metrics-observe.md @@ -0,0 +1,337 @@ +# Migrate Quality Gates + +The SLIs and SLOs used for Keptn v1 quality gates can be ported to +appropriate Keptn facilities: + +* [Keptn Metrics](../guides/evaluatemetrics.md/) + allow you to define and view metrics + from multiple data sources in your Kubernetes cluster. +* Use + [Keptn Evaluations](../guides/evaluations.md) + to do a simple evaluation of the metrics data you capture. + To implement this, transfer the information from the Keptn v1 + [sli.yaml](https://keptn.sh/docs/1.0.x/reference/files/sli/) + and + [slo.yaml](https://keptn.sh/docs/1.0.x/reference/files/slo/) + files into + [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) + resources. + +* Keptn v1 calculations that use weighting and scoring + can be converted to use the + [Keptn Analysis](../guides/slo.md) + feature. + Tools are provided to help with this conversion; + see below. + +By default, Keptn includes additional observability features +that are not included in Keptn v1: + +* [DORA metrics](../guides/dora.md) +* [OpenTelemetry observability](../guides/otel.md) + +## Paradigm changes + +The Keptn paradigm for evaluations and analyses +differs from that of Keptn v1 quality gates: + +* Data providers are installed and configured into your Kubernetes cluster + using Helm charts and standard practices. +* Keptn supports multiple instances of multiple data providers. +* You must populate a + [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) resource + for each instance of each data provider. + This resource specifies the URL and namespace for the data provider + and gives it a unique `name` that can be referenced + for Keptn Metrics (which are also used for Evaluations) and Analysis. +* Queries and objectives that are specified in your Keptn v1 + [sli.yaml](https://keptn.sh/docs/1.0.x/reference/files/sli/) + and + [slo.yaml](https://keptn.sh/docs/1.0.x/reference/files/slo/) + files are transferred/converted into Keptn resources. + +## Transfer Keptn v1 SLIs/SLOs to evaluation resources + +Simple comparisons of data can be implemented as +[Keptn Evaluations](../guides/evaluations.md). +To implement this: + +* Transfer the information from the Keptn v1 + [sli.yaml](https://keptn.sh/docs/1.0.x/reference/files/sli/) + files into + [KeptnMetric](../reference/crd-reference/metric.md) resources +* Transfer the information from the Keptn v1 + [slo.yaml](https://keptn.sh/docs/1.0.x/reference/files/slo/) + files into + [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) + resources. + +## Convert Keptn v1 SLIs/SLOs to Analysis resources + +The Keptn Analysis feature provides capabilities +similar to those of the Keptn v1 +[Quality Gates](https://keptn.sh/docs/1.0.x/define/quality-gates/) +feature +but it uses Kubernetes resources to define the analysis to be done +rather than the configuration files used for Keptn v1. +Tools are provided to convert Keptn v1 SLI and SLO definitions +to Keptn Analysis resources. + +These instructions assume that the same SLO file +has been used for all services in the project, +so only one `AnalysisDefinition` resource +(named `my-project-ad`) is created. +If your Keptn v1 project has multiple SLOs, +you need to create a separate `AnalysisDefinition` +with a unique name for each one. + +The process is: + +1. Convert the SLIs to `AnalysisValueTemplates` resources + + The following command sequence converts a Keptn v1 + [sli.yaml](https://keptn.sh/docs/1.0.x/reference/files/sli/) + file to a Keptn + [AnalysisValueTemplate](../reference/crd-reference/analysisvaluetemplate.md) + resource: + + + + ```shell + METRICS_OPERATOR_IMAGE=ghcr.io/keptn/metrics-operator:v0.8.3 + PATH_TO_SLI=sli.yaml + KEPTN_PROVIDER_NAME=my-prometheus-provider + KEPTN_PROVIDER_NAMESPACE=keptn-lifecycle-poc + + docker run -v .:/mydata $METRICS_OPERATOR_IMAGE \ + --convert-sli=mydata/$PATH_TO_SLI \ + --keptn-provider-name=$KEPTN_PROVIDER_NAME \ + --keptn-provider-namespace=$KEPTN_PROVIDER_NAMESPACE > analysis-value-template.yaml + ``` + + + + This command creates an `AnalysisValueTemplate` resource + for each SLI that is defined in the `sli.yaml` file. + + > **Note** + The `name` of each `AnalysisValueTemplate` resource + must adhere to the + [Kubernetes resource naming rules](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/). + The conversion tools preserve the name of each SLI + but modify the names to match the Kubernetes requirements. + For example, the `Response_Time` SLI + generates an `AnalysisValueTemplate` that is named `response-time`. + > + + All the SLIs for a particular `sli.yaml` file + are defined in a file called `analysis-value-template.yaml`. + Apply this file to your cluster with a command like the following. + Be sure to specify the namespace; + if you omit it, the yaml file is applied to the default namespace. + + ```shell + kubectl apply -f analysis-value-template.yaml -n keptn-lifecycle-poc + ``` + +1. Convert the SLO to an `AnalysisDefinition` resource: + + The process of converting the Keptn v1 + [slo.yaml](https://keptn.sh/docs/1.0.x/reference/files/slo/) + files to + [AnalysisDefinition](../reference/crd-reference/analysisdefinition.md) + resources is similar to the process of converting the SLIs. + Use the following command sequence: + + + + ```shell + METRICS_OPERATOR_IMAGE=ghcr.io/keptn/metrics-operator:v0.8.3 + PATH_TO_SLO=slo.yaml + ANALYSIS_VALUE_TEMPLATE_NAMESPACE=keptn-lifecycle-poc + ANALYSIS_DEFINITION_NAME=my-project-ad + + docker run -v $(pwd):/mydata $METRICS_OPERATOR_IMAGE \ + --convert-slo=/mydata/$PATH_TO_SLO \ + --analysis-value-template-namespace=$ANALYSIS_VALUE_TEMPLATE_NAMESPACE \ + --analysis-definition-name=$ANALYSIS_DEFINITION_NAME > analysis-definition.yaml + ``` + + + + The result of this command yields an `AnalysisDefinition` resource + that is defined in a file called `analysis-definition.yaml`. + Apply this to your Keptn cluster with the following command. + Be sure to add the namespace; + if you omit it, the yaml file is applied to the default namespace. + + ```shell + kubectl apply -f analysis-definition.yaml -n keptn-lifecycle-poc + ``` + +1. Create a `KeptnMetricsProvider` resource + + A [KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) + resource configures the data provider from which the values + for the `AnalysisValueTemplate` resource are fetched. + This same resource is used for any metrics and evaluations you are using. + Note that Keptn supports multiple instances of multiple data providers + and each `AnalysisValueTemplate` resource + can reference a different provider, + + The `KeptnMetricsProvider` resource defines: + + * The URL of the server used for your data provider + * The namespace where the data provider is located + * (optional) Secret information to access a protected data source + + See the `prometheus-provider` file for an example. + +1. Define the Analysis resource to run + + Create a yaml file (such as `analysis-instance.yaml`) + to populate the + [Analysis](../reference/crd-reference/analysis.md) + resource that defines the specific analysis you want to run. + Specify the following: + + * Name of the `AnalysisDefinition` resource that defines the goals + * Timeframe for which to retrieve the metrics. + The `from`/`to` timestamps are added automatically + to the query defined in the `AnalysisValueTemplate` resource. + * (optional) List of `args` that specify values for this analysis + that replace variables used in the queries + in the `AnalysisValueTemplate` resources. + See + [Passing contextual arguments to the Analysis](#passing-contextual-arguments-to-the-analysis) + for more information. + +1. Run the analysis + + To perform an Analysis (or "trigger an evaluation" in Keptn v1 jargon), + apply the `analysis-instance.yaml` file: + + ```shell + kubectl apply -f analysis-instance.yaml -n keptn-lifecycle-poc + ``` + + Retrieve the current status of the Analysis with the following command: + + ```shell + kubectl get analysis -n keptn-lifecycle-poc + ``` + + This yields an output that looks like the following: + + ```shell + NAME ANALYSISDEFINITION WARNING PASS + analysis-sample-1 my-project-ad true + ``` + + This shows that the analysis passed successfully. + + To get the detailed result of the evaluation, + use the `-oyaml` argument to inspect the full state of the analysis: + + This displays the `Analysis` resource + with the definition of the analysis + as well as the `status` (results) of the analysis; for example: + + ```shell + kubectl get analysis -n keptn-lifecycle-poc -oyaml + ``` + + ```yaml + apiVersion: v1 + items: + - apiVersion: metrics.keptn.sh/v1beta1 + kind: Analysis + metadata: + creationTimestamp: "2023-09-14T11:00:01Z" + generation: 4 + name: analysis-sample-1 + namespace: keptn-lifecycle-poc + resourceVersion: "71327" + uid: 1c5e043d-ed5e-42f8-ba32-b7af54b55c35 + spec: + analysisDefinition: + name: my-project-ad + namespace: keptn-lifecycle-poc + args: + ns: keptn-system + project: my-project + timeframe: + from: "2023-09-14T11:20:19Z" + to: "2023-09-14T11:22:19Z" + status: + pass: true + raw: '{"objectiveResults":[{"result":{"failResult":{"operator":{"greaterThan":{"fixedValue":"50"}}},"warnResult":{"operator":{"greaterThan":{"fixedValue":"50"}}},"pass":true},"value":7,"score":1}],"totalScore":1,"maximumScore":1,"pass":true}' + kind: List + metadata: + resourceVersion: "" + ``` + + As can be seen in the yaml above, + the `status.raw` property contains the detailed breakdown + of the analysis goals, and whether or not they passed. + + The result of this analysis stays in the cluster + until the `Analysis` is deleted. + That also means that, if another analysis should be performed, + the new analysis must be given a new, unique name within the namespace. + +### Passing contextual arguments to the Analysis + +In some cases, especially when migrating from Keptn v1, +you may want to do an analysis for different services within a project +and adapt the query for fetching the metric values, +based on which service/stage you are evaluating. +Keptn enables you to do this by using variables in the query defined in the +`AnalysisValueTemplates` resource +and arguments that are defined in the `Analysis` resource +for the specific analysis being run. + +For example, you may have a query +for retrieving the response time of a service, +which is identified by its label in Prometheus. +In this case, use the go templating syntax +to insert a variable as a placeholder +(for example, in this case, `{{.service}}`) +for the service identifier in the prometheus query: + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: AnalysisValueTemplate +metadata: + creationTimestamp: null + name: response-time +spec: + provider: + name: my-prometheus-provider + namespace: keptn-lifecycle-poc + query: response_time{label="{{.service}}"} +``` + +Then, if an analysis for that particular service should be performed, +the name of the service can be passed to the analysis +using the `spec.args` property from the `Analysis` resource: + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: Analysis +metadata: + name: analysis-sample-1 + namespace: keptn-lifecycle-poc +spec: + timeframe: + from: 2023-09-14T11:20:19Z + to: 2023-09-14T11:22:19Z + args: + "service": "my-service" + analysisDefinition: + name: my-project-ad + namespace: keptn-lifecycle-poc +``` + +This way, you can use the same `AnalysisDefinition` +and `AnalysisValueTemplates` for multiple services within the same project. diff --git a/docs-new/docs/migrate/strategy.md b/docs-new/docs/migrate/strategy.md new file mode 100644 index 0000000000..92e9476fc9 --- /dev/null +++ b/docs-new/docs/migrate/strategy.md @@ -0,0 +1,356 @@ +# Migration strategy + +> **Note** +This section is under development. +Information that is published here has been reviewed for technical accuracy +but the format and content is still evolving. +We hope you will contribute your experiences +and questions that you have. + +Before you begin the migration project, +we suggest that you run through the exercises in +[Getting started](../getting-started/index.md) +to familiarize yourself with how Keptn works. +When you are ready to begin the migration, +follow the instructions in +[Installation and upgrade](../installation/index.md) +to set up your Kubernetes cluster +and install Keptn on it. + +On this page, we discuss some of the major paradigm shifts +in Keptn relative to Keptn v1 +and then discuss how elements of your Keptn v1 can be implemented +for Keptn. + +## The Keptn cloud native paradigm + +Keptn uses a different paradigm +than Keptn v1 and so migration requires technical adjustments. +Much of the logic and functionality of your Keptn v1 projects +can be migrated to Keptn +but must be rewritten to utilize Keptn components. + +Some key points: + +* Keptn uses native Kubernetes CRDs + to configure SLIs/SLOs, tasks, and other elements + that are part of the environment where the application deployment lives + rather than using its own Git repo and its + [shipyard.yaml](https://keptn.sh/docs/1.0.x/reference/files/shipyard/) + file as Keptn v1 does. + * See the + [Lifecycle CRD Reference](../reference/crd-reference/index.md) + and + [Metrics CRD Reference](../reference/crd-reference/index.md) + section for pages that describe the Keptn manifests + that you populate manually for Keptn. + * See the + [API Reference](../reference/api-reference/index.md) + for a comprehensive reference to all resources + defined for Keptn. + +* Keptn is not a delivery tool + because it does not provide promotion. + Instead, it works with standard deployment tools + such as ArgoCD, Flux, even `kubectl -- apply`. + Keptn then prevents the scheduling and deployment + of workflows if the environment does not meet + the user-defined requirements. + +* Keptn operates on a + [KeptnApp](../reference/crd-reference/app.md) + resource + that is an amalgamation of multiple Kubernetes workloads, + which together comprise the released application. + Each workload deploys a separate microservice, + which can be deployed at different times using different tools. + +* Keptn integrates with continuous delivery tools + to insures that a `KeptnApp` is not deployed + if it does not meet the user-defined requirements + for all the associated workloads. + It also exposes metrics to evaluate the success/status of a deployment. + +* Keptn provides an operator + that can observe and orchestrate application-aware workload life cycles. + This operator leverages Kubernetes webhooks + and the Kubernetes scheduler + to support pre- and post-deployment hooks. + When the operator detects a new version of a service + (implemented as a Kubernetes + [Workload](https://kubernetes.io/docs/concepts/workloads/)), + it can execute pre- and post-deployment evaluations and tasks + using Kubernetes capabilities. + +* Keptn provides extensive observability data + using OpenTelemetry and Prometheus + rather than storing the data in a special Keptn database. + This data can be displayed using Grafana and Jaeger + or the dashboard of your choice. + +For in-depth information about Keptn components +and how they work, see the +[Architecture](../components/index.md) +section. + +## Disposition of Keptn v1 components in Keptn + +To help you wrap your mind around the migration process, +this lists Keptn v1 components +and identifies their possible disposition when you migrate to Keptn. + +### project + +A Keptn v1 project represents an arbitrary, higher-level grouping of services. +A project is defined by a +[shipyard.yaml](https://keptn.sh/docs/1.0.x/reference/files/shipyard/) +file. + +Keptn does not recognize projects. +Many Keptn v1 projects may translate into `KeptnApp` resources +but others will not. +For example, if your Keptn v1 project has a large number of services, +you may want to aggregate them into separate `KeptnApp` resources. +A project has a 1:1 mapping to a Git repo, +but, since few applications are stored in a mono-repo, +it is difficult to implement a project-as-application paradigm. + +In general, the Keptn v1 project is a useful as a reference list +when migrating to Keptn. +but may not directly translate to a Keptn resource. + +### service + +A Keptn v1 service models a smaller chunk of a project. +Most projects include many services. +In a micro-services world, +a service may represent a micro-service +but it could instead be a wrapper for something else, +like "the entire public website" + +Keptn does not have the concept of a service. +When migrating to Keptn, +you need to analyze what each service is doing +and translate that into an appropriate resource. +The closest analogy is a Kubernetes +[workload](https://kubernetes.io/docs/concepts/workloads/) +but some services may be translated into +[KeptnTaskDefinition](../reference/crd-reference/app.md) +or other resources. + See +[Working with Keptn tasks](../guides/tasks.md) +for more information. + +For example: + +* A Keptn v1 service that runs chaos or load tests + can probably be translated into + a `KeptnTask` using the `container-runner`. +* A Keptn v1 service that runs a database + can probably be translated + into a Kubernetes `StateFulSet` workload; see + [Workload Resources](https://kubernetes.io/docs/concepts/workloads/controllers/) + for more information. +* A Keptn v1 service that runs a webserver + can probably be translated into + a Kubernetes `Deployment` workload. + +### stage + +A stage is a subsection of a project. +Because Keptn is not a delivery tool, +it has no concept of a `stage` +but rather depends on a deployment engine. +However, the logic of the stages can be useful +when architecting the migration: + +* A **deployment stage** -- may define sequences of tasks + that should be translated into + [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) + resources that are executed pre- and post-deployment +* A **testing stage** may define sequences of tasks + that should be translated into `KeptnTaskDefinition` resources + that are executed pre- and post-deployment. + +Stage functionality could be implemented in many different ways. +Some functionality might be implemented in different namespaces +or even in different Keptn-enabled clusters, +allowing a tool such as ArgoCD to handle promotion. + +### sequence + +A sequence is an ordered and user-defined sequence of tasks +that are defined in a +[shipyard.yaml](https://keptn.sh/docs/1.0.x/reference/files/shipyard/) +file. +The shipyard controller micro-service reads the shipyard file +and (when the time is right), +emits a `taskName.triggered` cloud event onto the event bus. +The shipyard controller waits to receive a `taskName.started` event +and a correspondingly equal number of `taskName.finished` events +before the shipyard controller reads the next task +and emits a `taskName.finished` event for that task. + +In this way, you can define arbitrary sequences of any tasks +at any length and also link (or chain) sequences together +to form (primitive) workflows. +When migrating, these sequences of tasks can often be translated into +[KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) +resources that are defined to run either pre- or post-deployment +of the pod-scheduling phase. + +The `shipyard` file is a general purpose workflow engine +that is backed by cloud events. +It is not opinionated to a tool, platform, technology, +or a particular "slice" of the lifecycle. +The `TriggeredOn` property allows +a Keptn v1 sequence to be triggered at any time +by a user or another system. +This capability can be used, for example, +to trigger a data encryption and backup operation, +or a file movement over a network, or other arbitrary activities +that may or may not have anything to do with an application's lifecycle. + +When migrating to Keptn, +sequences that are not part of the lifecycle workflow +should not be handled by Keptn +but should instead be handled by the pipeline engine tools being used +such as Jenkins, Argo Workflows, Flux, and Tekton. + +### task + +Keptn v1 defines some specific types of tasks, +each of which is translated to a Keptn resource +that is appropriate for the activity: + +* A Keptn v1 **deployment task** becomes a + [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), + [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/), + or [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), + workload. + You can code + [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md) + and + [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) + resources that are configured + to run either pre- or post-deployment tasks +* An **evaluation task** becomes a + [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) + resource. +* All other standard tasks + (**action**, **approval**, **get-action**, **rollback**, + **release**, **test**) + as well as custom task types + that might be defined should be translated into + `KeptnTaskDefinition` resources. +* The `key:value` **properties** for each Keptn v1 sequence + should be coded into the `KeptnTaskDefinition` resource + as appropriate. + +Note that all `KeptnTask` resources at the same level +(either pre-deployment or post-deployment) +execute in parallel +whereas Keptn v1 sequences and tasks can not execute in parallel. + +* If you have actions that need to execute sequentially, + create a single `KeptnTaskDefinition` that calls each action in order. +* If you have tasks that can execute in parallel, + migrating to Keptn may improve the performance of the deployment. + +### SLIs + +Keptn v1 +[SLIs](https://keptn.sh/docs/1.0.x/reference/files/sli/) +(Service Level Indicators) +represent queries from the data provider +such as Prometheus, Dynatrace, or Datadog, +which is configured as a Keptn integration. + +When migrating to Keptn, you need to define a +[KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) +resource for the data provider(s) you are using. +Note that Keptn allows you to support multiple data providers +and multiple instances of each data provider for your SLIs +whereas Keptn v1 only allows you to use one SLI per project. + +The queries defined for the Keptn v1 SLIs +should be translated into an appropriate Keptn resource: + +* [KeptnMetric](../reference/crd-reference/metric.md) +resources + to do + [evaluations](../guides/evaluations.md) + with + [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) + resources. +* [AnalysisValueTemplate](../reference/crd-reference/analysisvaluetemplate.md) + resources to do + [analyses](../guides/slo.md) + with + [AnalysisDefinition](../reference/crd-reference/analysisdefinition.md) + resources. + Tools are provided to convert Keptn v1 SLIs and SLOs + to Keptn resources; see + [Convert Keptn v1 SLIs/SLOs to Analysis resources](./metrics-observe.md#convert-keptn-v1-slisslos-to-analysis-resources) + for more information. + +### SLOs + +Keptn v1 +[SLOs](https://keptn.sh/docs/1.0.x/reference/files/slo/). +can be implemented on Keptn as evaluations or analyses: + +* Simple evaluations of an SLI can be implemented as + [Evaluations](../guides/evaluations.md) + which are defined as + [KeptnEvaluationDefinition](../reference/crd-reference/evaluationdefinition.md) + resources. + +* Complex analyses that use weighting and scoring + and analyze the value over a specified time frame + can be implemented as + [Analyses](../guides/slo.md) + that are defined in + [AnalysisDefinition](../reference/crd-reference/analysisdefinition.md) + resources. + Tools are provided to convert Keptn v1 SLIs and SLOs + to Keptn resources; see + [Convert Keptn v1 SLIs/SLOs to Analysis resources](./metrics-observe.md#convert-keptn-v1-slisslos-to-analysis-resources) + for more information. + +### Remediation + +Keptn does not currently support the same level of +[remediations](https://keptn.sh/docs/1.0.x/reference/files/remediation/) +as Keptn v1 does, +but it does provide limited "Day 2" facilities: + +* Any query that is possible for your data provider post-deployment + can be defined as a `KeptnMetricDefinition`; + this is then reported as a Keptn Metric. + Evaluation can be defined as a `KeptnEvaluationDefinition`. +* `KeptnMetricsDefinition` resources can be retrieved and used + to implement the Kubernetes HorizontalPodAutoscaler (HPA), + which can detect the need for additional resources + (more pods, memory, disk space, etc.) + and automatically add those resources to your configuration + based on the `ReplicaSet` resources you have defined. + See + [Using the HorizontalPodAutoscaler](../use-cases/hpa.md) + for more information. + +### Integrations and services in JES + +Most functionality coded using the Keptn v1 +[JES](https://github.com/keptn-contrib/job-executor-service) +(Job Executor Service) facility +can simply be moved into a `KeptnTaskDefinition` resource +that uses the +[container-runtime runner](../reference/crd-reference/taskdefinition.md/#synopsis-for-container-runtime). +If the JES container code is written in JavaScript or TypeScript, +you may be able to use the `deno-runtime` runner. +If the JES container code is written in Python 3, +you may be able to use the `python-runtime` runner. + +Note that there is no need for integrations for data providers in Keptn; +these are configured as `KeptnMetricsProvider` resources. diff --git a/docs-new/docs/reference/api-reference/index.md b/docs-new/docs/reference/api-reference/index.md new file mode 100644 index 0000000000..cfec845cf3 --- /dev/null +++ b/docs-new/docs/reference/api-reference/index.md @@ -0,0 +1,47 @@ +# API Reference + +This section provides comprehensive reference information about all APIs +that are defined In Keptn. +This section is auto-generated from source code. + +Each CRD is an object of an API library. +Keptn APIs follow the Kubernetes API versioning scheme. +and are themselves composed of objects and sub-objects. +The Keptn CRDs extend the base Kubernetes API +with new objects and functionality. +Keptn APIs follow API versioning conventions recommended by Kubernetes. + +Keptn generates most of the resources it needs +without requiring manual input. +[Lifecycle CRD Reference and Metrics CRD Reference](../crd-reference/index.md) +contains reference pages for the manifests +that must be populated manually. + +Use `kubectl` to inspect the current contents of any Keptn resource: + +1. List all resources of the specified type within a certain namespace. + For example, to list all the `KeptnApp` resources + in the `namespace1` namespace, the command is: + + ```shell + kubectl get keptnapps -n namespace1 + ``` + +2. Get the current manifest for the specified resource. + For example, to view the manifest for the `my-keptn-app` resource + in the `namespace1` namespace, the command is: + + ```shell + kubectl get keptnapp -n my-keptn-app -oyaml + ``` + +For more information about the APIs and Custom Resources, +see the Kubernetes documentation: + +* [API Overview](https://kubernetes.io/docs/reference/using-api/) + +* [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) + +* [API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning) + +* [Understanding Kubernetes Objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/) diff --git a/docs-new/docs/reference/api-reference/lifecycle/index.md b/docs-new/docs/reference/api-reference/lifecycle/index.md new file mode 100644 index 0000000000..3b4c4653d3 --- /dev/null +++ b/docs-new/docs/reference/api-reference/lifecycle/index.md @@ -0,0 +1 @@ +# Lifecycle API diff --git a/docs-new/docs/reference/api-reference/lifecycle/v1alpha1/index.md b/docs-new/docs/reference/api-reference/lifecycle/v1alpha1/index.md new file mode 100644 index 0000000000..ac0e42d3a9 --- /dev/null +++ b/docs-new/docs/reference/api-reference/lifecycle/v1alpha1/index.md @@ -0,0 +1,857 @@ +# v1alpha1 + + +## Packages +- [lifecycle.keptn.sh/v1alpha1](#lifecyclekeptnshv1alpha1) + + +## lifecycle.keptn.sh/v1alpha1 + +Package v1alpha1 contains API Schema definitions for the lifecycle v1alpha1 API group + +### Resource Types +- [KeptnApp](#keptnapp) +- [KeptnAppList](#keptnapplist) +- [KeptnAppVersion](#keptnappversion) +- [KeptnAppVersionList](#keptnappversionlist) +- [KeptnEvaluation](#keptnevaluation) +- [KeptnEvaluationDefinition](#keptnevaluationdefinition) +- [KeptnEvaluationDefinitionList](#keptnevaluationdefinitionlist) +- [KeptnEvaluationList](#keptnevaluationlist) +- [KeptnTask](#keptntask) +- [KeptnTaskDefinition](#keptntaskdefinition) +- [KeptnTaskDefinitionList](#keptntaskdefinitionlist) +- [KeptnTaskList](#keptntasklist) +- [KeptnWorkload](#keptnworkload) +- [KeptnWorkloadInstance](#keptnworkloadinstance) +- [KeptnWorkloadInstanceList](#keptnworkloadinstancelist) +- [KeptnWorkloadList](#keptnworkloadlist) + + + + +#### ConfigMapReference + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | || ✓ | + + + + +#### EvaluationStatus + + + + + +_Appears in:_ +- [KeptnAppVersionStatus](#keptnappversionstatus) +- [KeptnWorkloadInstanceStatus](#keptnworkloadinstancestatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `evaluationDefinitionName` _string_ | || ✓ | +| `status` _string_ | |Pending| ✓ | +| `evaluationName` _string_ | || ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | + + +#### EvaluationStatusItem + + + + + +_Appears in:_ +- [KeptnEvaluationStatus](#keptnevaluationstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `value` _string_ | || x | +| `status` _string_ | || x | +| `message` _string_ | || ✓ | + + +#### FunctionReference + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | || ✓ | + + +#### FunctionSpec + + + + + +_Appears in:_ +- [KeptnTaskDefinitionSpec](#keptntaskdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `functionRef` _[FunctionReference](#functionreference)_ | || ✓ | +| `inline` _[Inline](#inline)_ | || ✓ | +| `httpRef` _[HttpReference](#httpreference)_ | || ✓ | +| `configMapRef` _[ConfigMapReference](#configmapreference)_ | || ✓ | +| `parameters` _[TaskParameters](#taskparameters)_ | || ✓ | +| `secureParameters` _[SecureParameters](#secureparameters)_ | || ✓ | + + +#### FunctionStatus + + + + + +_Appears in:_ +- [KeptnTaskDefinitionStatus](#keptntaskdefinitionstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `configMap` _string_ | || ✓ | + + +#### HttpReference + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `url` _string_ | || ✓ | + + +#### Inline + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `code` _string_ | || ✓ | + + +#### KeptnApp + + + +KeptnApp is the Schema for the keptnapps API + +_Appears in:_ +- [KeptnAppList](#keptnapplist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnApp` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnAppSpec](#keptnappspec)_ | || ✓ | +| `status` _[KeptnAppStatus](#keptnappstatus)_ | || ✓ | + + +#### KeptnAppList + + + +KeptnAppList contains a list of KeptnApp + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnAppList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnApp](#keptnapp) array_ | || x | + + +#### KeptnAppSpec + + + +KeptnAppSpec defines the desired state of KeptnApp + +_Appears in:_ +- [KeptnApp](#keptnapp) +- [KeptnAppVersionSpec](#keptnappversionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `version` _string_ | || x | +| `workloads` _[KeptnWorkloadRef](#keptnworkloadref) array_ | || ✓ | +| `preDeploymentTasks` _string array_ | || ✓ | +| `postDeploymentTasks` _string array_ | || ✓ | +| `preDeploymentEvaluations` _string array_ | || ✓ | +| `postDeploymentEvaluations` _string array_ | || ✓ | + + +#### KeptnAppStatus + + + +KeptnAppStatus defines the observed state of KeptnApp + +_Appears in:_ +- [KeptnApp](#keptnapp) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `currentVersion` _string_ | || ✓ | + + +#### KeptnAppVersion + + + +KeptnAppVersion is the Schema for the keptnappversions API + +_Appears in:_ +- [KeptnAppVersionList](#keptnappversionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnAppVersion` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnAppVersionSpec](#keptnappversionspec)_ | || ✓ | +| `status` _[KeptnAppVersionStatus](#keptnappversionstatus)_ | || ✓ | + + +#### KeptnAppVersionList + + + +KeptnAppVersionList contains a list of KeptnAppVersion + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnAppVersionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnAppVersion](#keptnappversion) array_ | || x | + + +#### KeptnAppVersionSpec + + + +KeptnAppVersionSpec defines the desired state of KeptnAppVersion + +_Appears in:_ +- [KeptnAppVersion](#keptnappversion) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `version` _string_ | || x | +| `workloads` _[KeptnWorkloadRef](#keptnworkloadref) array_ | || ✓ | +| `preDeploymentTasks` _string array_ | || ✓ | +| `postDeploymentTasks` _string array_ | || ✓ | +| `preDeploymentEvaluations` _string array_ | || ✓ | +| `postDeploymentEvaluations` _string array_ | || ✓ | +| `appName` _string_ | || x | +| `previousVersion` _string_ | || ✓ | +| `traceId` _object (keys:string, values:string)_ | || ✓ | + + +#### KeptnAppVersionStatus + + + +KeptnAppVersionStatus defines the observed state of KeptnAppVersion + +_Appears in:_ +- [KeptnAppVersion](#keptnappversion) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `preDeploymentStatus` _string_ | |Pending| ✓ | +| `postDeploymentStatus` _string_ | |Pending| ✓ | +| `preDeploymentEvaluationStatus` _string_ | |Pending| ✓ | +| `postDeploymentEvaluationStatus` _string_ | |Pending| ✓ | +| `workloadOverallStatus` _string_ | |Pending| ✓ | +| `workloadStatus` _[WorkloadStatus](#workloadstatus) array_ | || ✓ | +| `currentPhase` _string_ | || ✓ | +| `preDeploymentTaskStatus` _[TaskStatus](#taskstatus) array_ | || ✓ | +| `postDeploymentTaskStatus` _[TaskStatus](#taskstatus) array_ | || ✓ | +| `preDeploymentEvaluationTaskStatus` _[EvaluationStatus](#evaluationstatus) array_ | || ✓ | +| `postDeploymentEvaluationTaskStatus` _[EvaluationStatus](#evaluationstatus) array_ | || ✓ | +| `phaseTraceIDs` _[MapCarrier](https://pkg.go.dev/go.opentelemetry.io/otel/propagation#MapCarrier)_ | || ✓ | +| `status` _string_ | |Pending| ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | + + +#### KeptnEvaluation + + + +KeptnEvaluation is the Schema for the keptnevaluations API + +_Appears in:_ +- [KeptnEvaluationList](#keptnevaluationlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnEvaluation` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnEvaluationSpec](#keptnevaluationspec)_ | || ✓ | +| `status` _[KeptnEvaluationStatus](#keptnevaluationstatus)_ | || ✓ | + + +#### KeptnEvaluationDefinition + + + +KeptnEvaluationDefinition is the Schema for the keptnevaluationdefinitions API + +_Appears in:_ +- [KeptnEvaluationDefinitionList](#keptnevaluationdefinitionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnEvaluationDefinition` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnEvaluationDefinitionSpec](#keptnevaluationdefinitionspec)_ | || ✓ | +| `status` _string_ | unused field || ✓ | + + +#### KeptnEvaluationDefinitionList + + + +KeptnEvaluationDefinitionList contains a list of KeptnEvaluationDefinition + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnEvaluationDefinitionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnEvaluationDefinition](#keptnevaluationdefinition) array_ | || x | + + +#### KeptnEvaluationDefinitionSpec + + + +KeptnEvaluationDefinitionSpec defines the desired state of KeptnEvaluationDefinition + +_Appears in:_ +- [KeptnEvaluationDefinition](#keptnevaluationdefinition) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `source` _string_ | || x | +| `objectives` _[Objective](#objective) array_ | || x | + + +#### KeptnEvaluationList + + + +KeptnEvaluationList contains a list of KeptnEvaluation + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnEvaluationList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnEvaluation](#keptnevaluation) array_ | || x | + + + + +#### KeptnEvaluationSpec + + + +KeptnEvaluationSpec defines the desired state of KeptnEvaluation + +_Appears in:_ +- [KeptnEvaluation](#keptnevaluation) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `workload` _string_ | || ✓ | +| `workloadVersion` _string_ | || x | +| `appName` _string_ | || ✓ | +| `appVersion` _string_ | || ✓ | +| `evaluationDefinition` _string_ | || x | +| `retries` _integer_ | |10| ✓ | +| `retryInterval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | |5s| ✓ | +| `failAction` _string_ | || ✓ | +| `checkType` _string_ | || ✓ | + + +#### KeptnEvaluationStatus + + + +KeptnEvaluationStatus defines the observed state of KeptnEvaluation + +_Appears in:_ +- [KeptnEvaluation](#keptnevaluation) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `retryCount` _integer_ | |0| x | +| `evaluationStatus` _object (keys:string, values:[EvaluationStatusItem](#evaluationstatusitem))_ | || x | +| `overallStatus` _string_ | |Pending| x | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | + + +#### KeptnTask + + + +KeptnTask is the Schema for the keptntasks API + +_Appears in:_ +- [KeptnTaskList](#keptntasklist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnTask` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnTaskSpec](#keptntaskspec)_ | || ✓ | +| `status` _[KeptnTaskStatus](#keptntaskstatus)_ | || ✓ | + + +#### KeptnTaskDefinition + + + +KeptnTaskDefinition is the Schema for the keptntaskdefinitions API + +_Appears in:_ +- [KeptnTaskDefinitionList](#keptntaskdefinitionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnTaskDefinition` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnTaskDefinitionSpec](#keptntaskdefinitionspec)_ | || ✓ | +| `status` _[KeptnTaskDefinitionStatus](#keptntaskdefinitionstatus)_ | || ✓ | + + +#### KeptnTaskDefinitionList + + + +KeptnTaskDefinitionList contains a list of KeptnTaskDefinition + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnTaskDefinitionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnTaskDefinition](#keptntaskdefinition) array_ | || x | + + +#### KeptnTaskDefinitionSpec + + + +KeptnTaskDefinitionSpec defines the desired state of KeptnTaskDefinition + +_Appears in:_ +- [KeptnTaskDefinition](#keptntaskdefinition) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `function` _[FunctionSpec](#functionspec)_ | || ✓ | + + +#### KeptnTaskDefinitionStatus + + + +KeptnTaskDefinitionStatus defines the observed state of KeptnTaskDefinition + +_Appears in:_ +- [KeptnTaskDefinition](#keptntaskdefinition) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `function` _[FunctionStatus](#functionstatus)_ | || ✓ | + + +#### KeptnTaskList + + + +KeptnTaskList contains a list of KeptnTask + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnTaskList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnTask](#keptntask) array_ | || x | + + +#### KeptnTaskSpec + + + +KeptnTaskSpec defines the desired state of KeptnTask + +_Appears in:_ +- [KeptnTask](#keptntask) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `workload` _string_ | || x | +| `workloadVersion` _string_ | || x | +| `app` _string_ | || x | +| `appVersion` _string_ | || x | +| `taskDefinition` _string_ | || x | +| `context` _[TaskContext](#taskcontext)_ | || x | +| `parameters` _[TaskParameters](#taskparameters)_ | || ✓ | +| `secureParameters` _[SecureParameters](#secureparameters)_ | || ✓ | +| `checkType` _string_ | || ✓ | + + +#### KeptnTaskStatus + + + +KeptnTaskStatus defines the observed state of KeptnTask + +_Appears in:_ +- [KeptnTask](#keptntask) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `jobName` _string_ | || ✓ | +| `status` _string_ | |Pending| ✓ | +| `message` _string_ | || ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | + + +#### KeptnWorkload + + + +KeptnWorkload is the Schema for the keptnworkloads API + +_Appears in:_ +- [KeptnWorkloadList](#keptnworkloadlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnWorkload` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnWorkloadSpec](#keptnworkloadspec)_ | || ✓ | +| `status` _[KeptnWorkloadStatus](#keptnworkloadstatus)_ | || ✓ | + + +#### KeptnWorkloadInstance + + + +KeptnWorkloadInstance is the Schema for the keptnworkloadinstances API + +_Appears in:_ +- [KeptnWorkloadInstanceList](#keptnworkloadinstancelist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnWorkloadInstance` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnWorkloadInstanceSpec](#keptnworkloadinstancespec)_ | || ✓ | +| `status` _[KeptnWorkloadInstanceStatus](#keptnworkloadinstancestatus)_ | || ✓ | + + +#### KeptnWorkloadInstanceList + + + +KeptnWorkloadInstanceList contains a list of KeptnWorkloadInstance + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnWorkloadInstanceList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnWorkloadInstance](#keptnworkloadinstance) array_ | || x | + + +#### KeptnWorkloadInstanceSpec + + + +KeptnWorkloadInstanceSpec defines the desired state of KeptnWorkloadInstance + +_Appears in:_ +- [KeptnWorkloadInstance](#keptnworkloadinstance) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `app` _string_ | || x | +| `version` _string_ | || x | +| `preDeploymentTasks` _string array_ | || ✓ | +| `postDeploymentTasks` _string array_ | || ✓ | +| `preDeploymentEvaluations` _string array_ | || ✓ | +| `postDeploymentEvaluations` _string array_ | || ✓ | +| `resourceReference` _[ResourceReference](#resourcereference)_ | || x | +| `workloadName` _string_ | || x | +| `previousVersion` _string_ | || ✓ | +| `traceId` _object (keys:string, values:string)_ | || ✓ | + + +#### KeptnWorkloadInstanceStatus + + + +KeptnWorkloadInstanceStatus defines the observed state of KeptnWorkloadInstance + +_Appears in:_ +- [KeptnWorkloadInstance](#keptnworkloadinstance) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `preDeploymentStatus` _string_ | |Pending| ✓ | +| `deploymentStatus` _string_ | |Pending| ✓ | +| `preDeploymentEvaluationStatus` _string_ | |Pending| ✓ | +| `postDeploymentEvaluationStatus` _string_ | |Pending| ✓ | +| `postDeploymentStatus` _string_ | |Pending| ✓ | +| `preDeploymentTaskStatus` _[TaskStatus](#taskstatus) array_ | || ✓ | +| `postDeploymentTaskStatus` _[TaskStatus](#taskstatus) array_ | || ✓ | +| `preDeploymentEvaluationTaskStatus` _[EvaluationStatus](#evaluationstatus) array_ | || ✓ | +| `postDeploymentEvaluationTaskStatus` _[EvaluationStatus](#evaluationstatus) array_ | || ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `currentPhase` _string_ | || ✓ | +| `phaseTraceIDs` _[MapCarrier](https://pkg.go.dev/go.opentelemetry.io/otel/propagation#MapCarrier)_ | || ✓ | +| `status` _string_ | |Pending| ✓ | + + +#### KeptnWorkloadList + + + +KeptnWorkloadList contains a list of KeptnWorkload + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnWorkloadList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnWorkload](#keptnworkload) array_ | || x | + + +#### KeptnWorkloadRef + + + + + +_Appears in:_ +- [KeptnAppSpec](#keptnappspec) +- [KeptnAppVersionSpec](#keptnappversionspec) +- [WorkloadStatus](#workloadstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | || x | +| `version` _string_ | || x | + + +#### KeptnWorkloadSpec + + + +KeptnWorkloadSpec defines the desired state of KeptnWorkload + +_Appears in:_ +- [KeptnWorkload](#keptnworkload) +- [KeptnWorkloadInstanceSpec](#keptnworkloadinstancespec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `app` _string_ | || x | +| `version` _string_ | || x | +| `preDeploymentTasks` _string array_ | || ✓ | +| `postDeploymentTasks` _string array_ | || ✓ | +| `preDeploymentEvaluations` _string array_ | || ✓ | +| `postDeploymentEvaluations` _string array_ | || ✓ | +| `resourceReference` _[ResourceReference](#resourcereference)_ | || x | + + +#### KeptnWorkloadStatus + + + +KeptnWorkloadStatus defines the observed state of KeptnWorkload + +_Appears in:_ +- [KeptnWorkload](#keptnworkload) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `currentVersion` _string_ | || ✓ | + + +#### Objective + + + + + +_Appears in:_ +- [KeptnEvaluationDefinitionSpec](#keptnevaluationdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | || x | +| `query` _string_ | || x | +| `evaluationTarget` _string_ | || x | + + +#### ResourceReference + + + + + +_Appears in:_ +- [KeptnWorkloadInstanceSpec](#keptnworkloadinstancespec) +- [KeptnWorkloadSpec](#keptnworkloadspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `uid` _string_ | || x | +| `kind` _string_ | || x | +| `name` _string_ | || x | + + +#### SecureParameters + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) +- [KeptnTaskSpec](#keptntaskspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `secret` _string_ | || ✓ | + + +#### TaskContext + + + + + +_Appears in:_ +- [KeptnTaskSpec](#keptntaskspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `workloadName` _string_ | || x | +| `appName` _string_ | || x | +| `appVersion` _string_ | || x | +| `workloadVersion` _string_ | || x | +| `taskType` _string_ | || x | +| `objectType` _string_ | || x | + + +#### TaskParameters + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) +- [KeptnTaskSpec](#keptntaskspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `map` _object (keys:string, values:string)_ | || ✓ | + + +#### TaskStatus + + + + + +_Appears in:_ +- [KeptnAppVersionStatus](#keptnappversionstatus) +- [KeptnWorkloadInstanceStatus](#keptnworkloadinstancestatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `taskDefinitionName` _string_ | || ✓ | +| `status` _string_ | |Pending| ✓ | +| `taskName` _string_ | || ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | + + +#### WorkloadStatus + + + + + +_Appears in:_ +- [KeptnAppVersionStatus](#keptnappversionstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `workload` _[KeptnWorkloadRef](#keptnworkloadref)_ | || ✓ | +| `status` _string_ | |Pending| ✓ | + + diff --git a/docs-new/docs/reference/api-reference/lifecycle/v1alpha2/index.md b/docs-new/docs/reference/api-reference/lifecycle/v1alpha2/index.md new file mode 100644 index 0000000000..0e4fbb2343 --- /dev/null +++ b/docs-new/docs/reference/api-reference/lifecycle/v1alpha2/index.md @@ -0,0 +1,839 @@ +# v1alpha2 + + +## Packages +- [lifecycle.keptn.sh/v1alpha2](#lifecyclekeptnshv1alpha2) + + +## lifecycle.keptn.sh/v1alpha2 + +Package v1alpha2 contains API Schema definitions for the lifecycle v1alpha2 API group + +### Resource Types +- [KeptnApp](#keptnapp) +- [KeptnAppList](#keptnapplist) +- [KeptnAppVersion](#keptnappversion) +- [KeptnAppVersionList](#keptnappversionlist) +- [KeptnEvaluation](#keptnevaluation) +- [KeptnEvaluationDefinition](#keptnevaluationdefinition) +- [KeptnEvaluationDefinitionList](#keptnevaluationdefinitionlist) +- [KeptnEvaluationList](#keptnevaluationlist) +- [KeptnTask](#keptntask) +- [KeptnTaskDefinition](#keptntaskdefinition) +- [KeptnTaskDefinitionList](#keptntaskdefinitionlist) +- [KeptnTaskList](#keptntasklist) +- [KeptnWorkload](#keptnworkload) +- [KeptnWorkloadInstance](#keptnworkloadinstance) +- [KeptnWorkloadInstanceList](#keptnworkloadinstancelist) +- [KeptnWorkloadList](#keptnworkloadlist) + + + +#### ConfigMapReference + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | || ✓ | + + + + +#### EvaluationStatusItem + + + + + +_Appears in:_ +- [KeptnEvaluationStatus](#keptnevaluationstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `value` _string_ | || x | +| `status` _string_ | || x | +| `message` _string_ | || ✓ | + + +#### FunctionReference + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | || ✓ | + + +#### FunctionSpec + + + + + +_Appears in:_ +- [KeptnTaskDefinitionSpec](#keptntaskdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `functionRef` _[FunctionReference](#functionreference)_ | || ✓ | +| `inline` _[Inline](#inline)_ | || ✓ | +| `httpRef` _[HttpReference](#httpreference)_ | || ✓ | +| `configMapRef` _[ConfigMapReference](#configmapreference)_ | || ✓ | +| `parameters` _[TaskParameters](#taskparameters)_ | || ✓ | +| `secureParameters` _[SecureParameters](#secureparameters)_ | || ✓ | + + +#### FunctionStatus + + + + + +_Appears in:_ +- [KeptnTaskDefinitionStatus](#keptntaskdefinitionstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `configMap` _string_ | || ✓ | + + +#### HttpReference + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `url` _string_ | || ✓ | + + +#### Inline + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `code` _string_ | || ✓ | + + +#### ItemStatus + + + + + +_Appears in:_ +- [KeptnAppVersionStatus](#keptnappversionstatus) +- [KeptnWorkloadInstanceStatus](#keptnworkloadinstancestatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `definitionName` _string_ | DefinitionName is the name of the EvaluationDefinition/TaskDefinition || ✓ | +| `status` _string_ | |Pending| ✓ | +| `name` _string_ | Name is the name of the Evaluation/Task || ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | + + +#### KeptnApp + + + +KeptnApp is the Schema for the keptnapps API + +_Appears in:_ +- [KeptnAppList](#keptnapplist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnApp` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnAppSpec](#keptnappspec)_ | || ✓ | +| `status` _[KeptnAppStatus](#keptnappstatus)_ | || ✓ | + + +#### KeptnAppList + + + +KeptnAppList contains a list of KeptnApp + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnAppList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnApp](#keptnapp) array_ | || x | + + +#### KeptnAppSpec + + + +KeptnAppSpec defines the desired state of KeptnApp + +_Appears in:_ +- [KeptnApp](#keptnapp) +- [KeptnAppVersionSpec](#keptnappversionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `version` _string_ | || x | +| `revision` _integer_ | |1| ✓ | +| `workloads` _[KeptnWorkloadRef](#keptnworkloadref) array_ | || ✓ | +| `preDeploymentTasks` _string array_ | || ✓ | +| `postDeploymentTasks` _string array_ | || ✓ | +| `preDeploymentEvaluations` _string array_ | || ✓ | +| `postDeploymentEvaluations` _string array_ | || ✓ | + + +#### KeptnAppStatus + + + +KeptnAppStatus defines the observed state of KeptnApp + +_Appears in:_ +- [KeptnApp](#keptnapp) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `currentVersion` _string_ | || ✓ | + + +#### KeptnAppVersion + + + +KeptnAppVersion is the Schema for the keptnappversions API + +_Appears in:_ +- [KeptnAppVersionList](#keptnappversionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnAppVersion` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnAppVersionSpec](#keptnappversionspec)_ | || ✓ | +| `status` _[KeptnAppVersionStatus](#keptnappversionstatus)_ | || ✓ | + + +#### KeptnAppVersionList + + + +KeptnAppVersionList contains a list of KeptnAppVersion + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnAppVersionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnAppVersion](#keptnappversion) array_ | || x | + + +#### KeptnAppVersionSpec + + + +KeptnAppVersionSpec defines the desired state of KeptnAppVersion + +_Appears in:_ +- [KeptnAppVersion](#keptnappversion) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `version` _string_ | || x | +| `revision` _integer_ | |1| ✓ | +| `workloads` _[KeptnWorkloadRef](#keptnworkloadref) array_ | || ✓ | +| `preDeploymentTasks` _string array_ | || ✓ | +| `postDeploymentTasks` _string array_ | || ✓ | +| `preDeploymentEvaluations` _string array_ | || ✓ | +| `postDeploymentEvaluations` _string array_ | || ✓ | +| `appName` _string_ | || x | +| `previousVersion` _string_ | || ✓ | +| `traceId` _object (keys:string, values:string)_ | || ✓ | + + +#### KeptnAppVersionStatus + + + +KeptnAppVersionStatus defines the observed state of KeptnAppVersion + +_Appears in:_ +- [KeptnAppVersion](#keptnappversion) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `preDeploymentStatus` _string_ | |Pending| ✓ | +| `postDeploymentStatus` _string_ | |Pending| ✓ | +| `preDeploymentEvaluationStatus` _string_ | |Pending| ✓ | +| `postDeploymentEvaluationStatus` _string_ | |Pending| ✓ | +| `workloadOverallStatus` _string_ | |Pending| ✓ | +| `workloadStatus` _[WorkloadStatus](#workloadstatus) array_ | || ✓ | +| `currentPhase` _string_ | || ✓ | +| `preDeploymentTaskStatus` _[ItemStatus](#itemstatus) array_ | || ✓ | +| `postDeploymentTaskStatus` _[ItemStatus](#itemstatus) array_ | || ✓ | +| `preDeploymentEvaluationTaskStatus` _[ItemStatus](#itemstatus) array_ | || ✓ | +| `postDeploymentEvaluationTaskStatus` _[ItemStatus](#itemstatus) array_ | || ✓ | +| `phaseTraceIDs` _[MapCarrier](https://pkg.go.dev/go.opentelemetry.io/otel/propagation#MapCarrier)_ | || ✓ | +| `status` _string_ | |Pending| ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | + + +#### KeptnEvaluation + + + +KeptnEvaluation is the Schema for the keptnevaluations API + +_Appears in:_ +- [KeptnEvaluationList](#keptnevaluationlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnEvaluation` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnEvaluationSpec](#keptnevaluationspec)_ | || ✓ | +| `status` _[KeptnEvaluationStatus](#keptnevaluationstatus)_ | || ✓ | + + +#### KeptnEvaluationDefinition + + + +KeptnEvaluationDefinition is the Schema for the keptnevaluationdefinitions API + +_Appears in:_ +- [KeptnEvaluationDefinitionList](#keptnevaluationdefinitionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnEvaluationDefinition` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnEvaluationDefinitionSpec](#keptnevaluationdefinitionspec)_ | || ✓ | +| `status` _string_ | unused field || ✓ | + + +#### KeptnEvaluationDefinitionList + + + +KeptnEvaluationDefinitionList contains a list of KeptnEvaluationDefinition + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnEvaluationDefinitionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnEvaluationDefinition](#keptnevaluationdefinition) array_ | || x | + + +#### KeptnEvaluationDefinitionSpec + + + +KeptnEvaluationDefinitionSpec defines the desired state of KeptnEvaluationDefinition + +_Appears in:_ +- [KeptnEvaluationDefinition](#keptnevaluationdefinition) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `source` _string_ | || x | +| `objectives` _[Objective](#objective) array_ | || x | + + +#### KeptnEvaluationList + + + +KeptnEvaluationList contains a list of KeptnEvaluation + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnEvaluationList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnEvaluation](#keptnevaluation) array_ | || x | + + + + +#### KeptnEvaluationSpec + + + +KeptnEvaluationSpec defines the desired state of KeptnEvaluation + +_Appears in:_ +- [KeptnEvaluation](#keptnevaluation) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `workload` _string_ | || ✓ | +| `workloadVersion` _string_ | || x | +| `appName` _string_ | || ✓ | +| `appVersion` _string_ | || ✓ | +| `evaluationDefinition` _string_ | || x | +| `retries` _integer_ | |10| ✓ | +| `retryInterval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | |5s| ✓ | +| `failAction` _string_ | || ✓ | +| `checkType` _string_ | || ✓ | + + +#### KeptnEvaluationStatus + + + +KeptnEvaluationStatus defines the observed state of KeptnEvaluation + +_Appears in:_ +- [KeptnEvaluation](#keptnevaluation) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `retryCount` _integer_ | |0| x | +| `evaluationStatus` _object (keys:string, values:[EvaluationStatusItem](#evaluationstatusitem))_ | || x | +| `overallStatus` _string_ | |Pending| x | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | + + +#### KeptnTask + + + +KeptnTask is the Schema for the keptntasks API + +_Appears in:_ +- [KeptnTaskList](#keptntasklist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnTask` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnTaskSpec](#keptntaskspec)_ | || ✓ | +| `status` _[KeptnTaskStatus](#keptntaskstatus)_ | || ✓ | + + +#### KeptnTaskDefinition + + + +KeptnTaskDefinition is the Schema for the keptntaskdefinitions API + +_Appears in:_ +- [KeptnTaskDefinitionList](#keptntaskdefinitionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnTaskDefinition` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnTaskDefinitionSpec](#keptntaskdefinitionspec)_ | || ✓ | +| `status` _[KeptnTaskDefinitionStatus](#keptntaskdefinitionstatus)_ | || ✓ | + + +#### KeptnTaskDefinitionList + + + +KeptnTaskDefinitionList contains a list of KeptnTaskDefinition + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnTaskDefinitionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnTaskDefinition](#keptntaskdefinition) array_ | || x | + + +#### KeptnTaskDefinitionSpec + + + +KeptnTaskDefinitionSpec defines the desired state of KeptnTaskDefinition + +_Appears in:_ +- [KeptnTaskDefinition](#keptntaskdefinition) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `function` _[FunctionSpec](#functionspec)_ | || ✓ | + + +#### KeptnTaskDefinitionStatus + + + +KeptnTaskDefinitionStatus defines the observed state of KeptnTaskDefinition + +_Appears in:_ +- [KeptnTaskDefinition](#keptntaskdefinition) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `function` _[FunctionStatus](#functionstatus)_ | || ✓ | + + +#### KeptnTaskList + + + +KeptnTaskList contains a list of KeptnTask + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnTaskList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnTask](#keptntask) array_ | || x | + + +#### KeptnTaskSpec + + + +KeptnTaskSpec defines the desired state of KeptnTask + +_Appears in:_ +- [KeptnTask](#keptntask) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `workload` _string_ | || x | +| `workloadVersion` _string_ | || x | +| `app` _string_ | || x | +| `appVersion` _string_ | || x | +| `taskDefinition` _string_ | || x | +| `context` _[TaskContext](#taskcontext)_ | || x | +| `parameters` _[TaskParameters](#taskparameters)_ | || ✓ | +| `secureParameters` _[SecureParameters](#secureparameters)_ | || ✓ | +| `checkType` _string_ | || ✓ | + + +#### KeptnTaskStatus + + + +KeptnTaskStatus defines the observed state of KeptnTask + +_Appears in:_ +- [KeptnTask](#keptntask) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `jobName` _string_ | || ✓ | +| `status` _string_ | |Pending| ✓ | +| `message` _string_ | || ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | + + +#### KeptnWorkload + + + +KeptnWorkload is the Schema for the keptnworkloads API + +_Appears in:_ +- [KeptnWorkloadList](#keptnworkloadlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnWorkload` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnWorkloadSpec](#keptnworkloadspec)_ | || ✓ | +| `status` _[KeptnWorkloadStatus](#keptnworkloadstatus)_ | || ✓ | + + +#### KeptnWorkloadInstance + + + +KeptnWorkloadInstance is the Schema for the keptnworkloadinstances API + +_Appears in:_ +- [KeptnWorkloadInstanceList](#keptnworkloadinstancelist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnWorkloadInstance` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnWorkloadInstanceSpec](#keptnworkloadinstancespec)_ | || ✓ | +| `status` _[KeptnWorkloadInstanceStatus](#keptnworkloadinstancestatus)_ | || ✓ | + + +#### KeptnWorkloadInstanceList + + + +KeptnWorkloadInstanceList contains a list of KeptnWorkloadInstance + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnWorkloadInstanceList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnWorkloadInstance](#keptnworkloadinstance) array_ | || x | + + +#### KeptnWorkloadInstanceSpec + + + +KeptnWorkloadInstanceSpec defines the desired state of KeptnWorkloadInstance + +_Appears in:_ +- [KeptnWorkloadInstance](#keptnworkloadinstance) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `app` _string_ | || x | +| `version` _string_ | || x | +| `preDeploymentTasks` _string array_ | || ✓ | +| `postDeploymentTasks` _string array_ | || ✓ | +| `preDeploymentEvaluations` _string array_ | || ✓ | +| `postDeploymentEvaluations` _string array_ | || ✓ | +| `resourceReference` _[ResourceReference](#resourcereference)_ | || x | +| `workloadName` _string_ | || x | +| `previousVersion` _string_ | || ✓ | +| `traceId` _object (keys:string, values:string)_ | || ✓ | + + +#### KeptnWorkloadInstanceStatus + + + +KeptnWorkloadInstanceStatus defines the observed state of KeptnWorkloadInstance + +_Appears in:_ +- [KeptnWorkloadInstance](#keptnworkloadinstance) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `preDeploymentStatus` _string_ | |Pending| ✓ | +| `deploymentStatus` _string_ | |Pending| ✓ | +| `preDeploymentEvaluationStatus` _string_ | |Pending| ✓ | +| `postDeploymentEvaluationStatus` _string_ | |Pending| ✓ | +| `postDeploymentStatus` _string_ | |Pending| ✓ | +| `preDeploymentTaskStatus` _[ItemStatus](#itemstatus) array_ | || ✓ | +| `postDeploymentTaskStatus` _[ItemStatus](#itemstatus) array_ | || ✓ | +| `preDeploymentEvaluationTaskStatus` _[ItemStatus](#itemstatus) array_ | || ✓ | +| `postDeploymentEvaluationTaskStatus` _[ItemStatus](#itemstatus) array_ | || ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | || ✓ | +| `currentPhase` _string_ | || ✓ | +| `phaseTraceIDs` _[MapCarrier](https://pkg.go.dev/go.opentelemetry.io/otel/propagation#MapCarrier)_ | || ✓ | +| `status` _string_ | |Pending| ✓ | + + +#### KeptnWorkloadList + + + +KeptnWorkloadList contains a list of KeptnWorkload + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnWorkloadList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnWorkload](#keptnworkload) array_ | || x | + + +#### KeptnWorkloadRef + + + + + +_Appears in:_ +- [KeptnAppSpec](#keptnappspec) +- [KeptnAppVersionSpec](#keptnappversionspec) +- [WorkloadStatus](#workloadstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | || x | +| `version` _string_ | || x | + + +#### KeptnWorkloadSpec + + + +KeptnWorkloadSpec defines the desired state of KeptnWorkload + +_Appears in:_ +- [KeptnWorkload](#keptnworkload) +- [KeptnWorkloadInstanceSpec](#keptnworkloadinstancespec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `app` _string_ | || x | +| `version` _string_ | || x | +| `preDeploymentTasks` _string array_ | || ✓ | +| `postDeploymentTasks` _string array_ | || ✓ | +| `preDeploymentEvaluations` _string array_ | || ✓ | +| `postDeploymentEvaluations` _string array_ | || ✓ | +| `resourceReference` _[ResourceReference](#resourcereference)_ | || x | + + +#### KeptnWorkloadStatus + + + +KeptnWorkloadStatus defines the observed state of KeptnWorkload + +_Appears in:_ +- [KeptnWorkload](#keptnworkload) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `currentVersion` _string_ | || ✓ | + + +#### Objective + + + + + +_Appears in:_ +- [KeptnEvaluationDefinitionSpec](#keptnevaluationdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | || x | +| `query` _string_ | || x | +| `evaluationTarget` _string_ | || x | + + +#### ResourceReference + + + + + +_Appears in:_ +- [KeptnWorkloadInstanceSpec](#keptnworkloadinstancespec) +- [KeptnWorkloadSpec](#keptnworkloadspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `uid` _string_ | || x | +| `kind` _string_ | || x | +| `name` _string_ | || x | + + +#### SecureParameters + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) +- [KeptnTaskSpec](#keptntaskspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `secret` _string_ | || ✓ | + + +#### TaskContext + + + + + +_Appears in:_ +- [KeptnTaskSpec](#keptntaskspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `workloadName` _string_ | || x | +| `appName` _string_ | || x | +| `appVersion` _string_ | || x | +| `workloadVersion` _string_ | || x | +| `taskType` _string_ | || x | +| `objectType` _string_ | || x | + + +#### TaskParameters + + + + + +_Appears in:_ +- [FunctionSpec](#functionspec) +- [KeptnTaskSpec](#keptntaskspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `map` _object (keys:string, values:string)_ | || ✓ | + + +#### WorkloadStatus + + + + + +_Appears in:_ +- [KeptnAppVersionStatus](#keptnappversionstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `workload` _[KeptnWorkloadRef](#keptnworkloadref)_ | || ✓ | +| `status` _string_ | |Pending| ✓ | + + diff --git a/docs-new/docs/reference/api-reference/lifecycle/v1alpha3/index.md b/docs-new/docs/reference/api-reference/lifecycle/v1alpha3/index.md new file mode 100644 index 0000000000..a85e4942ac --- /dev/null +++ b/docs-new/docs/reference/api-reference/lifecycle/v1alpha3/index.md @@ -0,0 +1,948 @@ +# v1alpha3 + + +## Packages +- [lifecycle.keptn.sh/v1alpha3](#lifecyclekeptnshv1alpha3) + + +## lifecycle.keptn.sh/v1alpha3 + +Package v1alpha3 contains API Schema definitions for the lifecycle v1alpha3 API group + +### Resource Types +- [KeptnApp](#keptnapp) +- [KeptnAppCreationRequest](#keptnappcreationrequest) +- [KeptnAppCreationRequestList](#keptnappcreationrequestlist) +- [KeptnAppList](#keptnapplist) +- [KeptnAppVersion](#keptnappversion) +- [KeptnAppVersionList](#keptnappversionlist) +- [KeptnEvaluation](#keptnevaluation) +- [KeptnEvaluationDefinition](#keptnevaluationdefinition) +- [KeptnEvaluationDefinitionList](#keptnevaluationdefinitionlist) +- [KeptnEvaluationList](#keptnevaluationlist) +- [KeptnTask](#keptntask) +- [KeptnTaskDefinition](#keptntaskdefinition) +- [KeptnTaskDefinitionList](#keptntaskdefinitionlist) +- [KeptnTaskList](#keptntasklist) +- [KeptnWorkload](#keptnworkload) +- [KeptnWorkloadInstance](#keptnworkloadinstance) +- [KeptnWorkloadInstanceList](#keptnworkloadinstancelist) +- [KeptnWorkloadList](#keptnworkloadlist) + + + +#### AutomountServiceAccountTokenSpec + + + + + +_Appears in:_ +- [KeptnTaskDefinitionSpec](#keptntaskdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `type` _boolean_ | || x | + + +#### ConfigMapReference + + + + + +_Appears in:_ +- [RuntimeSpec](#runtimespec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | Name is the name of the referenced ConfigMap. || ✓ | + + +#### ContainerSpec + + + + + +_Appears in:_ +- [KeptnTaskDefinitionSpec](#keptntaskdefinitionspec) + + + +#### EvaluationStatusItem + + + + + +_Appears in:_ +- [KeptnEvaluationStatus](#keptnevaluationstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `value` _string_ | Value represents the value of the KeptnMetric being evaluated. || x | +| `status` _string_ | Status indicates the status of the objective being evaluated. || x | +| `message` _string_ | Message contains additional information about the evaluation of an objective. This can include explanations about why an evaluation has failed (e.g. due to a missed objective), or if there was any error during the evaluation of the objective. || ✓ | + + +#### FunctionReference + + + + + +_Appears in:_ +- [RuntimeSpec](#runtimespec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | Name is the name of the referenced KeptnTaskDefinition. || ✓ | + + +#### FunctionStatus + + + + + +_Appears in:_ +- [KeptnTaskDefinitionStatus](#keptntaskdefinitionstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `configMap` _string_ | ConfigMap indicates the ConfigMap in which the function code is stored. || ✓ | + + +#### HttpReference + + + + + +_Appears in:_ +- [RuntimeSpec](#runtimespec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `url` _string_ | Url is the URL containing the code of the function. || ✓ | + + +#### Inline + + + + + +_Appears in:_ +- [RuntimeSpec](#runtimespec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `code` _string_ | Code contains the code of the function. || ✓ | + + +#### ItemStatus + + + + + +_Appears in:_ +- [KeptnAppVersionStatus](#keptnappversionstatus) +- [KeptnWorkloadInstanceStatus](#keptnworkloadinstancestatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `definitionName` _string_ | DefinitionName is the name of the EvaluationDefinition/TaskDefinition || ✓ | +| `status` _string_ | |Pending| ✓ | +| `name` _string_ | Name is the name of the Evaluation/Task || ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | StartTime represents the time at which the Item (Evaluation/Task) started. || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | EndTime represents the time at which the Item (Evaluation/Task) started. || ✓ | + + +#### KeptnApp + + + +KeptnApp is the Schema for the keptnapps API + +_Appears in:_ +- [KeptnAppList](#keptnapplist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnApp` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnAppSpec](#keptnappspec)_ | Spec describes the desired state of the KeptnApp. || ✓ | +| `status` _[KeptnAppStatus](#keptnappstatus)_ | Status describes the current state of the KeptnApp. || ✓ | + + +#### KeptnAppCreationRequest + + + +KeptnAppCreationRequest is the Schema for the keptnappcreationrequests API + +_Appears in:_ +- [KeptnAppCreationRequestList](#keptnappcreationrequestlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnAppCreationRequest` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnAppCreationRequestSpec](#keptnappcreationrequestspec)_ | Spec describes the desired state of the KeptnAppCreationRequest. || ✓ | +| `status` _string_ | Status describes the current state of the KeptnAppCreationRequest. || ✓ | + + +#### KeptnAppCreationRequestList + + + +KeptnAppCreationRequestList contains a list of KeptnAppCreationRequest + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnAppCreationRequestList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnAppCreationRequest](#keptnappcreationrequest) array_ | || x | + + +#### KeptnAppCreationRequestSpec + + + +KeptnAppCreationRequestSpec defines the desired state of KeptnAppCreationRequest + +_Appears in:_ +- [KeptnAppCreationRequest](#keptnappcreationrequest) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `appName` _string_ | AppName is the name of the KeptnApp the KeptnAppCreationRequest should create if no user-defined object with that name is found. || x | + + +#### KeptnAppList + + + +KeptnAppList contains a list of KeptnApp + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnAppList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnApp](#keptnapp) array_ | || x | + + +#### KeptnAppSpec + + + +KeptnAppSpec defines the desired state of KeptnApp + +_Appears in:_ +- [KeptnApp](#keptnapp) +- [KeptnAppVersionSpec](#keptnappversionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `version` _string_ | Version defines the version of the application. For automatically created KeptnApps, the version is a function of all KeptnWorkloads that are part of the KeptnApp. || x | +| `revision` _integer_ | Revision can be modified to trigger another deployment of a KeptnApp of the same version. This can be used for restarting a KeptnApp which failed to deploy, e.g. due to a failed preDeploymentEvaluation/preDeploymentTask. |1| ✓ | +| `workloads` _[KeptnWorkloadRef](#keptnworkloadref) array_ | Workloads is a list of all KeptnWorkloads that are part of the KeptnApp. || ✓ | +| `preDeploymentTasks` _string array_ | PreDeploymentTasks is a list of all tasks to be performed during the pre-deployment phase of the KeptnApp. The items of this list refer to the names of KeptnTaskDefinitions located in the same namespace as the KeptnApp, or in the Keptn namespace. || ✓ | +| `postDeploymentTasks` _string array_ | PostDeploymentTasks is a list of all tasks to be performed during the post-deployment phase of the KeptnApp. The items of this list refer to the names of KeptnTaskDefinitions located in the same namespace as the KeptnApp, or in the Keptn namespace. || ✓ | +| `preDeploymentEvaluations` _string array_ | PreDeploymentEvaluations is a list of all evaluations to be performed during the pre-deployment phase of the KeptnApp. The items of this list refer to the names of KeptnEvaluationDefinitions located in the same namespace as the KeptnApp, or in the Keptn namespace. || ✓ | +| `postDeploymentEvaluations` _string array_ | PostDeploymentEvaluations is a list of all evaluations to be performed during the post-deployment phase of the KeptnApp. The items of this list refer to the names of KeptnEvaluationDefinitions located in the same namespace as the KeptnApp, or in the Keptn namespace. || ✓ | + + +#### KeptnAppStatus + + + +KeptnAppStatus defines the observed state of KeptnApp + +_Appears in:_ +- [KeptnApp](#keptnapp) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `currentVersion` _string_ | CurrentVersion indicates the version that is currently deployed or being reconciled. || ✓ | + + +#### KeptnAppVersion + + + +KeptnAppVersion is the Schema for the keptnappversions API + +_Appears in:_ +- [KeptnAppVersionList](#keptnappversionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnAppVersion` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnAppVersionSpec](#keptnappversionspec)_ | Spec describes the desired state of the KeptnAppVersion. || ✓ | +| `status` _[KeptnAppVersionStatus](#keptnappversionstatus)_ | Status describes the current state of the KeptnAppVersion. || ✓ | + + +#### KeptnAppVersionList + + + +KeptnAppVersionList contains a list of KeptnAppVersion + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnAppVersionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnAppVersion](#keptnappversion) array_ | || x | + + +#### KeptnAppVersionSpec + + + +KeptnAppVersionSpec defines the desired state of KeptnAppVersion + +_Appears in:_ +- [KeptnAppVersion](#keptnappversion) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `version` _string_ | Version defines the version of the application. For automatically created KeptnApps, the version is a function of all KeptnWorkloads that are part of the KeptnApp. || x | +| `revision` _integer_ | Revision can be modified to trigger another deployment of a KeptnApp of the same version. This can be used for restarting a KeptnApp which failed to deploy, e.g. due to a failed preDeploymentEvaluation/preDeploymentTask. |1| ✓ | +| `workloads` _[KeptnWorkloadRef](#keptnworkloadref) array_ | Workloads is a list of all KeptnWorkloads that are part of the KeptnApp. || ✓ | +| `preDeploymentTasks` _string array_ | PreDeploymentTasks is a list of all tasks to be performed during the pre-deployment phase of the KeptnApp. The items of this list refer to the names of KeptnTaskDefinitions located in the same namespace as the KeptnApp, or in the Keptn namespace. || ✓ | +| `postDeploymentTasks` _string array_ | PostDeploymentTasks is a list of all tasks to be performed during the post-deployment phase of the KeptnApp. The items of this list refer to the names of KeptnTaskDefinitions located in the same namespace as the KeptnApp, or in the Keptn namespace. || ✓ | +| `preDeploymentEvaluations` _string array_ | PreDeploymentEvaluations is a list of all evaluations to be performed during the pre-deployment phase of the KeptnApp. The items of this list refer to the names of KeptnEvaluationDefinitions located in the same namespace as the KeptnApp, or in the Keptn namespace. || ✓ | +| `postDeploymentEvaluations` _string array_ | PostDeploymentEvaluations is a list of all evaluations to be performed during the post-deployment phase of the KeptnApp. The items of this list refer to the names of KeptnEvaluationDefinitions located in the same namespace as the KeptnApp, or in the Keptn namespace. || ✓ | +| `appName` _string_ | AppName is the name of the KeptnApp. || x | +| `previousVersion` _string_ | PreviousVersion is the version of the KeptnApp that has been deployed prior to this version. || ✓ | +| `traceId` _object (keys:string, values:string)_ | TraceId contains the OpenTelemetry trace ID. || ✓ | + + +#### KeptnAppVersionStatus + + + +KeptnAppVersionStatus defines the observed state of KeptnAppVersion + +_Appears in:_ +- [KeptnAppVersion](#keptnappversion) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `preDeploymentStatus` _string_ | PreDeploymentStatus indicates the current status of the KeptnAppVersion's PreDeployment phase. |Pending| ✓ | +| `postDeploymentStatus` _string_ | PostDeploymentStatus indicates the current status of the KeptnAppVersion's PostDeployment phase. |Pending| ✓ | +| `preDeploymentEvaluationStatus` _string_ | PreDeploymentEvaluationStatus indicates the current status of the KeptnAppVersion's PreDeploymentEvaluation phase. |Pending| ✓ | +| `postDeploymentEvaluationStatus` _string_ | PostDeploymentEvaluationStatus indicates the current status of the KeptnAppVersion's PostDeploymentEvaluation phase. |Pending| ✓ | +| `workloadOverallStatus` _string_ | WorkloadOverallStatus indicates the current status of the KeptnAppVersion's Workload deployment phase. |Pending| ✓ | +| `workloadStatus` _[WorkloadStatus](#workloadstatus) array_ | WorkloadStatus contains the current status of each KeptnWorkload that is part of the KeptnAppVersion. || ✓ | +| `currentPhase` _string_ | CurrentPhase indicates the current phase of the KeptnAppVersion. || ✓ | +| `preDeploymentTaskStatus` _[ItemStatus](#itemstatus) array_ | PreDeploymentTaskStatus indicates the current state of each preDeploymentTask of the KeptnAppVersion. || ✓ | +| `postDeploymentTaskStatus` _[ItemStatus](#itemstatus) array_ | PostDeploymentTaskStatus indicates the current state of each postDeploymentTask of the KeptnAppVersion. || ✓ | +| `preDeploymentEvaluationTaskStatus` _[ItemStatus](#itemstatus) array_ | PreDeploymentEvaluationTaskStatus indicates the current state of each preDeploymentEvaluation of the KeptnAppVersion. || ✓ | +| `postDeploymentEvaluationTaskStatus` _[ItemStatus](#itemstatus) array_ | PostDeploymentEvaluationTaskStatus indicates the current state of each postDeploymentEvaluation of the KeptnAppVersion. || ✓ | +| `phaseTraceIDs` _[MapCarrier](https://pkg.go.dev/go.opentelemetry.io/otel/propagation#MapCarrier)_ | PhaseTraceIDs contains the trace IDs of the OpenTelemetry spans of each phase of the KeptnAppVersion. || ✓ | +| `status` _string_ | Status represents the overall status of the KeptnAppVersion. |Pending| ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | StartTime represents the time at which the deployment of the KeptnAppVersion started. || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | EndTime represents the time at which the deployment of the KeptnAppVersion finished. || ✓ | + + +#### KeptnEvaluation + + + +KeptnEvaluation is the Schema for the keptnevaluations API + +_Appears in:_ +- [KeptnEvaluationList](#keptnevaluationlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnEvaluation` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnEvaluationSpec](#keptnevaluationspec)_ | Spec describes the desired state of the KeptnEvaluation. || ✓ | +| `status` _[KeptnEvaluationStatus](#keptnevaluationstatus)_ | Status describes the current state of the KeptnEvaluation. || ✓ | + + +#### KeptnEvaluationDefinition + + + +KeptnEvaluationDefinition is the Schema for the keptnevaluationdefinitions API + +_Appears in:_ +- [KeptnEvaluationDefinitionList](#keptnevaluationdefinitionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnEvaluationDefinition` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnEvaluationDefinitionSpec](#keptnevaluationdefinitionspec)_ | Spec describes the desired state of the KeptnEvaluationDefinition. || ✓ | +| `status` _string_ | unused field || ✓ | + + +#### KeptnEvaluationDefinitionList + + + +KeptnEvaluationDefinitionList contains a list of KeptnEvaluationDefinition + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnEvaluationDefinitionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnEvaluationDefinition](#keptnevaluationdefinition) array_ | || x | + + +#### KeptnEvaluationDefinitionSpec + + + +KeptnEvaluationDefinitionSpec defines the desired state of KeptnEvaluationDefinition + +_Appears in:_ +- [KeptnEvaluationDefinition](#keptnevaluationdefinition) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `objectives` _[Objective](#objective) array_ | Objectives is a list of objectives that have to be met for a KeptnEvaluation referencing this KeptnEvaluationDefinition to be successful. || x | + + +#### KeptnEvaluationList + + + +KeptnEvaluationList contains a list of KeptnEvaluation + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnEvaluationList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnEvaluation](#keptnevaluation) array_ | || x | + + + + +#### KeptnEvaluationSpec + + + +KeptnEvaluationSpec defines the desired state of KeptnEvaluation + +_Appears in:_ +- [KeptnEvaluation](#keptnevaluation) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `workload` _string_ | Workload defines the KeptnWorkload for which the KeptnEvaluation is done. || ✓ | +| `workloadVersion` _string_ | WorkloadVersion defines the version of the KeptnWorkload for which the KeptnEvaluation is done. || x | +| `appName` _string_ | AppName defines the KeptnApp for which the KeptnEvaluation is done. || ✓ | +| `appVersion` _string_ | AppVersion defines the version of the KeptnApp for which the KeptnEvaluation is done. || ✓ | +| `evaluationDefinition` _string_ | EvaluationDefinition refers to the name of the KeptnEvaluationDefinition which includes the objectives for the KeptnEvaluation. The KeptnEvaluationDefinition can be located in the same namespace as the KeptnEvaluation, or in the Keptn namespace. || x | +| `retries` _integer_ | Retries indicates how many times the KeptnEvaluation can be attempted in the case of an error or missed evaluation objective, before considering the KeptnEvaluation to be failed. |10| ✓ | +| `retryInterval` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | RetryInterval specifies the interval at which the KeptnEvaluation is retried in the case of an error or a missed objective. |5s| ✓ | +| `failAction` _string_ | || ✓ | +| `checkType` _string_ | Type indicates whether the KeptnEvaluation is part of the pre- or postDeployment phase. || ✓ | + + +#### KeptnEvaluationStatus + + + +KeptnEvaluationStatus defines the observed state of KeptnEvaluation + +_Appears in:_ +- [KeptnEvaluation](#keptnevaluation) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `retryCount` _integer_ | RetryCount indicates how many times the KeptnEvaluation has been attempted already. |0| x | +| `evaluationStatus` _object (keys:string, values:[EvaluationStatusItem](#evaluationstatusitem))_ | EvaluationStatus describes the status of each objective of the KeptnEvaluationDefinition referenced by the KeptnEvaluation. || x | +| `overallStatus` _string_ | OverallStatus describes the overall status of the KeptnEvaluation. The Overall status is derived from the status of the individual objectives of the KeptnEvaluationDefinition referenced by the KeptnEvaluation. |Pending| x | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | StartTime represents the time at which the KeptnEvaluation started. || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | EndTime represents the time at which the KeptnEvaluation finished. || ✓ | + + +#### KeptnMetricReference + + + + + +_Appears in:_ +- [Objective](#objective) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | Name is the name of the referenced KeptnMetric. || x | +| `namespace` _string_ | Namespace is the namespace where the referenced KeptnMetric is located. || ✓ | + + +#### KeptnTask + + + +KeptnTask is the Schema for the keptntasks API + +_Appears in:_ +- [KeptnTaskList](#keptntasklist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnTask` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnTaskSpec](#keptntaskspec)_ | Spec describes the desired state of the KeptnTask. || ✓ | +| `status` _[KeptnTaskStatus](#keptntaskstatus)_ | Status describes the current state of the KeptnTask. || ✓ | + + +#### KeptnTaskDefinition + + + +KeptnTaskDefinition is the Schema for the keptntaskdefinitions API + +_Appears in:_ +- [KeptnTaskDefinitionList](#keptntaskdefinitionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnTaskDefinition` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnTaskDefinitionSpec](#keptntaskdefinitionspec)_ | Spec describes the desired state of the KeptnTaskDefinition. || ✓ | +| `status` _[KeptnTaskDefinitionStatus](#keptntaskdefinitionstatus)_ | Status describes the current state of the KeptnTaskDefinition. || ✓ | + + +#### KeptnTaskDefinitionList + + + +KeptnTaskDefinitionList contains a list of KeptnTaskDefinition + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnTaskDefinitionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnTaskDefinition](#keptntaskdefinition) array_ | || x | + + +#### KeptnTaskDefinitionSpec + + + +KeptnTaskDefinitionSpec defines the desired state of KeptnTaskDefinition + +_Appears in:_ +- [KeptnTaskDefinition](#keptntaskdefinition) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `function` _[RuntimeSpec](#runtimespec)_ | Deprecated Function contains the definition for the function that is to be executed in KeptnTasks based on the KeptnTaskDefinitions. || ✓ | +| `python` _[RuntimeSpec](#runtimespec)_ | Python contains the definition for the python function that is to be executed in KeptnTasks based on the KeptnTaskDefinitions. || ✓ | +| `deno` _[RuntimeSpec](#runtimespec)_ | Deno contains the definition for the Deno function that is to be executed in KeptnTasks based on the KeptnTaskDefinitions. || ✓ | +| `container` _[ContainerSpec](#containerspec)_ | Container contains the definition for the container that is to be used in Job based on the KeptnTaskDefinitions. || ✓ | +| `retries` _integer_ | Retries specifies how many times a job executing the KeptnTaskDefinition should be restarted in the case of an unsuccessful attempt. |10| ✓ | +| `timeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | Timeout specifies the maximum time to wait for the task to be completed successfully. If the task does not complete successfully within this time frame, it will be considered to be failed. |5m| ✓ | +| `serviceAccount` _[ServiceAccountSpec](#serviceaccountspec)_ | ServiceAccount specifies the service account to be used in jobs to authenticate with the Kubernetes API and access cluster resources. || ✓ | +| `automountServiceAccountToken` _[AutomountServiceAccountTokenSpec](#automountserviceaccounttokenspec)_ | AutomountServiceAccountToken allows to enable K8s to assign cluster API credentials to a pod, if set to false the pod will decline the service account || ✓ | +| `ttlSecondsAfterFinished` _integer_ | TTLSecondsAfterFinished controller makes a job eligible to be cleaned up after it is finished. The timer starts when the status shows up to be Complete or Failed. |300| ✓ | +| `imagePullSecrets` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#localobjectreference-v1-core) array_ | ImagePullSecrets is an optional field to specify the names of secrets to use for pulling container images || ✓ | + + +#### KeptnTaskDefinitionStatus + + + +KeptnTaskDefinitionStatus defines the observed state of KeptnTaskDefinition + +_Appears in:_ +- [KeptnTaskDefinition](#keptntaskdefinition) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `function` _[FunctionStatus](#functionstatus)_ | Function contains status information of the function definition for the task. || ✓ | + + +#### KeptnTaskList + + + +KeptnTaskList contains a list of KeptnTask + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnTaskList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnTask](#keptntask) array_ | || x | + + +#### KeptnTaskSpec + + + +KeptnTaskSpec defines the desired state of KeptnTask + +_Appears in:_ +- [KeptnTask](#keptntask) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `taskDefinition` _string_ | TaskDefinition refers to the name of the KeptnTaskDefinition which includes the specification for the task to be performed. The KeptnTaskDefinition can be located in the same namespace as the KeptnTask, or in the Keptn namespace. || x | +| `context` _[TaskContext](#taskcontext)_ | Context contains contextual information about the task execution. || ✓ | +| `parameters` _[TaskParameters](#taskparameters)_ | Parameters contains parameters that will be passed to the job that executes the task. || ✓ | +| `secureParameters` _[SecureParameters](#secureparameters)_ | SecureParameters contains secure parameters that will be passed to the job that executes the task. These will be stored and accessed as secrets in the cluster. || ✓ | +| `checkType` _string_ | Type indicates whether the KeptnTask is part of the pre- or postDeployment phase. || ✓ | +| `retries` _integer_ | Retries indicates how many times the KeptnTask can be attempted in the case of an error before considering the KeptnTask to be failed. |10| ✓ | +| `timeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | Timeout specifies the maximum time to wait for the task to be completed successfully. If the task does not complete successfully within this time frame, it will be considered to be failed. |5m| ✓ | + + +#### KeptnTaskStatus + + + +KeptnTaskStatus defines the observed state of KeptnTask + +_Appears in:_ +- [KeptnTask](#keptntask) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `jobName` _string_ | JobName is the name of the Job executing the Task. || ✓ | +| `status` _string_ | Status represents the overall state of the KeptnTask. |Pending| ✓ | +| `message` _string_ | Message contains information about unexpected errors encountered during the execution of the KeptnTask. || ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | StartTime represents the time at which the KeptnTask started. || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | EndTime represents the time at which the KeptnTask finished. || ✓ | +| `reason` _string_ | Reason contains more information about the reason for the last transition of the Job executing the KeptnTask. || ✓ | + + +#### KeptnWorkload + + + +KeptnWorkload is the Schema for the keptnworkloads API + +_Appears in:_ +- [KeptnWorkloadList](#keptnworkloadlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnWorkload` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnWorkloadSpec](#keptnworkloadspec)_ | Spec describes the desired state of the KeptnWorkload. || ✓ | +| `status` _[KeptnWorkloadStatus](#keptnworkloadstatus)_ | Status describes the current state of the KeptnWorkload. || ✓ | + + +#### KeptnWorkloadInstance + + + +KeptnWorkloadInstance is the Schema for the keptnworkloadinstances API + +_Appears in:_ +- [KeptnWorkloadInstanceList](#keptnworkloadinstancelist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnWorkloadInstance` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnWorkloadInstanceSpec](#keptnworkloadinstancespec)_ | Spec describes the desired state of the KeptnWorkloadInstance. || ✓ | +| `status` _[KeptnWorkloadInstanceStatus](#keptnworkloadinstancestatus)_ | Status describes the current state of the KeptnWorkloadInstance. || ✓ | + + +#### KeptnWorkloadInstanceList + + + +KeptnWorkloadInstanceList contains a list of KeptnWorkloadInstance + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnWorkloadInstanceList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnWorkloadInstance](#keptnworkloadinstance) array_ | || x | + + +#### KeptnWorkloadInstanceSpec + + + +KeptnWorkloadInstanceSpec defines the desired state of KeptnWorkloadInstance + +_Appears in:_ +- [KeptnWorkloadInstance](#keptnworkloadinstance) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `app` _string_ | AppName is the name of the KeptnApp containing the KeptnWorkload. || x | +| `version` _string_ | Version defines the version of the KeptnWorkload. || x | +| `preDeploymentTasks` _string array_ | PreDeploymentTasks is a list of all tasks to be performed during the pre-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnTaskDefinitions located in the same namespace as the KeptnApp, or in the Keptn namespace. || ✓ | +| `postDeploymentTasks` _string array_ | PostDeploymentTasks is a list of all tasks to be performed during the post-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnTaskDefinitions located in the same namespace as the KeptnWorkload, or in the Keptn namespace. || ✓ | +| `preDeploymentEvaluations` _string array_ | PreDeploymentEvaluations is a list of all evaluations to be performed during the pre-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnEvaluationDefinitions located in the same namespace as the KeptnWorkload, or in the Keptn namespace. || ✓ | +| `postDeploymentEvaluations` _string array_ | PostDeploymentEvaluations is a list of all evaluations to be performed during the post-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnEvaluationDefinitions located in the same namespace as the KeptnWorkload, or in the Keptn namespace. || ✓ | +| `resourceReference` _[ResourceReference](#resourcereference)_ | ResourceReference is a reference to the Kubernetes resource (Deployment, DaemonSet, StatefulSet or ReplicaSet) the KeptnWorkload is representing. || x | +| `workloadName` _string_ | WorkloadName is the name of the KeptnWorkload. || x | +| `previousVersion` _string_ | PreviousVersion is the version of the KeptnWorkload that has been deployed prior to this version. || ✓ | +| `traceId` _object (keys:string, values:string)_ | TraceId contains the OpenTelemetry trace ID. || ✓ | + + +#### KeptnWorkloadInstanceStatus + + + +KeptnWorkloadInstanceStatus defines the observed state of KeptnWorkloadInstance + +_Appears in:_ +- [KeptnWorkloadInstance](#keptnworkloadinstance) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `preDeploymentStatus` _string_ | PreDeploymentStatus indicates the current status of the KeptnWorkloadInstance's PreDeployment phase. |Pending| ✓ | +| `deploymentStatus` _string_ | DeploymentStatus indicates the current status of the KeptnWorkloadInstance's Deployment phase. |Pending| ✓ | +| `preDeploymentEvaluationStatus` _string_ | PreDeploymentEvaluationStatus indicates the current status of the KeptnWorkloadInstance's PreDeploymentEvaluation phase. |Pending| ✓ | +| `postDeploymentEvaluationStatus` _string_ | PostDeploymentEvaluationStatus indicates the current status of the KeptnWorkloadInstance's PostDeploymentEvaluation phase. |Pending| ✓ | +| `postDeploymentStatus` _string_ | PostDeploymentStatus indicates the current status of the KeptnWorkloadInstance's PostDeployment phase. |Pending| ✓ | +| `preDeploymentTaskStatus` _[ItemStatus](#itemstatus) array_ | PreDeploymentTaskStatus indicates the current state of each preDeploymentTask of the KeptnWorkloadInstance. || ✓ | +| `postDeploymentTaskStatus` _[ItemStatus](#itemstatus) array_ | PostDeploymentTaskStatus indicates the current state of each postDeploymentTask of the KeptnWorkloadInstance. || ✓ | +| `preDeploymentEvaluationTaskStatus` _[ItemStatus](#itemstatus) array_ | PreDeploymentEvaluationTaskStatus indicates the current state of each preDeploymentEvaluation of the KeptnWorkloadInstance. || ✓ | +| `postDeploymentEvaluationTaskStatus` _[ItemStatus](#itemstatus) array_ | PostDeploymentEvaluationTaskStatus indicates the current state of each postDeploymentEvaluation of the KeptnWorkloadInstance. || ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | StartTime represents the time at which the deployment of the KeptnWorkloadInstance started. || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | EndTime represents the time at which the deployment of the KeptnWorkloadInstance finished. || ✓ | +| `currentPhase` _string_ | CurrentPhase indicates the current phase of the KeptnWorkloadInstance. This can be: - PreDeploymentTasks - PreDeploymentEvaluations - Deployment - PostDeploymentTasks - PostDeploymentEvaluations || ✓ | +| `phaseTraceIDs` _[MapCarrier](https://pkg.go.dev/go.opentelemetry.io/otel/propagation#MapCarrier)_ | PhaseTraceIDs contains the trace IDs of the OpenTelemetry spans of each phase of the KeptnWorkloadInstance || ✓ | +| `status` _string_ | Status represents the overall status of the KeptnWorkloadInstance. |Pending| ✓ | + + +#### KeptnWorkloadList + + + +KeptnWorkloadList contains a list of KeptnWorkload + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnWorkloadList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnWorkload](#keptnworkload) array_ | || x | + + +#### KeptnWorkloadRef + + + +KeptnWorkloadRef refers to a KeptnWorkload that is part of a KeptnApp + +_Appears in:_ +- [KeptnAppSpec](#keptnappspec) +- [KeptnAppVersionSpec](#keptnappversionspec) +- [WorkloadStatus](#workloadstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | Name is the name of the KeptnWorkload. || x | +| `version` _string_ | Version is the version of the KeptnWorkload. || x | + + +#### KeptnWorkloadSpec + + + +KeptnWorkloadSpec defines the desired state of KeptnWorkload + +_Appears in:_ +- [KeptnWorkload](#keptnworkload) +- [KeptnWorkloadInstanceSpec](#keptnworkloadinstancespec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `app` _string_ | AppName is the name of the KeptnApp containing the KeptnWorkload. || x | +| `version` _string_ | Version defines the version of the KeptnWorkload. || x | +| `preDeploymentTasks` _string array_ | PreDeploymentTasks is a list of all tasks to be performed during the pre-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnTaskDefinitions located in the same namespace as the KeptnApp, or in the Keptn namespace. || ✓ | +| `postDeploymentTasks` _string array_ | PostDeploymentTasks is a list of all tasks to be performed during the post-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnTaskDefinitions located in the same namespace as the KeptnWorkload, or in the Keptn namespace. || ✓ | +| `preDeploymentEvaluations` _string array_ | PreDeploymentEvaluations is a list of all evaluations to be performed during the pre-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnEvaluationDefinitions located in the same namespace as the KeptnWorkload, or in the Keptn namespace. || ✓ | +| `postDeploymentEvaluations` _string array_ | PostDeploymentEvaluations is a list of all evaluations to be performed during the post-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnEvaluationDefinitions located in the same namespace as the KeptnWorkload, or in the Keptn namespace. || ✓ | +| `resourceReference` _[ResourceReference](#resourcereference)_ | ResourceReference is a reference to the Kubernetes resource (Deployment, DaemonSet, StatefulSet or ReplicaSet) the KeptnWorkload is representing. || x | + + +#### KeptnWorkloadStatus + + + +KeptnWorkloadStatus defines the observed state of KeptnWorkload + +_Appears in:_ +- [KeptnWorkload](#keptnworkload) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `currentVersion` _string_ | CurrentVersion indicates the version that is currently deployed or being reconciled. || ✓ | + + +#### Objective + + + + + +_Appears in:_ +- [KeptnEvaluationDefinitionSpec](#keptnevaluationdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `keptnMetricRef` _[KeptnMetricReference](#keptnmetricreference)_ | KeptnMetricRef references the KeptnMetric that should be evaluated. || x | +| `evaluationTarget` _string_ | EvaluationTarget specifies the target value for the references KeptnMetric. Needs to start with either '<' or '>', followed by the target value (e.g. '<10'). || x | + + +#### ResourceReference + + + +ResourceReference represents the parent resource of Workload + +_Appears in:_ +- [KeptnWorkloadInstanceSpec](#keptnworkloadinstancespec) +- [KeptnWorkloadSpec](#keptnworkloadspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `uid` _string_ | || x | +| `kind` _string_ | || x | +| `name` _string_ | || x | + + +#### RuntimeSpec + + + + + +_Appears in:_ +- [KeptnTaskDefinitionSpec](#keptntaskdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `functionRef` _[FunctionReference](#functionreference)_ | FunctionReference allows to reference another KeptnTaskDefinition which contains the source code of the function to be executes for KeptnTasks based on this KeptnTaskDefinition. This can be useful when you have multiple KeptnTaskDefinitions that should execute the same logic, but each with different parameters. || ✓ | +| `inline` _[Inline](#inline)_ | Inline allows to specify the code that should be executed directly in the KeptnTaskDefinition, as a multi-line string. || ✓ | +| `httpRef` _[HttpReference](#httpreference)_ | HttpReference allows to point to an HTTP URL containing the code of the function. || ✓ | +| `configMapRef` _[ConfigMapReference](#configmapreference)_ | ConfigMapReference allows to reference a ConfigMap containing the code of the function. When referencing a ConfigMap, the code of the function must be available as a value of the 'code' key of the referenced ConfigMap. || ✓ | +| `parameters` _[TaskParameters](#taskparameters)_ | Parameters contains parameters that will be passed to the job that executes the task as env variables. || ✓ | +| `secureParameters` _[SecureParameters](#secureparameters)_ | SecureParameters contains secure parameters that will be passed to the job that executes the task. These will be stored and accessed as secrets in the cluster. || ✓ | +| `cmdParameters` _string_ | CmdParameters contains parameters that will be passed to the command || ✓ | + + +#### SecureParameters + + + + + +_Appears in:_ +- [KeptnTaskSpec](#keptntaskspec) +- [RuntimeSpec](#runtimespec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `secret` _string_ | Secret contains the parameters that will be made available to the job executing the KeptnTask via the 'SECRET_DATA' environment variable. The 'SECRET_DATA' environment variable's content will the same as value of the 'SECRET_DATA' key of the referenced secret. || ✓ | + + +#### ServiceAccountSpec + + + + + +_Appears in:_ +- [KeptnTaskDefinitionSpec](#keptntaskdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | || x | + + +#### TaskContext + + + + + +_Appears in:_ +- [KeptnTaskSpec](#keptntaskspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `workloadName` _string_ | WorkloadName the name of the KeptnWorkload the KeptnTask is being executed for. || ✓ | +| `appName` _string_ | AppName the name of the KeptnApp the KeptnTask is being executed for. || ✓ | +| `appVersion` _string_ | AppVersion the version of the KeptnApp the KeptnTask is being executed for. || ✓ | +| `workloadVersion` _string_ | WorkloadVersion the version of the KeptnWorkload the KeptnTask is being executed for. || ✓ | +| `taskType` _string_ | TaskType indicates whether the KeptnTask is part of the pre- or postDeployment phase. || ✓ | +| `objectType` _string_ | ObjectType indicates whether the KeptnTask is being executed for a KeptnApp or KeptnWorkload. || ✓ | + + +#### TaskParameters + + + + + +_Appears in:_ +- [KeptnTaskSpec](#keptntaskspec) +- [RuntimeSpec](#runtimespec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `map` _object (keys:string, values:string)_ | Inline contains the parameters that will be made available to the job executing the KeptnTask via the 'DATA' environment variable. The 'DATA' environment variable's content will be a json encoded string containing all properties of the map provided. || ✓ | + + +#### WorkloadStatus + + + + + +_Appears in:_ +- [KeptnAppVersionStatus](#keptnappversionstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `workload` _[KeptnWorkloadRef](#keptnworkloadref)_ | Workload refers to a KeptnWorkload that is part of the KeptnAppVersion. || ✓ | +| `status` _string_ | Status indicates the current status of the KeptnWorkload. |Pending| ✓ | + + diff --git a/docs-new/docs/reference/api-reference/lifecycle/v1alpha4/index.md b/docs-new/docs/reference/api-reference/lifecycle/v1alpha4/index.md new file mode 100644 index 0000000000..2d3441779e --- /dev/null +++ b/docs-new/docs/reference/api-reference/lifecycle/v1alpha4/index.md @@ -0,0 +1,101 @@ +# v1alpha4 + + +## Packages +- [lifecycle.keptn.sh/v1alpha4](#lifecyclekeptnshv1alpha4) + + +## lifecycle.keptn.sh/v1alpha4 + +Package v1alpha4 contains API Schema definitions for the lifecycle v1alpha4 API group + +### Resource Types +- [KeptnWorkloadVersion](#keptnworkloadversion) +- [KeptnWorkloadVersionList](#keptnworkloadversionlist) + + + +#### KeptnWorkloadVersion + + + +KeptnWorkloadVersion is the Schema for the keptnworkloadversions API + +_Appears in:_ +- [KeptnWorkloadVersionList](#keptnworkloadversionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha4` | | | +| `kind` _string_ | `KeptnWorkloadVersion` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnWorkloadVersionSpec](#keptnworkloadversionspec)_ | Spec describes the desired state of the KeptnWorkloadVersion. || ✓ | +| `status` _[KeptnWorkloadVersionStatus](#keptnworkloadversionstatus)_ | Status describes the current state of the KeptnWorkloadVersion. || ✓ | + + +#### KeptnWorkloadVersionList + + + +KeptnWorkloadVersionList contains a list of KeptnWorkloadVersion + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `lifecycle.keptn.sh/v1alpha4` | | | +| `kind` _string_ | `KeptnWorkloadVersionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnWorkloadVersion](#keptnworkloadversion) array_ | || x | + + +#### KeptnWorkloadVersionSpec + + + +KeptnWorkloadVersionSpec defines the desired state of KeptnWorkloadVersion + +_Appears in:_ +- [KeptnWorkloadVersion](#keptnworkloadversion) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `app` _string_ | AppName is the name of the KeptnApp containing the KeptnWorkload. || x | +| `version` _string_ | Version defines the version of the KeptnWorkload. || x | +| `preDeploymentTasks` _string array_ | PreDeploymentTasks is a list of all tasks to be performed during the pre-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnTaskDefinitions located in the same namespace as the KeptnApp, or in the Keptn namespace. || ✓ | +| `postDeploymentTasks` _string array_ | PostDeploymentTasks is a list of all tasks to be performed during the post-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnTaskDefinitions located in the same namespace as the KeptnWorkload, or in the Keptn namespace. || ✓ | +| `preDeploymentEvaluations` _string array_ | PreDeploymentEvaluations is a list of all evaluations to be performed during the pre-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnEvaluationDefinitions located in the same namespace as the KeptnWorkload, or in the Keptn namespace. || ✓ | +| `postDeploymentEvaluations` _string array_ | PostDeploymentEvaluations is a list of all evaluations to be performed during the post-deployment phase of the KeptnWorkload. The items of this list refer to the names of KeptnEvaluationDefinitions located in the same namespace as the KeptnWorkload, or in the Keptn namespace. || ✓ | +| `resourceReference` _[ResourceReference](../v1alpha3/index.md##resourcereference)_ | ResourceReference is a reference to the Kubernetes resource (Deployment, DaemonSet, StatefulSet or ReplicaSet) the KeptnWorkload is representing. || x | +| `workloadName` _string_ | WorkloadName is the name of the KeptnWorkload. || x | +| `previousVersion` _string_ | PreviousVersion is the version of the KeptnWorkload that has been deployed prior to this version. || ✓ | +| `traceId` _object (keys:string, values:string)_ | TraceId contains the OpenTelemetry trace ID. || ✓ | + + +#### KeptnWorkloadVersionStatus + + + +KeptnWorkloadVersionStatus defines the observed state of KeptnWorkloadVersion + +_Appears in:_ +- [KeptnWorkloadVersion](#keptnworkloadversion) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `preDeploymentStatus` _string_ | PreDeploymentStatus indicates the current status of the KeptnWorkloadVersion's PreDeployment phase. |Pending| ✓ | +| `deploymentStatus` _string_ | DeploymentStatus indicates the current status of the KeptnWorkloadVersion's Deployment phase. |Pending| ✓ | +| `preDeploymentEvaluationStatus` _string_ | PreDeploymentEvaluationStatus indicates the current status of the KeptnWorkloadVersion's PreDeploymentEvaluation phase. |Pending| ✓ | +| `postDeploymentEvaluationStatus` _string_ | PostDeploymentEvaluationStatus indicates the current status of the KeptnWorkloadVersion's PostDeploymentEvaluation phase. |Pending| ✓ | +| `postDeploymentStatus` _string_ | PostDeploymentStatus indicates the current status of the KeptnWorkloadVersion's PostDeployment phase. |Pending| ✓ | +| `preDeploymentTaskStatus` _[ItemStatus](../v1alpha3/index.md##itemstatus) array_ | PreDeploymentTaskStatus indicates the current state of each preDeploymentTask of the KeptnWorkloadVersion. || ✓ | +| `postDeploymentTaskStatus` _[ItemStatus](../v1alpha3/index.md##itemstatus) array_ | PostDeploymentTaskStatus indicates the current state of each postDeploymentTask of the KeptnWorkloadVersion. || ✓ | +| `preDeploymentEvaluationTaskStatus` _[ItemStatus](../v1alpha3/index.md##itemstatus) array_ | PreDeploymentEvaluationTaskStatus indicates the current state of each preDeploymentEvaluation of the KeptnWorkloadVersion. || ✓ | +| `postDeploymentEvaluationTaskStatus` _[ItemStatus](../v1alpha3/index.md##itemstatus) array_ | PostDeploymentEvaluationTaskStatus indicates the current state of each postDeploymentEvaluation of the KeptnWorkloadVersion. || ✓ | +| `startTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | StartTime represents the time at which the deployment of the KeptnWorkloadVersion started. || ✓ | +| `endTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | EndTime represents the time at which the deployment of the KeptnWorkloadVersion finished. || ✓ | +| `currentPhase` _string_ | CurrentPhase indicates the current phase of the KeptnWorkloadVersion. This can be: - PreDeploymentTasks - PreDeploymentEvaluations - Deployment - PostDeploymentTasks - PostDeploymentEvaluations || ✓ | +| `phaseTraceIDs` _[MapCarrier](https://pkg.go.dev/go.opentelemetry.io/otel/propagation#MapCarrier)_ | PhaseTraceIDs contains the trace IDs of the OpenTelemetry spans of each phase of the KeptnWorkloadVersion || ✓ | +| `status` _string_ | Status represents the overall status of the KeptnWorkloadVersion. |Pending| ✓ | + + diff --git a/docs-new/docs/reference/api-reference/metrics/index.md b/docs-new/docs/reference/api-reference/metrics/index.md new file mode 100644 index 0000000000..f81bd1baa4 --- /dev/null +++ b/docs-new/docs/reference/api-reference/metrics/index.md @@ -0,0 +1 @@ +# Metrics API diff --git a/docs-new/docs/reference/api-reference/metrics/v1alpha1/index.md b/docs-new/docs/reference/api-reference/metrics/v1alpha1/index.md new file mode 100644 index 0000000000..bb084a214d --- /dev/null +++ b/docs-new/docs/reference/api-reference/metrics/v1alpha1/index.md @@ -0,0 +1,97 @@ +# v1alpha1 + + +## Packages +- [metrics.keptn.sh/v1alpha1](#metricskeptnshv1alpha1) + + +## metrics.keptn.sh/v1alpha1 + +Package v1alpha1 contains API Schema definitions for the metrics v1alpha1 API group + +### Resource Types +- [KeptnMetric](#keptnmetric) +- [KeptnMetricList](#keptnmetriclist) + + + +#### KeptnMetric + + + +KeptnMetric is the Schema for the keptnmetrics API + +_Appears in:_ +- [KeptnMetricList](#keptnmetriclist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnMetric` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnMetricSpec](#keptnmetricspec)_ | || ✓ | +| `status` _[KeptnMetricStatus](#keptnmetricstatus)_ | || ✓ | + + +#### KeptnMetricList + + + +KeptnMetricList contains a list of KeptnMetric + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnMetricList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnMetric](#keptnmetric) array_ | || x | + + +#### KeptnMetricSpec + + + +KeptnMetricSpec defines the desired state of KeptnMetric + +_Appears in:_ +- [KeptnMetric](#keptnmetric) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `provider` _[ProviderRef](#providerref)_ | Provider represents the provider object || x | +| `query` _string_ | Query represents the query to be run || x | +| `fetchIntervalSeconds` _integer_ | FetchIntervalSeconds represents the update frequency in seconds that is used to update the metric || x | + + +#### KeptnMetricStatus + + + +KeptnMetricStatus defines the observed state of KeptnMetric + +_Appears in:_ +- [KeptnMetric](#keptnmetric) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `value` _string_ | Value represents the resulting value || x | +| `rawValue` _integer array_ | RawValue represents the resulting value in raw format || x | +| `lastUpdated` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | LastUpdated represents the time when the status data was last updated || x | + + +#### ProviderRef + + + +ProviderRef represents the provider object + +_Appears in:_ +- [KeptnMetricSpec](#keptnmetricspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | Name of the provider || x | + + diff --git a/docs-new/docs/reference/api-reference/metrics/v1alpha2/index.md b/docs-new/docs/reference/api-reference/metrics/v1alpha2/index.md new file mode 100644 index 0000000000..da081af39b --- /dev/null +++ b/docs-new/docs/reference/api-reference/metrics/v1alpha2/index.md @@ -0,0 +1,149 @@ +# v1alpha2 + + +## Packages +- [metrics.keptn.sh/v1alpha2](#metricskeptnshv1alpha2) + + + +## metrics.keptn.sh/v1alpha2 + +Package v1alpha2 contains API Schema definitions for the metrics v1alpha2 API group + +### Resource Types +- [KeptnMetric](#keptnmetric) +- [KeptnMetricList](#keptnmetriclist) +- [KeptnMetricsProvider](#keptnmetricsprovider) +- [KeptnMetricsProviderList](#keptnmetricsproviderlist) + + + +#### KeptnMetric + + + +KeptnMetric is the Schema for the keptnmetrics API + +_Appears in:_ +- [KeptnMetricList](#keptnmetriclist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnMetric` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnMetricSpec](#keptnmetricspec)_ | || ✓ | +| `status` _[KeptnMetricStatus](#keptnmetricstatus)_ | || ✓ | + + +#### KeptnMetricList + + + +KeptnMetricList contains a list of KeptnMetric + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnMetricList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnMetric](#keptnmetric) array_ | || x | + + +#### KeptnMetricSpec + + + +KeptnMetricSpec defines the desired state of KeptnMetric + +_Appears in:_ +- [KeptnMetric](#keptnmetric) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `provider` _[ProviderRef](#providerref)_ | Provider represents the provider object || x | +| `query` _string_ | Query represents the query to be run || x | +| `fetchIntervalSeconds` _integer_ | FetchIntervalSeconds represents the update frequency in seconds that is used to update the metric || x | + + +#### KeptnMetricStatus + + + +KeptnMetricStatus defines the observed state of KeptnMetric + +_Appears in:_ +- [KeptnMetric](#keptnmetric) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `value` _string_ | Value represents the resulting value || x | +| `rawValue` _integer array_ | RawValue represents the resulting value in raw format || x | +| `lastUpdated` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | LastUpdated represents the time when the status data was last updated || x | + + +#### KeptnMetricsProvider + + + +KeptnMetricsProvider is the Schema for the keptnmetricsproviders API + +_Appears in:_ +- [KeptnMetricsProviderList](#keptnmetricsproviderlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnMetricsProvider` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnMetricsProviderSpec](#keptnmetricsproviderspec)_ | || ✓ | +| `status` _string_ | unused field || ✓ | + + +#### KeptnMetricsProviderList + + + +KeptnMetricsProviderList contains a list of KeptnMetricsProvider + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha2` | | | +| `kind` _string_ | `KeptnMetricsProviderList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnMetricsProvider](#keptnmetricsprovider) array_ | || x | + + +#### KeptnMetricsProviderSpec + + + +KeptnMetricsProviderSpec defines the desired state of KeptnMetricsProvider + +_Appears in:_ +- [KeptnMetricsProvider](#keptnmetricsprovider) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `targetServer` _string_ | || x | +| `secretKeyRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#secretkeyselector-v1-core)_ | || ✓ | + + +#### ProviderRef + + + +ProviderRef represents the provider object + +_Appears in:_ +- [KeptnMetricSpec](#keptnmetricspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | Name of the provider || x | + + diff --git a/docs-new/docs/reference/api-reference/metrics/v1alpha3/index.md b/docs-new/docs/reference/api-reference/metrics/v1alpha3/index.md new file mode 100644 index 0000000000..807665ec8c --- /dev/null +++ b/docs-new/docs/reference/api-reference/metrics/v1alpha3/index.md @@ -0,0 +1,519 @@ +# v1alpha3 + + +## Packages +- [metrics.keptn.sh/v1alpha3](#metricskeptnshv1alpha3) + + +## metrics.keptn.sh/v1alpha3 + +Package v1alpha3 contains API Schema definitions for the metrics v1alpha3 API group + +### Resource Types +- [Analysis](#analysis) +- [AnalysisDefinition](#analysisdefinition) +- [AnalysisDefinitionList](#analysisdefinitionlist) +- [AnalysisList](#analysislist) +- [AnalysisValueTemplate](#analysisvaluetemplate) +- [AnalysisValueTemplateList](#analysisvaluetemplatelist) +- [KeptnMetric](#keptnmetric) +- [KeptnMetricList](#keptnmetriclist) +- [KeptnMetricsProvider](#keptnmetricsprovider) +- [KeptnMetricsProviderList](#keptnmetricsproviderlist) + + + +#### Analysis + + + +Analysis is the Schema for the analyses API + +_Appears in:_ +- [AnalysisList](#analysislist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `Analysis` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[AnalysisSpec](#analysisspec)_ | || ✓ | +| `status` _[AnalysisStatus](#analysisstatus)_ | || ✓ | + + +#### AnalysisDefinition + + + +AnalysisDefinition is the Schema for the analysisdefinitions APIs + +_Appears in:_ +- [AnalysisDefinitionList](#analysisdefinitionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `AnalysisDefinition` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[AnalysisDefinitionSpec](#analysisdefinitionspec)_ | || ✓ | +| `status` _string_ | unused field || ✓ | + + +#### AnalysisDefinitionList + + + +AnalysisDefinitionList contains a list of AnalysisDefinition + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `AnalysisDefinitionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[AnalysisDefinition](#analysisdefinition) array_ | || x | + + +#### AnalysisDefinitionSpec + + + +AnalysisDefinitionSpec defines the desired state of AnalysisDefinition + +_Appears in:_ +- [AnalysisDefinition](#analysisdefinition) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `objectives` _[Objective](#objective) array_ | Objectives defines a list of objectives to evaluate for an analysis || ✓ | +| `totalScore` _[TotalScore](#totalscore)_ | TotalScore defines the required score for an analysis to be successful || x | + + +#### AnalysisList + + + +AnalysisList contains a list of Analysis + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `AnalysisList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[Analysis](#analysis) array_ | || x | + + +#### AnalysisSpec + + + +AnalysisSpec defines the desired state of Analysis + +_Appears in:_ +- [Analysis](#analysis) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `timeframe` _[Timeframe](#timeframe)_ | Timeframe specifies the range for the corresponding query in the AnalysisValueTemplate. Please note that either a combination of 'from' and 'to' or the 'recent' property may be set. If neither is set, the Analysis can not be added to the cluster. || x | +| `args` _object (keys:string, values:string)_ | Args corresponds to a map of key/value pairs that can be used to substitute placeholders in the AnalysisValueTemplate query. i.e. for args foo:bar the query could be "query:percentile(95)?scope=tag(my_foo_label:{{.foo}})". || ✓ | +| `analysisDefinition` _[ObjectReference](#objectreference)_ | AnalysisDefinition refers to the AnalysisDefinition, a CRD that stores the AnalysisValuesTemplates || x | + + +#### AnalysisState + +_Underlying type:_ _string_ + +AnalysisState represents the state of the analysis + +_Appears in:_ +- [AnalysisStatus](#analysisstatus) + + + +#### AnalysisStatus + + + +AnalysisStatus stores the status of the overall analysis returns also pass or warnings + +_Appears in:_ +- [Analysis](#analysis) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `timeframe` _[Timeframe](#timeframe)_ | Timeframe describes the time frame which is evaluated by the Analysis || x | +| `raw` _string_ | Raw contains the raw result of the SLO computation || ✓ | +| `pass` _boolean_ | Pass returns whether the SLO is satisfied || ✓ | +| `warning` _boolean_ | Warning returns whether the analysis returned a warning || ✓ | +| `state` _string_ | State describes the current state of the Analysis (Pending/Progressing/Completed) || x | +| `storedValues` _object (keys:string, values:[ProviderResult](#providerresult))_ | StoredValues contains all analysis values that have already been retrieved successfully || ✓ | + + +#### AnalysisValueTemplate + + + +AnalysisValueTemplate is the Schema for the analysisvaluetemplates API + +_Appears in:_ +- [AnalysisValueTemplateList](#analysisvaluetemplatelist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `AnalysisValueTemplate` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[AnalysisValueTemplateSpec](#analysisvaluetemplatespec)_ | Spec contains the specification for the AnalysisValueTemplate || ✓ | +| `status` _string_ | unused field || ✓ | + + +#### AnalysisValueTemplateList + + + +AnalysisValueTemplateList contains a list of AnalysisValueTemplate + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `AnalysisValueTemplateList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[AnalysisValueTemplate](#analysisvaluetemplate) array_ | || x | + + +#### AnalysisValueTemplateSpec + + + +AnalysisValueTemplateSpec defines the desired state of AnalysisValueTemplate + +_Appears in:_ +- [AnalysisValueTemplate](#analysisvaluetemplate) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `provider` _[ObjectReference](#objectreference)_ | Provider refers to the KeptnMetricsProvider which should be used to retrieve the data || x | +| `query` _string_ | Query represents the query to be run. It can include placeholders that are defined using the go template syntax. More info on go templating - https://pkg.go.dev/text/template || x | + + +#### IntervalResult + + + + + +_Appears in:_ +- [KeptnMetricStatus](#keptnmetricstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `value` _string_ | Value represents the resulting value || x | +| `range` _[RangeSpec](#rangespec)_ | Range represents the time range for which this data was queried || x | +| `lastUpdated` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | LastUpdated represents the time when the status data was last updated || x | +| `errMsg` _string_ | ErrMsg represents the error details when the query could not be evaluated || ✓ | + + +#### KeptnMetric + + + +KeptnMetric is the Schema for the keptnmetrics API + +_Appears in:_ +- [KeptnMetricList](#keptnmetriclist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnMetric` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnMetricSpec](#keptnmetricspec)_ | || ✓ | +| `status` _[KeptnMetricStatus](#keptnmetricstatus)_ | || ✓ | + + +#### KeptnMetricList + + + +KeptnMetricList contains a list of KeptnMetric + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnMetricList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnMetric](#keptnmetric) array_ | || x | + + +#### KeptnMetricSpec + + + +KeptnMetricSpec defines the desired state of KeptnMetric + +_Appears in:_ +- [KeptnMetric](#keptnmetric) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `provider` _[ProviderRef](#providerref)_ | Provider represents the provider object || x | +| `query` _string_ | Query represents the query to be run || x | +| `fetchIntervalSeconds` _integer_ | FetchIntervalSeconds represents the update frequency in seconds that is used to update the metric || x | +| `range` _[RangeSpec](#rangespec)_ | Range represents the time range for which data is to be queried || ✓ | + + +#### KeptnMetricStatus + + + +KeptnMetricStatus defines the observed state of KeptnMetric + +_Appears in:_ +- [KeptnMetric](#keptnmetric) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `value` _string_ | Value represents the resulting value || ✓ | +| `rawValue` _integer array_ | RawValue represents the resulting value in raw format || ✓ | +| `lastUpdated` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | LastUpdated represents the time when the status data was last updated || ✓ | +| `errMsg` _string_ | ErrMsg represents the error details when the query could not be evaluated || ✓ | +| `intervalResults` _[IntervalResult](#intervalresult) array_ | IntervalResults contain a slice of all the interval results || ✓ | + + +#### KeptnMetricsProvider + + + +KeptnMetricsProvider is the Schema for the keptnmetricsproviders API + +_Appears in:_ +- [KeptnMetricsProviderList](#keptnmetricsproviderlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnMetricsProvider` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnMetricsProviderSpec](#keptnmetricsproviderspec)_ | || ✓ | +| `status` _string_ | unused field || ✓ | + + +#### KeptnMetricsProviderList + + + +KeptnMetricsProviderList contains a list of KeptnMetricsProvider + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1alpha3` | | | +| `kind` _string_ | `KeptnMetricsProviderList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnMetricsProvider](#keptnmetricsprovider) array_ | || x | + + +#### KeptnMetricsProviderSpec + + + +KeptnMetricsProviderSpec defines the desired state of KeptnMetricsProvider + +_Appears in:_ +- [KeptnMetricsProvider](#keptnmetricsprovider) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `type` _string_ | Type represents the provider type. This can be one of prometheus, dynatrace, datadog, dql. || x | +| `targetServer` _string_ | TargetServer defined the URL at which the metrics provider is reachable with included port and protocol. || x | +| `secretKeyRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#secretkeyselector-v1-core)_ | SecretKeyRef defines an optional secret for access credentials to the metrics provider. || ✓ | + + +#### ObjectReference + + + + + +_Appears in:_ +- [AnalysisSpec](#analysisspec) +- [AnalysisValueTemplateSpec](#analysisvaluetemplatespec) +- [Objective](#objective) +- [ProviderResult](#providerresult) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | Name defines the name of the referenced object || x | +| `namespace` _string_ | Namespace defines the namespace of the referenced object || ✓ | + + +#### Objective + + + +Objective defines an objective for analysis + +_Appears in:_ +- [AnalysisDefinitionSpec](#analysisdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `analysisValueTemplateRef` _[ObjectReference](#objectreference)_ | AnalysisValueTemplateRef refers to the appropriate AnalysisValueTemplate || x | +| `target` _[Target](#target)_ | Target defines failure or warning criteria || ✓ | +| `weight` _integer_ | Weight can be used to emphasize the importance of one Objective over the others |1| ✓ | +| `keyObjective` _boolean_ | KeyObjective defines whether the whole analysis fails when this objective's target is not met |false| ✓ | + + +#### Operator + + + +Operator specifies the supported operators for value comparisons + +_Appears in:_ +- [Target](#target) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `lessThanOrEqual` _[OperatorValue](#operatorvalue)_ | LessThanOrEqual represents '<=' operator || ✓ | +| `lessThan` _[OperatorValue](#operatorvalue)_ | LessThan represents '<' operator || ✓ | +| `greaterThan` _[OperatorValue](#operatorvalue)_ | GreaterThan represents '>' operator || ✓ | +| `greaterThanOrEqual` _[OperatorValue](#operatorvalue)_ | GreaterThanOrEqual represents '>=' operator || ✓ | +| `equalTo` _[OperatorValue](#operatorvalue)_ | EqualTo represents '==' operator || ✓ | +| `inRange` _[RangeValue](#rangevalue)_ | InRange represents operator checking the value is inclusively in the defined range, e.g. 2 <= x <= 5 || ✓ | +| `notInRange` _[RangeValue](#rangevalue)_ | NotInRange represents operator checking the value is exclusively out of the defined range, e.g. x < 2 AND x > 5 || ✓ | + + +#### OperatorValue + + + +OperatorValue represents the value to which the result is compared + +_Appears in:_ +- [Operator](#operator) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `fixedValue` _[Quantity](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity)_ | FixedValue defines the value for comparison || x | + + +#### ProviderRef + + + +ProviderRef represents the provider object + +_Appears in:_ +- [KeptnMetricSpec](#keptnmetricspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | Name of the provider || x | + + +#### ProviderResult + + + +ProviderResult stores reference of already collected provider query associated to its objective template + +_Appears in:_ +- [AnalysisStatus](#analysisstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `objectiveReference` _[ObjectReference](#objectreference)_ | Objective store reference to corresponding objective template || ✓ | +| `query` _string_ | Query represents the executed query || ✓ | +| `value` _string_ | Value is the value the provider returned || ✓ | +| `errMsg` _string_ | ErrMsg stores any possible error at retrieval time || ✓ | + + +#### RangeSpec + + + +RangeSpec defines the time range for which data is to be queried + +_Appears in:_ +- [IntervalResult](#intervalresult) +- [KeptnMetricSpec](#keptnmetricspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `interval` _string_ | Interval specifies the duration of the time interval for the data query |5m| ✓ | +| `step` _string_ | Step represents the query resolution step width for the data query || ✓ | +| `aggregation` _string_ | Aggregation defines the type of aggregation function to be applied on the data. Accepted values: p90, p95, p99, max, min, avg, median || ✓ | +| `storedResults` _integer_ | StoredResults indicates the upper limit of how many past results should be stored in the status of a KeptnMetric || ✓ | + + +#### RangeValue + + + +RangeValue represents a range which the value should fit + +_Appears in:_ +- [Operator](#operator) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `lowBound` _[Quantity](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity)_ | LowBound defines the lower bound of the range || x | +| `highBound` _[Quantity](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity)_ | HighBound defines the higher bound of the range || x | + + +#### Target + + + +Target defines the failure and warning criteria + +_Appears in:_ +- [Objective](#objective) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `failure` _[Operator](#operator)_ | Failure defines limits up to which an analysis fails || ✓ | +| `warning` _[Operator](#operator)_ | Warning defines limits where the result does not pass or fail || ✓ | + + +#### Timeframe + + + + + +_Appears in:_ +- [AnalysisSpec](#analysisspec) +- [AnalysisStatus](#analysisstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `from` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | From is the time of start for the query. This field follows RFC3339 time format || ✓ | +| `to` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | To is the time of end for the query. This field follows RFC3339 time format || ✓ | +| `recent` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | Recent describes a recent timeframe using a duration string. E.g. Setting this to '5m' provides an Analysis for the last five minutes || ✓ | + + +#### TotalScore + + + +TotalScore defines the required score for an analysis to be successful + +_Appears in:_ +- [AnalysisDefinitionSpec](#analysisdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `passPercentage` _integer_ | PassPercentage defines the threshold to reach for an analysis to pass || x | +| `warningPercentage` _integer_ | WarningPercentage defines the threshold to reach for an analysis to pass with a 'warning' status || x | + + diff --git a/docs-new/docs/reference/api-reference/metrics/v1beta1/index.md b/docs-new/docs/reference/api-reference/metrics/v1beta1/index.md new file mode 100644 index 0000000000..a811732481 --- /dev/null +++ b/docs-new/docs/reference/api-reference/metrics/v1beta1/index.md @@ -0,0 +1,519 @@ +# v1beta1 + + +## Packages +- [metrics.keptn.sh/v1beta1](#metricskeptnshv1beta1) + + +## metrics.keptn.sh/v1beta1 + +Package v1beta1 contains API Schema definitions for the metrics v1beta1 API group + +### Resource Types +- [Analysis](#analysis) +- [AnalysisDefinition](#analysisdefinition) +- [AnalysisDefinitionList](#analysisdefinitionlist) +- [AnalysisList](#analysislist) +- [AnalysisValueTemplate](#analysisvaluetemplate) +- [AnalysisValueTemplateList](#analysisvaluetemplatelist) +- [KeptnMetric](#keptnmetric) +- [KeptnMetricList](#keptnmetriclist) +- [KeptnMetricsProvider](#keptnmetricsprovider) +- [KeptnMetricsProviderList](#keptnmetricsproviderlist) + + + +#### Analysis + + + +Analysis is the Schema for the analyses API + +_Appears in:_ +- [AnalysisList](#analysislist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1beta1` | | | +| `kind` _string_ | `Analysis` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[AnalysisSpec](#analysisspec)_ | || ✓ | +| `status` _[AnalysisStatus](#analysisstatus)_ | || ✓ | + + +#### AnalysisDefinition + + + +AnalysisDefinition is the Schema for the analysisdefinitions APIs + +_Appears in:_ +- [AnalysisDefinitionList](#analysisdefinitionlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1beta1` | | | +| `kind` _string_ | `AnalysisDefinition` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[AnalysisDefinitionSpec](#analysisdefinitionspec)_ | || ✓ | +| `status` _string_ | unused field || ✓ | + + +#### AnalysisDefinitionList + + + +AnalysisDefinitionList contains a list of AnalysisDefinition resources + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1beta1` | | | +| `kind` _string_ | `AnalysisDefinitionList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[AnalysisDefinition](#analysisdefinition) array_ | || x | + + +#### AnalysisDefinitionSpec + + + +AnalysisDefinitionSpec defines the desired state of AnalysisDefinition + +_Appears in:_ +- [AnalysisDefinition](#analysisdefinition) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `objectives` _[Objective](#objective) array_ | Objectives defines a list of objectives to evaluate for an analysis || ✓ | +| `totalScore` _[TotalScore](#totalscore)_ | TotalScore defines the required score for an analysis to be successful || x | + + +#### AnalysisList + + + +AnalysisList contains a list of Analysis resources + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1beta1` | | | +| `kind` _string_ | `AnalysisList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[Analysis](#analysis) array_ | || x | + + +#### AnalysisSpec + + + +AnalysisSpec defines the desired state of Analysis + +_Appears in:_ +- [Analysis](#analysis) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `timeframe` _[Timeframe](#timeframe)_ | Timeframe specifies the range for the corresponding query in the AnalysisValueTemplate. Please note that either a combination of 'from' and 'to' or the 'recent' property may be set. If neither is set, the Analysis can not be added to the cluster. || x | +| `args` _object (keys:string, values:string)_ | Args corresponds to a map of key/value pairs that can be used to substitute placeholders in the AnalysisValueTemplate query. i.e. for args foo:bar the query could be "query:percentile(95)?scope=tag(my_foo_label:{{.foo}})". || ✓ | +| `analysisDefinition` _[ObjectReference](#objectreference)_ | AnalysisDefinition refers to the AnalysisDefinition, a CRD that stores the AnalysisValuesTemplates || x | + + +#### AnalysisState + +_Underlying type:_ _string_ + +AnalysisState represents the state of the analysis + +_Appears in:_ +- [AnalysisStatus](#analysisstatus) + + + +#### AnalysisStatus + + + +AnalysisStatus stores the status of the overall analysis returns also pass or warnings + +_Appears in:_ +- [Analysis](#analysis) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `timeframe` _[Timeframe](#timeframe)_ | Timeframe describes the time frame which is evaluated by the Analysis || x | +| `raw` _string_ | Raw contains the raw result of the SLO computation || ✓ | +| `pass` _boolean_ | Pass returns whether the SLO is satisfied || ✓ | +| `warning` _boolean_ | Warning returns whether the analysis returned a warning || ✓ | +| `state` _string_ | State describes the current state of the Analysis (Pending/Progressing/Completed) || x | +| `storedValues` _object (keys:string, values:[ProviderResult](#providerresult))_ | StoredValues contains all analysis values that have already been retrieved successfully || ✓ | + + +#### AnalysisValueTemplate + + + +AnalysisValueTemplate is the Schema for the analysisvaluetemplates API + +_Appears in:_ +- [AnalysisValueTemplateList](#analysisvaluetemplatelist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1beta1` | | | +| `kind` _string_ | `AnalysisValueTemplate` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[AnalysisValueTemplateSpec](#analysisvaluetemplatespec)_ | Spec contains the specification for the AnalysisValueTemplate || ✓ | +| `status` _string_ | unused field || ✓ | + + +#### AnalysisValueTemplateList + + + +AnalysisValueTemplateList contains a list of AnalysisValueTemplate resources + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1beta1` | | | +| `kind` _string_ | `AnalysisValueTemplateList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[AnalysisValueTemplate](#analysisvaluetemplate) array_ | || x | + + +#### AnalysisValueTemplateSpec + + + +AnalysisValueTemplateSpec defines the desired state of AnalysisValueTemplate + +_Appears in:_ +- [AnalysisValueTemplate](#analysisvaluetemplate) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `provider` _[ObjectReference](#objectreference)_ | Provider refers to the KeptnMetricsProvider which should be used to retrieve the data || x | +| `query` _string_ | Query represents the query to be run. It can include placeholders that are defined using the go template syntax. More info on go templating - https://pkg.go.dev/text/template || x | + + +#### IntervalResult + + + + + +_Appears in:_ +- [KeptnMetricStatus](#keptnmetricstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `value` _string_ | Value represents the resulting value || x | +| `range` _[RangeSpec](#rangespec)_ | Range represents the time range for which this data was queried || x | +| `lastUpdated` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | LastUpdated represents the time when the status data was last updated || x | +| `errMsg` _string_ | ErrMsg represents the error details when the query could not be evaluated || ✓ | + + +#### KeptnMetric + + + +KeptnMetric is the Schema for the keptnmetrics API + +_Appears in:_ +- [KeptnMetricList](#keptnmetriclist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1beta1` | | | +| `kind` _string_ | `KeptnMetric` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnMetricSpec](#keptnmetricspec)_ | || ✓ | +| `status` _[KeptnMetricStatus](#keptnmetricstatus)_ | || ✓ | + + +#### KeptnMetricList + + + +KeptnMetricList contains a list of KeptnMetric resources + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1beta1` | | | +| `kind` _string_ | `KeptnMetricList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnMetric](#keptnmetric) array_ | || x | + + +#### KeptnMetricSpec + + + +KeptnMetricSpec defines the desired state of KeptnMetric + +_Appears in:_ +- [KeptnMetric](#keptnmetric) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `provider` _[ProviderRef](#providerref)_ | Provider represents the provider object || x | +| `query` _string_ | Query represents the query to be run || x | +| `fetchIntervalSeconds` _integer_ | FetchIntervalSeconds represents the update frequency in seconds that is used to update the metric || x | +| `range` _[RangeSpec](#rangespec)_ | Range represents the time range for which data is to be queried || ✓ | + + +#### KeptnMetricStatus + + + +KeptnMetricStatus defines the observed state of KeptnMetric + +_Appears in:_ +- [KeptnMetric](#keptnmetric) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `value` _string_ | Value represents the resulting value || ✓ | +| `rawValue` _integer array_ | RawValue represents the resulting value in raw format || ✓ | +| `lastUpdated` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | LastUpdated represents the time when the status data was last updated || ✓ | +| `errMsg` _string_ | ErrMsg represents the error details when the query could not be evaluated || ✓ | +| `intervalResults` _[IntervalResult](#intervalresult) array_ | IntervalResults contain a slice of all the interval results || ✓ | + + +#### KeptnMetricsProvider + + + +KeptnMetricsProvider is the Schema for the keptnmetricsproviders API + +_Appears in:_ +- [KeptnMetricsProviderList](#keptnmetricsproviderlist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1beta1` | | | +| `kind` _string_ | `KeptnMetricsProvider` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnMetricsProviderSpec](#keptnmetricsproviderspec)_ | || ✓ | +| `status` _string_ | unused field || ✓ | + + +#### KeptnMetricsProviderList + + + +KeptnMetricsProviderList contains a list of KeptnMetricsProvider resources + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `metrics.keptn.sh/v1beta1` | | | +| `kind` _string_ | `KeptnMetricsProviderList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnMetricsProvider](#keptnmetricsprovider) array_ | || x | + + +#### KeptnMetricsProviderSpec + + + +KeptnMetricsProviderSpec defines the desired state of KeptnMetricsProvider + +_Appears in:_ +- [KeptnMetricsProvider](#keptnmetricsprovider) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `type` _string_ | Type represents the provider type. This can be one of prometheus, dynatrace, datadog, dql. || x | +| `targetServer` _string_ | TargetServer defines URL (including port and protocol) at which the metrics provider is reachable. || x | +| `secretKeyRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#secretkeyselector-v1-core)_ | SecretKeyRef defines an optional secret for access credentials to the metrics provider. || ✓ | + + +#### ObjectReference + + + + + +_Appears in:_ +- [AnalysisSpec](#analysisspec) +- [AnalysisValueTemplateSpec](#analysisvaluetemplatespec) +- [Objective](#objective) +- [ProviderResult](#providerresult) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | Name defines the name of the referenced object || x | +| `namespace` _string_ | Namespace defines the namespace of the referenced object || ✓ | + + +#### Objective + + + +Objective defines an objective for analysis + +_Appears in:_ +- [AnalysisDefinitionSpec](#analysisdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `analysisValueTemplateRef` _[ObjectReference](#objectreference)_ | AnalysisValueTemplateRef refers to the appropriate AnalysisValueTemplate || x | +| `target` _[Target](#target)_ | Target defines failure or warning criteria || ✓ | +| `weight` _integer_ | Weight can be used to emphasize the importance of one Objective over the others |1| ✓ | +| `keyObjective` _boolean_ | KeyObjective defines whether the whole analysis fails when this objective's target is not met |false| ✓ | + + +#### Operator + + + +Operator specifies the supported operators for value comparisons + +_Appears in:_ +- [Target](#target) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `lessThanOrEqual` _[OperatorValue](#operatorvalue)_ | LessThanOrEqual represents '<=' operator || ✓ | +| `lessThan` _[OperatorValue](#operatorvalue)_ | LessThan represents '<' operator || ✓ | +| `greaterThan` _[OperatorValue](#operatorvalue)_ | GreaterThan represents '>' operator || ✓ | +| `greaterThanOrEqual` _[OperatorValue](#operatorvalue)_ | GreaterThanOrEqual represents '>=' operator || ✓ | +| `equalTo` _[OperatorValue](#operatorvalue)_ | EqualTo represents '==' operator || ✓ | +| `inRange` _[RangeValue](#rangevalue)_ | InRange represents operator checking the value is inclusively in the defined range, e.g. 2 <= x <= 5 || ✓ | +| `notInRange` _[RangeValue](#rangevalue)_ | NotInRange represents operator checking the value is exclusively out of the defined range, e.g. x < 2 AND x > 5 || ✓ | + + +#### OperatorValue + + + +OperatorValue represents the value to which the result is compared + +_Appears in:_ +- [Operator](#operator) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `fixedValue` _[Quantity](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity)_ | FixedValue defines the value for comparison || x | + + +#### ProviderRef + + + +ProviderRef represents the provider object + +_Appears in:_ +- [KeptnMetricSpec](#keptnmetricspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `name` _string_ | Name of the provider || x | + + +#### ProviderResult + + + +ProviderResult stores reference of already collected provider query associated to its objective template + +_Appears in:_ +- [AnalysisStatus](#analysisstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `objectiveReference` _[ObjectReference](#objectreference)_ | Objective store reference to corresponding objective template || ✓ | +| `query` _string_ | Query represents the executed query || ✓ | +| `value` _string_ | Value is the value the provider returned || ✓ | +| `errMsg` _string_ | ErrMsg stores any possible error at retrieval time || ✓ | + + +#### RangeSpec + + + +RangeSpec defines the time range for which data is to be queried + +_Appears in:_ +- [IntervalResult](#intervalresult) +- [KeptnMetricSpec](#keptnmetricspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `interval` _string_ | Interval specifies the duration of the time interval for the data query |5m| ✓ | +| `step` _string_ | Step represents the query resolution step width for the data query || ✓ | +| `aggregation` _string_ | Aggregation defines the type of aggregation function to be applied on the data. Accepted values: p90, p95, p99, max, min, avg, median || ✓ | +| `storedResults` _integer_ | StoredResults indicates the upper limit of how many past results should be stored in the status of a KeptnMetric || ✓ | + + +#### RangeValue + + + +RangeValue represents a range which the value should fit + +_Appears in:_ +- [Operator](#operator) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `lowBound` _[Quantity](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity)_ | LowBound defines the lower bound of the range || x | +| `highBound` _[Quantity](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity)_ | HighBound defines the higher bound of the range || x | + + +#### Target + + + +Target defines the failure and warning criteria + +_Appears in:_ +- [Objective](#objective) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `failure` _[Operator](#operator)_ | Failure defines limits up to which an analysis fails || ✓ | +| `warning` _[Operator](#operator)_ | Warning defines limits where the result does not pass or fail || ✓ | + + +#### Timeframe + + + + + +_Appears in:_ +- [AnalysisSpec](#analysisspec) +- [AnalysisStatus](#analysisstatus) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `from` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | From is the time of start for the query. This field follows RFC3339 time format || ✓ | +| `to` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | To is the time of end for the query. This field follows RFC3339 time format || ✓ | +| `recent` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | Recent describes a recent timeframe using a duration string. E.g. Setting this to '5m' provides an Analysis for the last five minutes || ✓ | + + +#### TotalScore + + + +TotalScore defines the required score for an analysis to be successful + +_Appears in:_ +- [AnalysisDefinitionSpec](#analysisdefinitionspec) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `passPercentage` _integer_ | PassPercentage defines the threshold to reach for an analysis to pass || x | +| `warningPercentage` _integer_ | WarningPercentage defines the threshold to reach for an analysis to pass with a 'warning' status || x | + + diff --git a/docs-new/docs/reference/api-reference/options/index.md b/docs-new/docs/reference/api-reference/options/index.md new file mode 100644 index 0000000000..dc10a25622 --- /dev/null +++ b/docs-new/docs/reference/api-reference/options/index.md @@ -0,0 +1 @@ +# Options API diff --git a/docs-new/docs/reference/api-reference/options/v1alpha1/index.md b/docs-new/docs/reference/api-reference/options/v1alpha1/index.md new file mode 100644 index 0000000000..bb3bea5473 --- /dev/null +++ b/docs-new/docs/reference/api-reference/options/v1alpha1/index.md @@ -0,0 +1,67 @@ +# v1alpha1 + + +## Packages +- [options.keptn.sh/v1alpha1](#optionskeptnshv1alpha1) + + +## options.keptn.sh/v1alpha1 + +Package v1alpha1 contains API Schema definitions for the options v1alpha1 API group + +### Resource Types +- [KeptnConfig](#keptnconfig) +- [KeptnConfigList](#keptnconfiglist) + + + +#### KeptnConfig + + + +KeptnConfig is the Schema for the keptnconfigs API + +_Appears in:_ +- [KeptnConfigList](#keptnconfiglist) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `options.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnConfig` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `spec` _[KeptnConfigSpec](#keptnconfigspec)_ | || ✓ | +| `status` _string_ | unused field || ✓ | + + +#### KeptnConfigList + + + +KeptnConfigList contains a list of KeptnConfig + + + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `options.keptn.sh/v1alpha1` | | | +| `kind` _string_ | `KeptnConfigList` | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. || ✓ | +| `items` _[KeptnConfig](#keptnconfig) array_ | || x | + + +#### KeptnConfigSpec + + + +KeptnConfigSpec defines the desired state of KeptnConfig + +_Appears in:_ +- [KeptnConfig](#keptnconfig) + +| Field | Description | Default | Optional | +| --- | --- | --- | --- | +| `OTelCollectorUrl` _string_ | OTelCollectorUrl can be used to set the Open Telemetry collector that the lifecycle operator should use || ✓ | +| `keptnAppCreationRequestTimeoutSeconds` _integer_ | KeptnAppCreationRequestTimeoutSeconds is used to set the interval in which automatic app discovery searches for workload to put into the same auto-generated KeptnApp |30| ✓ | +| `cloudEventsEndpoint` _string_ | CloudEventsEndpoint can be used to set the endpoint where Cloud Events should be posted by the lifecycle operator || ✓ | + + diff --git a/docs-new/docs/reference/crd-reference/analysis.md b/docs-new/docs/reference/crd-reference/analysis.md new file mode 100644 index 0000000000..deeec55ac5 --- /dev/null +++ b/docs-new/docs/reference/crd-reference/analysis.md @@ -0,0 +1,353 @@ +# Analysis + +An `Analysis` resource customizes the templates +that are defined in an +[AnalysisDefinition](analysisdefinition.md) resource +by identifying the time for which the analysis should be done +and the appropriate values to use for variables +that are used in the `AnalysisDefinition` query. + +## Synopsis + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: Analysis +metadata: + name: analysis-sample +spec: + timeframe: from: to: | `recent ` + args: + : + : + ... + analysisDefinition: + name: + state: Completed | Progressing +``` + +## Fields + +* **apiVersion** -- API version being used +* **kind** -- Resource type. + Must be set to `Analysis` +* **metadata** + * **name** -- Unique name of this analysis. + 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** + * **timeframe** (required) -- Specifies the range for the corresponding query + in the AnalysisValueTemplate. + This can be populated as one of the following: + + * A combination of ‘from’ and ’to’ + to specify the start and stop times for the analysis. + These fields follow the + [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) + timestamp format. + * Set the ‘recent’ property to a time span. + This causes the Analysis to use data going back that amount of time. + For example, if `recent: 10m` is set, + the Analysis studies data from the last ten minutes. + If neither is set, the Analysis can not be added to the cluster. + * **args** -- Map of key/value pairs that can be used + to substitute variables in the `AnalysisValueTemplate` query. + * **analysisDefinition** (required) -- Identify the `AnalysisDefinition` resource + that stores the `AnalysisValuesTemplate` associated with this `Analysis` + * **name** -- Name of the `AnalysisDefinition` resource + * **namespace** (optional) -- + Namespace of the `AnalysisDefinition` resource. + The `AnalysisDefinition` resource can be located in any namespace. + If the namespace is not specified, + the analysis controller looks for the `AnalysisDefinition` resource + in the same namespace as the `Analysis` resource. + * **status** -- results of this Analysis run, + added to the resource by Keptn, + based on criteria defined in the `AnalysisDefinition` resource. + + * **warning** -- Whether the analysis returned a warning. + * **raw** -- String-encoded JSON object that reports the results + of evaluating one or more objectives or metrics. + See + [Interpreting Analysis results](#interpreting-analysis-results) + for details. + * **state** -- Set to `Completed` or `Progressing` as appropriate. + +## Interpreting Analysis results + +The `status.raw` field is a string encoded JSON object object that represents the +results of evaluating one or more performance objectives or metrics. +It shows whether these objectives have passed or failed, their actual values, and the associated scores. +In this example, the objectives include response time and error rate analysis, +each with its own criteria for passing or failing. +The overall evaluation has passed, and no warnings have been issued. + +```json +{ + "objectiveResults": [ + { + "result": { + "failResult": { + "operator": { + "greaterThan": { + "fixedValue": "500m" + } + }, + "fulfilled": false + }, + "warnResult": { + "operator": { + "greaterThan": { + "fixedValue": "300m" + } + }, + "fulfilled": false + }, + "warning": false, + "pass": true + }, + "objective": { + "analysisValueTemplateRef": { + "name": "response-time-p95" + }, + "target": { + "failure": { + "greaterThan": { + "fixedValue": "500m" + } + }, + "warning": { + "greaterThan": { + "fixedValue": "300m" + } + } + }, + "weight": 1 + }, + "value": 0.00475, + "score": 1 + }, + { + "result": { + "failResult": { + "operator": { + "greaterThan": { + "fixedValue": "0" + } + }, + "fulfilled": false + }, + "warnResult": { + "operator": { + + }, + "fulfilled": false + }, + "warning": false, + "pass": true + }, + "objective": { + "analysisValueTemplateRef": { + "name": "error-rate" + }, + "target": { + "failure": { + "greaterThan": { + "fixedValue": "0" + } + } + }, + "weight": 1, + "keyObjective": true + }, + "value": 0, + "score": 1 + } + ], + "totalScore": 2, + "maximumScore": 2, + "pass": true, + "warning": false +} +``` + +The meaning of each of these properties is as follows: + +**`objectiveResults`**: This is an array containing one or more objects, +each representing the results of a specific objective or performance metric. + +* The first item in the array: + * **`result`** -- This object contains information + about whether the objective has passed or failed. + It has two sub-objects: + * **`failResult`** -- Indicates whether the objective has failed. + In this case, it checks if a value is greater than 500 milliseconds + and it has not been fulfilled (`fulfilled: false`). + * **`warnResult`** -- Indicates whether the objective has issued a warning. + It checks if a value is greater than 300 milliseconds + and it has not been fulfilled (`fulfilled: false`). + + - **`warning`** -- Indicates whether a warning has been issued + (false in this case). + * **`pass`** -- Indicates whether the objective has passed + (true in this case). + * **`objective`** -- Describes the objective being evaluated. + It includes: + * **`analysisValueTemplateRef`** -- Refers to the template + used for analysis (`response-time-p95`). + * **`target`** -- Sets the target values for failure and warning conditions. + In this case, failure occurs + if the value is greater than 500 milliseconds + and warning occurs if it's greater than 300 milliseconds. + * **`weight`** -- Specifies the weight assigned to this objective + (weight: 1). + * **`value`** -- Indicates the actual value measured for this objective + (value: 0.00475). + * **`score`** -- Indicates the score assigned to this objective (score: 1). + +* The second item in the array: + * **`result`** -- Similar to the first objective, + it checks whether a value is greater than 0 and has not been fulfilled + (`fulfilled: false`). + There are no warning conditions in this case. + * **`objective`** -- Describes the objective related to error rate analysis. + * **`analysisValueTemplateRef`** -- Refers to the template + used for analysis (`error-rate`). + * **`target`** -- Sets the target value for failure + (failure occurs if the value is greater than 0). + * **`weight`** -- Specifies the weight assigned to this objective + (weight: 1). + * **`keyObjective`** -- Indicates that this is a key objective (true). + + * **`value`** -- Indicates the actual value measured for this objective + (value: 0). + * **`score`** -- Indicates the score assigned to this objective (score: 1). + +* The second item in the array: + * **`result`** -- Similar to the first objective, + it checks whether a value is greater than 0 and has not been fulfilled + (`fulfilled: false`). + There are no warning conditions in this case. + * **`objective`** -- Describes the objective related to error rate analysis. + * **`analysisValueTemplateRef`** -- Refers to the template + used for analysis (`error-rate`). + * **`target`** -- Sets the target value for failure + (failure occurs if the value is greater than 0). + * **`weight`** -- Specifies the weight assigned to this objective + (weight: 1). + * **`keyObjective`** -- Indicates that this is a key objective (true). + + * **`value`** -- Indicates the actual value measured for this objective + (value: 0). + * **`score`** -- Indicates the score assigned to this objective (score: 1). + +**`totalScore`** -- Represents the total score achieved +based on the objectives evaluated (totalScore: 2). + +**`maximumScore`** -- Indicates the maximum possible score (maximumScore: 2). + +**`pass`** -- Indicates whether the overall evaluation has passed +(true in this case). + +**`warning`** -- Indicates whether any warnings have been issued +during the evaluation (false in this case). + +## Usage + +An `Analysis` resource specifies a single Analysis run. +It specifies the `AnalysisValueTemplate` resource +that defines the calculations to use, +the timeframe for which to report information, +and values to use for variables for this run. + +The result of this analysis stays in the cluster +until the `Analysis` is deleted. +That also means that, if another analysis should be performed, +the new analysis must be given a new, unique name within the namespace. + +To perform an Analysis (or "trigger an evaluation" in Keptn v1 jargon), +apply the `analysis-instance.yaml` file: + +```shell +kubectl apply -f analysis-instance.yaml -n keptn-lifecycle-poc +``` + +Retrieve the current status of the Analysis with the following command: + +```shell +kubectl get analysis - n keptn-lifecycle-poc +``` + +This yields an output that looks like the following: + +```shell +NAME ANALYSISDEFINITION WARNING PASS +analysis-sample-1 my-project-ad true +``` + +This shows that the analysis passed successfully. + +To get the detailed result of the evaluation, +use the `-oyaml` argument to inspect the full state of the analysis: + +This displays the `Analysis` resource +with the definition of the analysis +as well as the `status` (results) of the analysis; for example: + +```shell +kubectl get analysis - n keptn-lifecycle-poc -oyaml +``` + +## Examples + +{% include "../../assets/crd/analysis.yaml" %} + +This `Analysis` resource: + +* Defines the `timeframe` for which the analysis is done + as between 5 am and 10 am on the 5th of May 2023 +* Adds a few specific key-value pairs that will be substituted in the query. + For instance, the query could contain the `{{.nodename}}` variable. + The value of the `args.nodename` field (`test`) + will be substituted for this string. + +For a full example of how to implement the Keptn Analysis feature, see the +[Analysis](../../guides/slo.md) +guide page. + +## Files + +API reference: [Analysis](../api-reference/metrics/v1beta1/index.md#analysis) + +## Differences between versions + +Keptn v0.8.3 and v0.9.0 include a preliminary release +of the Keptn Analysis feature +but it is hidden behind a feature flag. +To preview these features, do one of the following for your Keptn cluster: + +* Set the environment variable `ENABLE_ANALYSIS` to `true` + in the `metrics-operator` deployment +* Add the following to your `helm upgrade` command line: + + ```shell + --set metricsOperator.env.enableKeptnAnalysis=true + ``` +* Set `enableKeptnAnalysis: "true"` in the + [keptn-metrics-operator/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-metrics-operator/values.yaml) + file + +See +[Customizing the configuration of components](../../installation/index.md#customizing-the-configuration-of-components) +for more information. + +## See also + +* [AnalysisDefinition](analysisdefinition.md) +* [AnalysisValueTemplate](analysisvaluetemplate.md) +* [Analysis](../../guides/slo.md) guide diff --git a/docs-new/docs/reference/crd-reference/analysisdefinition.md b/docs-new/docs/reference/crd-reference/analysisdefinition.md new file mode 100644 index 0000000000..f2e189a232 --- /dev/null +++ b/docs-new/docs/reference/crd-reference/analysisdefinition.md @@ -0,0 +1,169 @@ +# AnalysisDefinition + +An `AnalysisDefinition` resource defines the +list of Service Level Objectives (SLOs) for an `Analysis`. + +## Synopsis + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: AnalysisDefinition +metadata: + name: + namespace: +spec: + objectives: + - analysisValueTemplateRef: + name: + namespace: + target: + failure | warning: + : + : | + : + lowbound: + highBound: + weight: + keyObjective: + totalScore: + passPercentage: 90 + warningPercentage: 75 +``` + +## Fields + +* **apiVersion** -- API version being used +* **kind** -- Resource type. + Must be set to `AnalysisDefinition`. +* **metadata** + * **name** -- Unique name of this analysis definition. + Names must comply with the + [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) + specification. + * **namespace** -- Namespace where this resource is located. + `Analysis` resources must specify this namespace + when referencing this definition, + unless it resides in the same namespace as the `Analysis` resource. +* **spec** + * **objectives** + This is a list of objectives whose results are combined + to determine whether the analysis fails, passes, or passes with a warning. + * **analysisValueTemplateRef** (required) -- + This string marks the beginning of each objective + * **name** (required) -- The `metadata.name` value of the + [AnalysisDefinition](analysisdefinition.md) + resource used for this objective. + That resource defines the data provider and the query to use. + * **namespace** -- + Namespace of the `analysisValueTemplateRef` resource. + If the namespace is not specified, + the analysis controller looks for the `AnalysisValueTemplateRef` resource + in the same namespace as the `Analysis` resource. + * **target** -- defines failure or, optionally, warning criteria. + Values not specified for failure or warning result in a pass. + Keptn writes the results of the analysis to the `status` section + of the + [Analysis](analysis.md) + resource after the analysis runs. + * **failure** -- criteria for failure, specified as + `operator: `. + This can be specified either as an absolute value + or as a range of values. + + Valid operators for absolute values are: + * `lessThan` -- `<` operator + * `lessThanOrEqual` -- `<=` operator + * `greaterThan` -- `>` operator + * `greaterThanOrEqual` -- `>=` operator + * `equalTo` -- `==` operator + + Valid operators for specifying ranges are: + * `inRange` -- value is inclusively in the defined range + * `notInRange` -- value is exclusively out of the defined range + + Each of these operators require two arguments: + + * `lowBound` -- minimum value of the range included or excluded + * `highBound` -- maximum value of the range included or excluded + + * **warning** -- criteria for a warning, + specified in the same way as the `failure` field. + * **weight** -- used to emphasize the importance + of one `objective` over others + * **keyObjective** -- If set to `true`, + the entire analysis fails if this objective fails + * **totalScore** (required) -- + * **passPercentage** -- threshold to reach for the full analysis + (all objectives) to pass + + * **warningPercentage** -- threshold to reach + for the full analysis (all objectives) to pass with `warning` status + +## Usage + +An `AnalysisDefinition` resource contains a list of objectives to satisfy. +Each of these objectives must specify: + +* Failure or warning target criteria +* Whether the objective is a key objective + meaning that its failure fails the Analysis +* Weight of the objective on the overall Analysis +* The `AnalysisValueTemplate` resource that contains the SLIs, + defining the data provider from which to gather the data + and how to compute the Analysis + +## Example + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: AnalysisDefinition +metadata: + name: ed-my-proj-dev-svc1 + namespace: keptn-system +spec: + objectives: + - analysisValueTemplateRef: + name: response-time-p95 + namespace: keptn-system + target: + failure: + : + fixedValue: integer> | + inRange: | notInRange: + lowBound: + highBound: + warning: + : + fixedValue: integer> | + inRange: | notInRange: + lowBound: + highBound: + weight: + keyObjective: + totalScore: + passPercentage: + warningPercentage: +``` + +For an example of how to implement the Keptn Analysis feature, see the +[Analysis](../../guides/slo.md) +guide page. + +## Files + +API reference: +[AnalysisDefinition](../api-reference/metrics/v1beta1/index.md#analysisdefinition) + +## Differences between versions + +A preliminary release of the Keptn Analysis feature +is included in Keptn v0.8.3 and v0.9.0 but is hidden behind a feature flag. +See the +[Analysis](analysis.md/#differences-between-versions) +reference page for instructions to activate the preview of this feature. + +## See also + +* [Analysis](analysis.md) +* [AnalysisValueTemplate](analysisvaluetemplate.md) +* [Analysis](../../guides/slo.md) guide diff --git a/docs-new/docs/reference/crd-reference/analysisvaluetemplate.md b/docs-new/docs/reference/crd-reference/analysisvaluetemplate.md new file mode 100644 index 0000000000..04c70ddcf2 --- /dev/null +++ b/docs-new/docs/reference/crd-reference/analysisvaluetemplate.md @@ -0,0 +1,107 @@ +# AnalysisValueTemplate + +An `AnalysisValueTemplate` resource +defines a Service Level Indicator (SLI), +which identifies the data to be analyzed +by data source to use and the query to issue. +One Analysis can use data from multiple instances +of multiple types of data provider. + +## Synopsis + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: AnalysisValueTemplate +metadata: + name: response-time-p95 + namespace: +spec: + provider: + name: prometheus | dynatrace | dql | datadog + query: +``` + +## Fields + +* **apiVersion** -- API version being used +* **kind** -- Resource type. + Must be set to `AnalysisValueTemplate` +* **metadata** + * **labels** -- The Analysis feature uses the + `name` and `part-of` labels that are discussed in + [Basic annotations](../../guides/integrate.md#basic-annotations) + plus the following: + * **app.kubernetes.io/instance** analysis-sample + * **app.kubernetes.io/managed-by** -- Tool used to manage + the operation of the application. + Valid values are `helm` and `kustomize`. + * **app.kubernetes.io/created-by** metrics-operator + + TODO: Need to clarify how to use these annotations + * **name** -- Unique name of this template. + Names must comply with the + [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) + specification. + * **namespace** (optional) -- Namespace where this template lives. + `Analysis` resources must specify this namespace + when referencing this definition, + unless it resides in the same namespace as the `Analysis` resource. +* **spec** + * **provider** (required) -- the KeptnMetricProvider + * **name** -- The `spec.name` value of the + [KeptnMetricsProvider](metricsprovider.md) resource to use. + Note that each `AnalysisValueTemplate` resource + can use only one data source. + However, an `Analysis` resource + can use multiple `AnalysisValueTemplate` resources, + each of which uses a different data source. + * **query** (required) -- query to be made. + This is done in the data provider's query language. + It can include variables that use the go templating syntax + to insert a placeholder in the query. + For example, the query might include `{{.nodename}}'}`; + the value to substitute for that variable for this Analysis + is defined in the `spec.args` section of the `AnalysisTemplate` resource, + which might be set to `nodename: test`. + +## Usage + +You must define a +[KeptnMetricsProvider](metricsprovider.md) +for each instance of each data provider you are using. +The `AnalysisValueTemplate` refers to that provider and queries it. + +One `Analysis` can use data from multiple instances +of multiple types of data provider; +you must define a +[KeptnMetricsProvider](metricsprovider.md) +resource for each instance of each data provider you are using. +The template refers to that provider and queries it. + +## Example + +{% include "../../assets/crd/analysis-template.yaml" %} + +For a full example of how the `AnalysisValueTemplate` is used +to implement the Keptn Analysis feature, see the +[Analysis](../../guides/slo.md) +guide page. + +## Files + +API reference: +[AnalysisValueTemplate](../api-reference/metrics/v1beta1/index.md#analysisvaluetemplate) + +## Differences between versions + +A preliminary release of the Keptn Analysis feature +is included in Keptn v0.8.3 and v0.9.0 but is hidden behind a feature flag. +See the +[Analysis](analysis.md#differences-between-versions) +reference page for instructions to activate the preview of this feature. + +## See also + +* [Analysis](analysis.md) +* [AnalysisDefinition](analysisdefinition.md) +* [Analysis](../../guides/slo.md) guide diff --git a/docs-new/docs/reference/crd-reference/app.md b/docs-new/docs/reference/crd-reference/app.md new file mode 100644 index 0000000000..a51bba59ee --- /dev/null +++ b/docs-new/docs/reference/crd-reference/app.md @@ -0,0 +1,174 @@ +# KeptnApp + +A `KeptnApp` resource lists all the [workloads](https://kubernetes.io/docs/concepts/workloads/) +that constitute a logical application. +It contains information about: + +- All [workloads](https://kubernetes.io/docs/concepts/workloads/) and checks + that are associated with a Keptn application +- A list of tasks and evaluations to be executed + pre- and post-deployment. +- Tasks referenced by `KeptnApp` are defined in a + [KeptnTaskDefinition](taskdefinition.md) resource. + `KeptnApp` identifies the task by the value of the `metadata.name` field + and does not need to understand what runner is used to define the task. + +## Synopsis + +```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 + +The first set of fields are created automatically +when the app discovery feature generates the `KeptnApp` resource: + +- **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** (required) -- 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](../../guides/restart-application-deployment.md) + for a longer discussion of this. + - **workloads** + - **name** (required) -- 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](https://kubernetes.io/docs/concepts/workloads/) + associated with this Keptn application. + - **version** (required) -- version number for this [workload](https://kubernetes.io/docs/concepts/workloads/). + Changing this number causes a new execution + of checks for this [workload](https://kubernetes.io/docs/concepts/workloads/) 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](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](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](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](evaluationdefinition.md) + resource. + +## Usage + +Kubernetes defines +[workloads](https://kubernetes.io/docs/concepts/workloads/) +but does not define applications. +Keptn adds the concept of applications +defined as a set of workloads that can be executed. +A `KeptnApp` resource is added +into the repository of the deployment engine +(ArgoCD, Flux, etc.) +and is then deployed by that deployment engine. + +A `KeptnApp` resource is created automatically, using the +[automatic application discovery](../../guides/auto-app-discovery.md) +feature to generate a `KeptnApp` resource +based on the +[basic annotations](../../guides/integrate.md#basic-annotations) +that are applied to any of the workload resources. +This allows you to use the Keptn observability features for existing resources +without manually populating any Keptn related resources. + +The release lifecycle management feature +allows you to define pre- and post-deployment +evaluations and tasks to be run for the `KeptnApp` as a whole. +These must be added to the `KeptnApp` manifest manually. +Note that all evaluations or tasks for a specific stage +(such as `preDeploymentTasks`) +are executed in parallel. +If you have a series of tasks that should be executed sequentially, +you can code them all into a single `KeptnTaskDefinition`. + +## 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 +``` + +## Files + +## Differences between versions + +- The `spec.revision` field is introduced in v1alpha2. + +## See also + +- [KeptnTaskDefinition](taskdefinition.md) +- [KeptnEvaluationDefinition](evaluationdefinition.md) +- [Working with tasks](../../guides/tasks.md) +- [Architecture of KeptnWorkloads and KeptnTasks](../../components/lifecycle-operator/keptn-apps.md) +- [Pre- and post-deployment tasks](../../guides/integrate.md#pre--and-post-deployment-checks) +- [Orchestrate deployment checks](../../core-concepts/usecase-orchestrate.md) +- [Use Keptn automatic app discovery](../../guides/auto-app-discovery.md) +- [Restart an Application Deployment](../../guides/restart-application-deployment.md) diff --git a/docs-new/docs/reference/crd-reference/config.md b/docs-new/docs/reference/crd-reference/config.md new file mode 100644 index 0000000000..e20c7dbbd0 --- /dev/null +++ b/docs-new/docs/reference/crd-reference/config.md @@ -0,0 +1,76 @@ +# KeptnConfig + +`KeptnConfig` defines Keptn configuration values. + +## Yaml Synopsis + +```yaml +apiVersion: options.keptn.sh/v?alpha? +kind: KeptnConfig +metadata: + name: +spec: + OTelCollectorUrl: '' + keptnAppCreationRequestTimeoutSeconds: <#-seconds> + cloudEventsEndpoint: +``` + +## Fields + +* **apiVersion** -- API version being used. +* **kind** -- Resource type. + Must be set to `KeptnConfig`. + +* **metadata** + * **name** -- Unique name of this set of configurations. + 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** + * **OTelCollectorUrl** -- The URL and port of the OpenTelemetry collector + This field must be populated + in order to export traces to the OpenTelemetry Collector. + * **keptnAppCreationRequestTimeoutSeconds** -- + Interval in which automatic app discovery searches for [workloads](https://kubernetes.io/docs/concepts/workloads/) + to put into the same auto-generated [KeptnApp](app.md). + The default value is 30 (seconds). + * **cloudEventsEndpoint** -- + Endpoint where the lifecycle operator posts Cloud Events. + +## Usage + +Each cluster should have a single `KeptnConfig` CRD +that describes all configurations for that cluster. + +## Example + +### OTel example + +This example specifies the URL of the OpenTelemetry collector +and that the automatic app discovery should be run every 40 seconds: + +```yaml +apiVersion: options.keptn.sh/v1alpha2 +kind: KeptnConfig +metadata: + name: keptn-config +spec: + OTelCollectorUrl: 'otel-collector:4317' + keptnAppCreationRequestTimeoutSeconds: 40 + cloudEventsEndpoint: 'http://endpoint.com' +``` + +## Files + +API Reference: + +* [KeptnTaskDefinition](../api-reference/lifecycle/v1alpha3/index.md#keptntaskdefinition) + +## Differences between versions + +## See also + +* [KeptnApp](./app.md) +* [OpenTelemetry observability](../../guides/otel.md) +* [Keptn automatic app discovery](../../guides/auto-app-discovery.md) diff --git a/docs-new/docs/reference/crd-reference/evaluationdefinition.md b/docs-new/docs/reference/crd-reference/evaluationdefinition.md new file mode 100644 index 0000000000..f82807e974 --- /dev/null +++ b/docs-new/docs/reference/crd-reference/evaluationdefinition.md @@ -0,0 +1,138 @@ +# KeptnEvaluationDefinition + +A `KeptnEvaluationDefinition` assigns target values +to [KeptnMetric](metric.md) queries. +These are used as part of evaluation tasks +that Keptn runs +as part of pre- and post-analysis phases of a [workload](https://kubernetes.io/docs/concepts/workloads/) or application. + +## Yaml Synopsis + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnEvaluationDefinition +metadata: + name: +spec: + objectives: + - evaluationTarget: "" + keptnMetricRef: + name: available-cpus + namespace: some-namespace +``` + +## Fields + +* **apiVersion** -- API version being used. + Must be `v1alpha3` or later for this syntax. +* **kind** -- Resource type. + Must be set to `KeptnEvaluationDefinition` + +* **metadata** + * **name** -- Unique name of this evaluation + such as `pre-deploy-eval` or `post-deploy-resource-eval`. + 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** + + * **objectives** (required) -- define the evaluations to be performed. + Each objective is expressed as a `keptnMetricRef` + and an `evaluationTarget` value. + + * **keptnMetricRef** (required) -- A reference to the + [KeptnMetric](metric.md) object + + * **name** (required) -- Name of the referenced + [KeptnMetric](metric.md) object + + * **namespace** -- Name of the referenced + [KeptnMetric](metric.md) object + + * **evaluationTarget** (required) -- Desired value of the query, + expressed as an arithmetic formula, + usually less than (`<`) or greater than (`>`) + This is used to define success or failure criteria + for the referenced `KeptnMetric` in order to pass or fail + the pre- and post-evaluation stages + +## Usage + +A `KeptnEvaluationDefinition` references one or more +[KeptnMetric](metric.md) resources. +When multiple `KeptnMetric`s are used, +Keptn considers the evaluation successful +if **all** metrics meet their `evaluationTarget`. + +The `KeptnMetric` resource and associated +[KeptnMetricsProvider](metricsprovider.md) +resource must be located in the same namespace +but the `KeptnEvaluationDefinition` resources +can reference metrics from any namespace in the cluster. +This means that you can create `KeptnMetricsProvider` +and `KeptnMetric` resources +in a centralized namespace (e.g. in `keptn-system`) +and use those metrics in evaluations +on all namespaces in the cluster. + +## Example + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnEvaluationDefinition +metadata: + name: my-prometheus-evaluation + namespace: example +spec: + source: prometheus + objectives: + - keptnMetricRef: + name: available-cpus + namespace: example + evaluationTarget: ">1" + - keptnMetricRef: + name: cpus-throttling + namespace: example + evaluationTarget: "<0.01" +``` + +## Files + +API Reference: + +## Differences between versions + +In the `v1alpha1` and `v1alpha2` API versions, +`KeptnEvaluationDefinition` referenced the `KeptnEvaluationProvider` CR +to identify the data source associated with this definition +and itself contained the queries +that are now taken from the specified [KeptnMetric](metric.md) CRD. +The synopsis was: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha2 +kind: KeptnEvaluationDefinition +metadata: + name: +spec: + source: prometheus | dynatrace | datadog + objectives: + - name: query-1 + query: "xxxx" + evaluationTarget: <20 + - name: query-2 + query: "yyyy" + evaluationTarget: >4 +``` + +Beginning with `v1alpha3` API version, +`KeptnEvaluationDefinition` references a `keptnMetricRef` +that points to a [KeptnMetric](metric.md) CR, +that defines the data source, the query and the namespace to use. +The `KeptnEvaluationDefinition` merely specifies the evaluation target. + +## See also + +* [KeptnMetricsProvider](metricsprovider.md) +* [KeptnMetric](metric.md) diff --git a/docs-new/docs/reference/crd-reference/index.md b/docs-new/docs/reference/crd-reference/index.md new file mode 100644 index 0000000000..988a2b55a8 --- /dev/null +++ b/docs-new/docs/reference/crd-reference/index.md @@ -0,0 +1,21 @@ +# CRD Reference + +This section provides comprehensive reference information about the +manifest files that must be populated for Keptn +[Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). + +Each CRD is an object of an API library. +In addition to the CRDs documented in this section, +Keptn populates many resources on its own. +For a comprehensive list of all Keptn resources, see +[API Reference](../api-reference/index.md). + +For more information about CRDs and APIs, see the Kubernetes documentation: + +* [API Overview](https://kubernetes.io/docs/reference/using-api/) + +* [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) + +* [API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning) + +* [Understanding Kubernetes Objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/) diff --git a/docs-new/docs/reference/crd-reference/metric.md b/docs-new/docs/reference/crd-reference/metric.md new file mode 100644 index 0000000000..fa30d9384f --- /dev/null +++ b/docs-new/docs/reference/crd-reference/metric.md @@ -0,0 +1,162 @@ +# KeptnMetric + +A `KeptnMetric` represents a metric that is collected from a provider. +Providing the metrics as a CR in a Kubernetes cluster +facilitates the reusability of this data across multiple components +and allows using multiple observability platforms +for different metrics at the same time. + +`KeptnMetric` CRs are also used as targets for +[EvaluationDefinition](evaluationdefinition.md) CRs. + +## Yaml Synopsis + +```yaml +apiVersion: metrics.keptn.sh/v1beta1 +kind: KeptnMetric +metadata: + name: + namespace: +spec: + provider: + name: "" + query: "" + fetchIntervalSeconds: <#-seconds> + range: + interval: "" + status: + properties: + value: + rawValue: + errMsg: + lastUpdated: