From a5aa98a314ba2661d3d39379c7a9d84b60ed4e0c Mon Sep 17 00:00:00 2001 From: Moritz Wiesinger Date: Thu, 16 Nov 2023 15:07:51 +0100 Subject: [PATCH] chore: backport updated install page (#2517) --- .../content/en/docs/implementing/integrate.md | 4 +- .../assets/values-advance-changes.yaml | 6 +- .../assets/values-remove-certmanager.yaml | 4 - docs/content/en/docs/install/install.md | 347 +++++++----------- docs/content/en/docs/install/reqs.md | 35 +- .../en/docs/install/troubleshooting.md | 2 +- docs/content/en/docs/yaml-crd-ref/analysis.md | 2 +- 7 files changed, 162 insertions(+), 238 deletions(-) diff --git a/docs/content/en/docs/implementing/integrate.md b/docs/content/en/docs/implementing/integrate.md index 9d5d77416a..a13933a0b3 100644 --- a/docs/content/en/docs/implementing/integrate.md +++ b/docs/content/en/docs/implementing/integrate.md @@ -20,9 +20,7 @@ to identify the workloads of interest. To integrate Keptn with your applications: * You must first -[install](../install/install.md) -and -[enable](../install/install.md/#enable-keptn-lifecycle-operator-observability) +[install and enable](../install/install.md#basic-installation) Keptn. * Annotate or label your workloads with either Keptn or Kubernetes keys. diff --git a/docs/content/en/docs/install/assets/values-advance-changes.yaml b/docs/content/en/docs/install/assets/values-advance-changes.yaml index 9f5aff713b..7dfbcd8df1 100644 --- a/docs/content/en/docs/install/assets/values-advance-changes.yaml +++ b/docs/content/en/docs/install/assets/values-advance-changes.yaml @@ -1,5 +1,7 @@ global: - imageRegistry: "localhost:5000" # change all installed operator registry ex. metrics operator image will be localhost:5000/keptn/metrics-operator:v0.0.0 + # 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 @@ -10,5 +12,5 @@ lifecycleOperator: metricsOperator: enabled: true image: - tag: v0.0.0 # changes metrics operator image tag + tag: v0.0.0 # metrics operator will use this image tag imagePullPolicy: Never diff --git a/docs/content/en/docs/install/assets/values-remove-certmanager.yaml b/docs/content/en/docs/install/assets/values-remove-certmanager.yaml index 62954b99ef..83c6407c06 100644 --- a/docs/content/en/docs/install/assets/values-remove-certmanager.yaml +++ b/docs/content/en/docs/install/assets/values-remove-certmanager.yaml @@ -1,6 +1,2 @@ certManager: enabled: false -lifecycleOperator: - enabled: true -metricsOperator: - enabled: true diff --git a/docs/content/en/docs/install/install.md b/docs/content/en/docs/install/install.md index e68a00fd8c..716a6bb5b7 100644 --- a/docs/content/en/docs/install/install.md +++ b/docs/content/en/docs/install/install.md @@ -1,68 +1,35 @@ --- -title: Install and enable Keptn -description: Install Keptn +title: Install Keptn +description: Install and enable Keptn weight: 35 hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html --- -Keptn must be installed, enabled, and integrated -into each Kubernetes cluster you want to monitor. -This is because Keptn communicates with the Kubernetes scheduler -for tasks such as enforcing checks natively, -stopping a deployment from proceeding when criteria are not met, -doing post-deployment evaluations -and tracing all activities of all deployment [workloads](https://kubernetes.io/docs/concepts/workloads/) on the cluster. - -Keptn v.0.9.0 and later is installed using -an umbrella [Helm Chart](#basic-installation). -This means that the Helm Chart that installs all of Keptn -actually groups subcharts for individual services -and you can install one of these services -without installing all of Keptn. +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. -This page covers the following: - -* [Basic installation](#basic-installation) discusses the command sequence - used to install Keptn. - -* To modify the Keptn configuration, - you must modify the appropriate `values.yaml` files: - - * [Modify Helm configuration options](#modify-helm-configuration-options) - summarizes the mechanics of modifying and applying a `values.yaml` file. - * [Control what components are installed](#control-what-components-are-installed_ - explains how to modify the umbrella `values.yaml` file - to control which components are included in your Keptn configuration. - By default, all components are installed. - - This section then gives explicit notes about the components that must be configured - for common use-cases. - * [Customizing the configuration of components](#customizing-the-configuration-of-components) - explains how to modify the configuration of individual components. - -* [Running Keptn with vCluster](#running-keptn-with-vcluster) - discusses how to configure vCluster in order to run Keptn on it. - After you install Keptn, you are ready to [Integrate Keptn with your applications](../implementing/integrate.md). ## Basic installation Keptn is installed onto an existing Kubernetes cluster -using an umbrella Helm Chart. +using a Helm chart. To modify the Keptn configuration, -you must modify the appropriate Helm Chart. +you must modify the `values.yaml` file of the chart. -> **Note** Keptn works on virtually any type of Kubernetes cluster - with some standard tools installed. +> **Note** Keptn works on virtually any type of Kubernetes cluster. See - [Kubernetes cluster](k8s.md) - for details about preparing your Kubernetes cluster for Keptn. + [Requirements](reqs.md) + for specific requirements for your Kubernetes cluster. > The command sequence to fetch and install the latest release of Keptn is: @@ -71,228 +38,172 @@ The command sequence to fetch and install the latest release of Keptn is: helm repo add keptn https://charts.lifecycle.keptn.sh helm repo update helm upgrade --install keptn keptn/keptn \ - -n keptn-lifecycle-toolkit-system --create-namespace --wait + -n keptn-system --create-namespace --wait ``` -Note that the `helm repo update` command is used for fresh installs -as well as for upgrades. +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 line to specify a different Keptn version. + `helm upgrade --install` command to specify a different Keptn Helm chart version. -* Use the following command sequence to see a list of available versions: + 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 repo update - helm search repo keptn + helm upgrade --install keptn keptn/keptn \ + --version 0.3.0 \ + -n keptn-system --create-namespace --wait ``` -* To verify that the Keptn components are installed in your cluster, +* 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-lifecycle-toolkit-system + kubectl get pods -n keptn-system ``` - The output shows all components that are running on your system. + The output shows all Keptn components that are running on your cluster. -## Modify Helm configuration options +## Keptn Helm configuration -Helm chart values can be modified before the installation. -This is useful if you want to install only the `metrics-operator` -rather than the full Toolkit -or if you need to change the size of the installation. +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. -To modify configuration options, download a copy of the -[chart/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn/values.yaml) -file, modify some values, and use the modified file to install Keptn: +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](../implementing/otel.md), [Release Lifecycle Management](../intro/_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](../implementing/evaluatemetrics.md), [Analysis](../implementing/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](../architecture/cert-manager.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 -1. Download the `values.yaml` file: +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/install/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 get values RELEASE_NAME [flags] > values.yaml + helm show values keptn/keptn > values.yaml ``` 1. Edit your local copy to modify some values -1. Install Keptn by adding the following string to your `helm upgrade` command line: +1. Add the following string + to your `helm upgrade` command to install Keptn + with your configuration changes: ```shell --values=values.yaml ``` -You can also use the `--set` flag -to specify a value change for the `helm upgrade --install` command. -Configuration options are specified using the format: + For example, if you create a `my.values.yaml` + and modify some configuration values, + use the following command to apply your configuration: -```shell ---set key1=value1,key2=value2,.... -``` - -Keptn presents a toolkit composed of multiple operators, each of which enables a specific use-case. -In the next sections we explore basic installation setups based on use-case. -The installation command is always the following, only the content of the value.yaml file changes: + ```shell + helm upgrade --install keptn keptn/keptn \ + --values my.values.yaml \ + -n keptn-system --create-namespace --wait + ``` -```shell -helm repo add keptn https://charts.lifecycle.keptn.sh -helm repo update -helm upgrade --install keptn keptn/keptn \ - --values ./values.yaml \ - -n keptn-lifecycle-toolkit-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: -* The [helm-charts](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn/README.md) page - contains the full list of available values. + ```shell + --set key1=value1 \ + --set key2=value2 ... + ``` ## Control what components are installed -Keptn v.0.9 and later releases use an umbrella chart -with separate charts for individual subcharts. - -* Use the Keptn umbrella `values.yaml` file to specify which components are installed - and to set some global configuration parameters for Keptn -* Each component has its own `values.yaml` file - where you set configuration parameters that are specific to that component. - -The following table summarizes the Keptn umbrella chart scheme; - -| Component | Used for | Configuration file | -| --------- | -------- | --------------------| -| [Keptn umbrella](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](../implementing/otel.md), Lifecycle management [tasks](../implementing/tasks.md) and [evaluations](../implementing/evaluatemetrics.md) | [keptn-lifecycle-operator/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn/values.yaml) | -| [metrics-operator](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-metrics-operator/README.md) | [Keptn metrics](../implementing/evaluatemetrics.md), [Analysis](../implementing/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) | Configures TLS certificates | [keptn-cert-manager/values.yaml](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-cert-manager/values.yaml) | - 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](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn/values.yaml) -file. -The following sections summarize the configurations needed for different use cases. +you need to modify the Keptn `values.yaml` file +to disable the components you do not want to install. -Note that the umbrella scheme is quite flexible. -You can install all of Keptn on your cluster, +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 configuration. +and update your installation. Conversely, you can exclude some components when you install Keptn then later add them in. -### Enable Keptn Lifecycle Operator (Observability) - -If you only want to run the Keptn Observability use-case in your cluster, -you do not need to install the Keptn Metrics Operator. -To disable it, modify the `keptn/values.yaml` file like this: - -{{< embed path="/docs/content/en/docs/install/assets/values-only-lifecycle.yaml" >}} - -Keptn Observability must be enabled by -[Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/). -To enable Observability in your namespace, you need to annotate it. -For example, for the `simplenode-dev` namespace: - -```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"`. -This annotation tells the webhook to handle the namespace. - -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). - -### Enable Keptn Metrics Operator (Metrics) - -If you are interested in Metrics, you do not need 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** The Analysis use-case is currently behind a feature flag. - To enable it, add the following to your `helm upgrade` command line: - - ```shell - --set metricsOperator.env.enableKeptnAnalysis=true - ``` -> - -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 custom certificate manager, -you can disable Keptn `cert-manager` by using the -`--set " certificateManager.enabled=false"` argument -to the `helm upgrade` command line -or you can modify the `keptn/values.yaml` file: +you can disable Keptn `cert-manager` by setting the +`certificateManager.enabled` Helm value to `false`: -{{< embed path="/docs/content/en/docs/install/assets/values-remove-certmanager.yaml" >}} +{{< docsembed path="content/en/docs/install/assets/values-remove-certmanager.yaml" >}} For more information on using `cert-manager` with Keptn, see [Use Keptn with cert-manager.io](../operate/cert-manager.md). -For more advanced installations configurations,see: - -* [CertificateManager-README](https://github.com/keptn/lifecycle-toolkit-charts/blob/main/charts/keptn-cert-manager/README.md) - -## Customizing the configuration of components - -To access and modify the configuration of a subcomponent, -modify the component's `values.yaml` file. -You can use the sub-chart name -as written in the `chart.yaml` file. -The `README` file for each component documents the parameters -that are supported for that component. - -Here is an example `values.yaml` altering metrics operator values: - -{{< embed path="/docs/content/en/docs/install/assets/values-advance-changes.yaml" >}} - -## Running Keptn with vCluster - -Keptn running on Kubernetes versions 1.26 and older -uses a custom -[scheduler](../architecture/components/scheduler.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 `schedulingGatesEnabled` Helm chart value is set to `false` -for Kubernetes version 1.27 and later. -See -[Keptn integration with Scheduling](../architecture/components/scheduler.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. +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). diff --git a/docs/content/en/docs/install/reqs.md b/docs/content/en/docs/install/reqs.md index fe0160ccd4..3f11381417 100644 --- a/docs/content/en/docs/install/reqs.md +++ b/docs/content/en/docs/install/reqs.md @@ -38,16 +38,33 @@ 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](install.md/#running-keptn-with-vcluster) +[Running Keptn with vCluster](#running-keptn-with-vcluster) for more information. -## Resource requirements +## Running Keptn with vCluster -## cert-manager +Keptn running on Kubernetes versions 1.26 and older +uses a custom +[scheduler](../architecture/components/scheduler.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](../architecture/components/scheduler.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. -Keptn includes a lightweight cert-manager -that is used for installation and Webhooks. -You can configure a different cert-manager -before you install Keptn. -See [Implement your own cert-manager](../operate/cert-manager.md) -for instructions. +1. Follow the instructions in the section below + to install Keptn in that vCluster. diff --git a/docs/content/en/docs/install/troubleshooting.md b/docs/content/en/docs/install/troubleshooting.md index 8548aad34b..d068412039 100644 --- a/docs/content/en/docs/install/troubleshooting.md +++ b/docs/content/en/docs/install/troubleshooting.md @@ -16,7 +16,7 @@ Below are some common problems and their solutions: 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](install.md/#enable-keptn-lifecycle-operator-observability). +1. Ensure that the namespace you wish to target is [annotated correctly](install.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). diff --git a/docs/content/en/docs/yaml-crd-ref/analysis.md b/docs/content/en/docs/yaml-crd-ref/analysis.md index e2a1cb67b8..d62871a5bb 100644 --- a/docs/content/en/docs/yaml-crd-ref/analysis.md +++ b/docs/content/en/docs/yaml-crd-ref/analysis.md @@ -347,7 +347,7 @@ To preview these features, do one of the following for your Keptn cluster: file See -[Modify Helm configuration options](../install/install.md/#modify-helm-configuration-options) +[Customizing the configuration of components](../install/install.md#customizing-the-configuration-of-components) for more information. ## See also