diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index 9c859e4acd..2337936cfa 100644 --- a/.github/actions/spelling/expect.txt +++ b/.github/actions/spelling/expect.txt @@ -568,7 +568,7 @@ stdouttrace storageclasses storageversion sts -subcharts +subchart subdir subjectaccessreviews substitue diff --git a/docs/content/en/contribute/docs/linter-requirements/_index.md b/docs/content/en/contribute/docs/linter-requirements/_index.md index 2ea8d4b754..4b2ede49f7 100644 --- a/docs/content/en/contribute/docs/linter-requirements/_index.md +++ b/docs/content/en/contribute/docs/linter-requirements/_index.md @@ -1,7 +1,7 @@ --- title: Linter Requirements description: To maintain optimal code quality, this project employs linters which require a specific IDE configuration for effective utilization. -weight: 400 +weight: 350 --- ## Linter Requirements diff --git a/docs/content/en/contribute/docs/local-building/_index.md b/docs/content/en/contribute/docs/local-building/_index.md index 73d360856a..2418e49d65 100644 --- a/docs/content/en/contribute/docs/local-building/_index.md +++ b/docs/content/en/contribute/docs/local-building/_index.md @@ -1,7 +1,7 @@ --- title: Build Documentation Locally description: This guide explains how to create a local version of the documentation -weight: 400 +weight: 300 --- ## Building the documentation locally diff --git a/docs/content/en/contribute/docs/spell-checker/_index.md b/docs/content/en/contribute/docs/spell-checker/_index.md new file mode 100644 index 0000000000..345d5aec5c --- /dev/null +++ b/docs/content/en/contribute/docs/spell-checker/_index.md @@ -0,0 +1,41 @@ +--- +title: Spell checker +description: How to work with the spell checker +weight: 375 +--- + +All PRs that are pushed to a Keptn repository +are run through a spell checker that is based on +[check-spelling](https://github.com/check-spelling/check-spelling) +Github action. + +Note, however, that you are still responsible for reading your text carefully. +The tool does not flag if you used a real word that is not the right word, +if you misuse "setup" versus "set up", and so forth. + +## Handling Spell Checker errors + +If you get a Spell Checker error: + +1. Right-click the `details` link for Spell Checker. +1. If you do not want to read through the whole (and rather verbose) log, + type `unrecognized words` in the search box at the top. +1. This shows the word(s) that caused Spell Checker to fail. + + - If these are genuine misspellings, + correct the spelling in your local branch + or using the github editor + and push the new commit to resolve the errors. + + - If a word that is flagged is a legitimate word, + follow the instructions in the report + to propose adding it to our dictionary. + This request will be added to your PR for review + and, if approved, will be merged when the PR is merged. + + - If your PR includes a file that should not be spell-checked, + you can add it to the + [excludes.txt](https://github.com/check-spelling/check-spelling/blob/main/.github/actions/spelling/excludes.txt) file + as part of your PR. + It will be reviewed and, if approved, + merged as part of your PR. diff --git a/docs/content/en/docs/install/tips-tricks.md b/docs/content/en/docs/install/tips-tricks.md new file mode 100644 index 0000000000..74a9900409 --- /dev/null +++ b/docs/content/en/docs/install/tips-tricks.md @@ -0,0 +1,152 @@ +--- +title: Installation Tips and Tricks +description: Supplemental installation information +weight: 38 +hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html +--- + +The +[Install Keptn](install.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/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn/values.yaml) +umbrella 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](install.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 + `keptn` as the value to the `NAME` option of the + [helm repo add](https://helm.sh/docs/helm/helm_repo_add/) + command whereas earlier releases used `klt`. + +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: + +```shell +helm repo add keptn https://charts.lifecycle.keptn.sh +helm repo update +helm search repo keptn +``` + +To install an older release, +specify the version with the chart `--version` flag +in the `helm update` command for the release you are installing. + +## Example configurations by use-case + +[Control what components are installed](install.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: + +{{< embed path="/docs/content/en/docs/install/assets/values-only-lifecycle.yaml" >}} + +Note that, if you want to run pre- and/or post-deployment +[evaluations](../implementing/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](../implementing/integrate.md). + +For more information about implementing Observability, see the +[Observability User Guide](../implementing/otel.md). + +For more information about implementing Keptn Release Lifecycle, see the +[Deployment tasks](../implementing/tasks.md) +and +[Evaluations](../implementing/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: + +{{< embed path="/docs/content/en/docs/install/assets/values-only-metrics.yaml" >}} + +For more information about implementing Metrics, see the +[Metrics User Guide](../implementing/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: + +{{< embed path="/docs/content/en/docs/install/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](../yaml-crd-ref/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](../implementing/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: + +{{< embed path="/docs/content/en/docs/install/assets/values-remove-certmanager.yaml" >}} + +For more information about using `cert-manager` with Keptn, see +[Use Keptn with cert-manager.io](../operate/cert-manager.md). diff --git a/docs/content/en/docs/intro/_index-bad.md b/docs/content/en/docs/intro/_index-bad.md new file mode 100644 index 0000000000..4b21ead863 --- /dev/null +++ b/docs/content/en/docs/intro/_index-bad.md @@ -0,0 +1,144 @@ +--- +title: Bad Introduction to Keptn +description: A bad copy of this file to play with spell-check +weight: 10 +--- + +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. + +One never knows how behaviours will be affected in a theatre. +You may need to make some adjustments manually. + +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](../implementing/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](https://lifecycle.keptn.sh/docs/yaml-crd-ref/app/) + resources (which connect logically related [workloads](https://kubernetes.io/docs/concepts/workloads/)) + using different deployment strategies. + +* Captures + [DORA metrics](../implementing/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](../implementing/dora.md) User Guide +* [OpenTelemetry observability](../implementing/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](../yaml-crd-ref/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](../implementing/tasks.md) User Guide +* [Evaluations](../implementing/evaluations.md) User Guide +* [Manage release lifecycle](usecase-orchestrate.md) +* [KeptnApp and KeptnWorkload resources](../architecture/keptn-apps.md)