From 98079866fd19e100e3e63ba28bcdc47aca98546b Mon Sep 17 00:00:00 2001 From: Florian Bacher Date: Fri, 5 Jan 2024 10:20:27 +0100 Subject: [PATCH] docs: remove indentation to fix code blocks (#2751) Signed-off-by: Florian Bacher Co-authored-by: Meg McRoberts --- .../docs/contrib-guidelines-docs.md | 26 ++-- .../docs/contribute/docs/local-building.md | 18 +-- .../docs/contribute/software/dev-environ.md | 30 ++-- docs-new/docs/guides/dora.md | 22 +-- docs-new/docs/guides/otel.md | 26 ++-- docs-new/docs/installation/index.md | 52 +++---- docs-new/docs/installation/k8s.md | 8 +- docs-new/docs/migrate/metrics-observe.md | 140 +++++++++--------- .../docs/reference/api-reference/index.md | 8 +- 9 files changed, 161 insertions(+), 169 deletions(-) diff --git a/docs-new/docs/contribute/docs/contrib-guidelines-docs.md b/docs-new/docs/contribute/docs/contrib-guidelines-docs.md index 18ad3e4595..c7c18d77a7 100644 --- a/docs-new/docs/contribute/docs/contrib-guidelines-docs.md +++ b/docs-new/docs/contribute/docs/contrib-guidelines-docs.md @@ -68,21 +68,21 @@ that are relevant only to documentation 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 - ... - ``` +```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 - ... - ``` +```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. @@ -92,9 +92,9 @@ that are relevant only to documentation * 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 - ``` +```shell +make markdownlint-fix +``` See [Markdownlint](./linter-requirements.md#markdownlint) for details. diff --git a/docs-new/docs/contribute/docs/local-building.md b/docs-new/docs/contribute/docs/local-building.md index 52b37d7d77..5021e43ee9 100644 --- a/docs-new/docs/contribute/docs/local-building.md +++ b/docs-new/docs/contribute/docs/local-building.md @@ -19,9 +19,9 @@ To set up a local Docsy build: 1. Execute the following command from the `docs` folder of your clone: - ```shell - make server - ``` +```shell +make server +``` It will continue running in its own shell. @@ -72,10 +72,10 @@ to check your formatting, you have the following options: you can format the specified file locally by running the following in its own shell: - ```shell - grip .md - ``` +```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. +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/software/dev-environ.md b/docs-new/docs/contribute/software/dev-environ.md index d683f996d7..d7be308a64 100644 --- a/docs-new/docs/contribute/software/dev-environ.md +++ b/docs-new/docs/contribute/software/dev-environ.md @@ -96,9 +96,9 @@ you need to install the following on your system: 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 - ``` +```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) @@ -124,9 +124,9 @@ You are now ready to make your changes to the source code. 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 - ``` +```shell +make build-deploy-metrics-operator RELEASE_REGISTRY=docker.io/exampleuser TAG=my-feature +``` ## Testing @@ -148,23 +148,23 @@ Study these errors, modify your code, and rerun the test until it passes. 1. Run the integration tests from the root directory of your clone: - ```shell - make integration-test-local - ``` +```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 - ``` +```shell +make component-test +``` 1. From the `lifecycle-operator` directory, run the end-to-end tests: - ```shell - make e2e-test - ``` +```shell +make e2e-test +``` ## Create and manage the PR diff --git a/docs-new/docs/guides/dora.md b/docs-new/docs/guides/dora.md index b51b707f85..cd4c2a39ea 100644 --- a/docs-new/docs/guides/dora.md +++ b/docs-new/docs/guides/dora.md @@ -35,23 +35,23 @@ 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 - ``` +```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 - ``` +```shell +kubectl -n keptn-system port-forward \ +service/ 2222 +``` Then view the metrics at: - ```shell - http://localhost:2222/metrics - ``` +```shell +http://localhost:2222/metrics +``` DORA metrics are also displayed on Grafana or whatever dashboard application you choose. diff --git a/docs-new/docs/guides/otel.md b/docs-new/docs/guides/otel.md index e3495266f6..18efd9babf 100644 --- a/docs-new/docs/guides/otel.md +++ b/docs-new/docs/guides/otel.md @@ -51,21 +51,21 @@ you must have the following on your cluster: 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: +- 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/ - ``` + 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: diff --git a/docs-new/docs/installation/index.md b/docs-new/docs/installation/index.md index dac9206655..4e400fd09a 100644 --- a/docs-new/docs/installation/index.md +++ b/docs-new/docs/installation/index.md @@ -90,26 +90,26 @@ Some helpful hints: To get the appropriate chart version for the Keptn version you want, use the following command: - ```shell - helm search repo keptn --versions - ``` +```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 - ``` +```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 - ``` +```shell +kubectl get pods -n keptn-system +``` The output shows all Keptn components that are running on your cluster. @@ -174,9 +174,9 @@ To modify Helm values: 1. Download a copy of the Helm values file: - ```shell - helm show values keptn/keptn > values.yaml - ``` +```shell +helm show values keptn/keptn > values.yaml +``` 1. Edit your local copy to modify some values @@ -184,28 +184,28 @@ To modify Helm values: to your `helm upgrade` command to install Keptn with your configuration changes: - ```shell - --values=values.yaml - ``` +```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 - ``` +```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 ... - ``` +```shell +--set key1=value1 \ +--set key2=value2 ... +``` ## Control what components are installed diff --git a/docs-new/docs/installation/k8s.md b/docs-new/docs/installation/k8s.md index d4327f51e3..d1bee2eeab 100644 --- a/docs-new/docs/installation/k8s.md +++ b/docs-new/docs/installation/k8s.md @@ -29,9 +29,7 @@ The basic steps are: 2. Download [KinD](https://kind.sigs.k8s.io/) 3. Create the local KinD cluster with the following command: - ```shell - kind create cluster - ``` + kind create cluster See the [KinD Quick Start Guide](https://kind.sigs.k8s.io/docs/user/quick-start/) @@ -42,9 +40,7 @@ The basic steps are: and that it is running a supported version of Kubernetes with the following command: - ```shell - kubectl version --short - ``` + kubectl version --short ## Prepare your cluster for Keptn diff --git a/docs-new/docs/migrate/metrics-observe.md b/docs-new/docs/migrate/metrics-observe.md index 2ce709dc6f..6deb91cc07 100644 --- a/docs-new/docs/migrate/metrics-observe.md +++ b/docs-new/docs/migrate/metrics-observe.md @@ -97,17 +97,17 @@ The process is: - ```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 - ``` +```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 +``` @@ -130,9 +130,9 @@ The process is: 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 - ``` +```shell +kubectl apply -f analysis-value-template.yaml -n keptn-lifecycle-poc +``` 1. Convert the SLO to an `AnalysisDefinition` resource: @@ -145,17 +145,17 @@ The process is: - ```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 +```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 - ``` +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 +``` @@ -165,9 +165,9 @@ The process is: 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 - ``` +```shell +kubectl apply -f analysis-definition.yaml -n keptn-lifecycle-poc +``` 1. Create a `KeptnMetricsProvider` resource @@ -211,22 +211,22 @@ The process is: 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 - ``` +```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 - ``` +```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 - ``` +```shell +NAME ANALYSISDEFINITION WARNING PASS +analysis-sample-1 my-project-ad true +``` This shows that the analysis passed successfully. @@ -237,39 +237,39 @@ The process is: 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: "" - ``` +```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 diff --git a/docs-new/docs/reference/api-reference/index.md b/docs-new/docs/reference/api-reference/index.md index cfec845cf3..57ab631a87 100644 --- a/docs-new/docs/reference/api-reference/index.md +++ b/docs-new/docs/reference/api-reference/index.md @@ -23,17 +23,13 @@ Use `kubectl` to inspect the current contents of any Keptn resource: For example, to list all the `KeptnApp` resources in the `namespace1` namespace, the command is: - ```shell - kubectl get keptnapps -n namespace1 - ``` + 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 - ``` + kubectl get keptnapp -n my-keptn-app -oyaml For more information about the APIs and Custom Resources, see the Kubernetes documentation: