Skip to content

Commit

Permalink
docs: bold rendering only for folders (keptn#2333)
Browse files Browse the repository at this point in the history
Co-authored-by: Moritz Wiesinger <[email protected]>
  • Loading branch information
thisthat and mowies authored Oct 31, 2023
1 parent 8b6bc79 commit e0a2c05
Show file tree
Hide file tree
Showing 32 changed files with 98 additions and 95 deletions.
3 changes: 3 additions & 0 deletions .github/mlc_config.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@
},
{
"pattern": "^/images/why-keptn"
},
{
"pattern": "^../assets/"
}
],
"timeout": "20s",
Expand Down
2 changes: 1 addition & 1 deletion docs/content/en/docs/architecture/cert-manager.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.htm
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
[configure Keptn to use cert-manager.io](../operate/cert-manager.md)
[use cert-manager.io](../operate/cert-manager.md)
for this purpose.

Keptn includes a Mutating Webhook
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ so they are compatible with the Kubernetes
(HPA), which enables the horizontal scaling of workloads
based on metrics collected from multiple observability platforms.
See
[Using the HorizontalPodAutoscaler](../../../implementing/evaluatemetrics.md/#using-the-horizontalpodautoscaler)
[Using the HorizontalPodAutoscaler](../../implementing/evaluatemetrics.md/#using-the-horizontalpodautoscaler)
for instructions.

The Metrics Operator consists of the following components:
Expand All @@ -54,18 +54,18 @@ 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`](../../../yaml-crd-ref/metric.md)
The controller reconciles a [`KeptnMetric`](../../yaml-crd-ref/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](../../../yaml-crd-ref/metricsprovider.md)
[KeptnMetricsProvider](../../yaml-crd-ref/metricsprovider.md)
resource.

The steps in which the controller fetches metrics are given below:

1. When a [`KeptnMetric`](../../../yaml-crd-ref/metric.md)
1. When a [`KeptnMetric`](../../yaml-crd-ref/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.
Expand All @@ -85,7 +85,7 @@ The steps in which the controller fetches metrics are given below:
in the `status` field of the `KeptnMetric` object.
* If the evaluation fails,
the error and reason is written to the
[KeptnMetricStatus](../../../crd-ref/metrics/v1alpha3/#keptnmetricstatus)
[KeptnMetricStatus](../../crd-ref/metrics/v1alpha3/#keptnmetricstatus)
resource.
The error is described in both human-readable language
and as raw data to help identify the source of the problem
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ to gate Pods until the required deployment checks pass.
When you apply a workload to a K8s cluster,
the Mutating Webhook checks each Pod for annotations
to see if it is annotated with
[Keptn specific annotations](../../../implementing/integrate/#basic-annotations).
[Keptn specific annotations](../../implementing/integrate/_index.md#basic-annotations).
If the annotations are present, the Webhook adds a gate to the Pod called `keptn-prechecks-gate`.
This spec tells the Kubernetes scheduling framework
to wait for the Keptn checks before assigning the pod to a node.
Expand Down Expand Up @@ -64,7 +64,7 @@ a [Permit plugin](https://kubernetes.io/docs/concepts/scheduling-eviction/schedu
### 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](../../../implementing/integrate/#basic-annotations).
[Keptn specific annotations](../../implementing/integrate/#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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ weight: 50
## Keptn Workloads

A
[KeptnWorkload](../../crd-ref/lifecycle/v1alpha3/#keptnworkload)
[KeptnWorkload](../crd-ref/lifecycle/v1alpha3/#keptnworkload)
resource augments a Kubernetes
[Workload](https://kubernetes.io/docs/concepts/workloads/)
with the ability to handle extra phases.
Expand All @@ -31,7 +31,7 @@ as soon as the workload manifest is applied.

## Keptn Applications

A [KeptnApp](../../yaml-crd-ref/app.md)
A [KeptnApp](../yaml-crd-ref/app.md)
resource combines multiple Kubernetes
[workloads](https://kubernetes.io/docs/concepts/workloads/)
into a single entity
Expand Down Expand Up @@ -64,12 +64,12 @@ plus specific tasks and evaluations that you define
for the `KeptnApp` resource itself:

* The annotations described in
[Basic annotations](../../implementing/integrate/#basic-annotations)
[Basic annotations](../implementing/integrate/#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](../../implementing/integrate/#pre--and-post-deployment-checks)
[Pre- and post-deployment checks](../implementing/integrate/#pre--and-post-deployment-checks)
to the basic `KeptnApp` manifest to define
the evaluations and tasks you want to run pre- and post-deployment.

Expand All @@ -86,12 +86,12 @@ 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](../../yaml-crd-ref/config.md)
[KeptnConfig](../yaml-crd-ref/config.md)
resource.

## How basic annotations are implemented

The [Basic annotations](../../implementing/integrate/#basic-annotations)
The [Basic annotations](../implementing/integrate/#basic-annotations)
page gives instructions for applying the annotations or labels
that identify the pods that Keptn should manage.

Expand All @@ -108,7 +108,7 @@ In other words:
again first in the annotations, then in the labels.

Keptn automatically generates appropriate
[KeptnApp](../../yaml-crd-ref/app.md)
[KeptnApp](../yaml-crd-ref/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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ 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/)
[Getting started with Keptn Observability](../getting-started/)
exercise.
> Please ensure you've finished that before attempting this guide.
Expand All @@ -23,7 +23,7 @@ When Keptn is successfully monitoring your deployments, it can also run arbitrar
- post-deployment (after the post is scheduled)

> Pre and post deployments can also run on a KeptnApp level.
> See [annotations to KeptnApp](../../implementing/integrate/_index.md#annotations-to-keptnapp)
> See [annotations to KeptnApp](../implementing/integrate/_index.md#annotations-to-keptnapp)
## Prerequisites: Deploy webhook sink

Expand Down Expand Up @@ -140,7 +140,7 @@ 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](../../implementing/tasks-non-k8s-apps.md).
Incidentally, this is exactly how you can use Keptn with [applications deployed outside of Kubernetes](../implementing/tasks-non-k8s-apps.md).

> Note: If you want to trigger this multiple times, you must change the KeptnTask name.
>
Expand All @@ -150,7 +150,7 @@ Incidentally, this is exactly how you can use Keptn with [applications deployed

Annotate the demo application `Deployment` manifest to have Keptn automatically trigger the task after every deployment.

Recall the `Deployment` from the [Observability](../../getting-started/observability/_index.md#step-3-deploy-demo-application)
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:
Expand Down Expand Up @@ -219,7 +219,7 @@ Do this by using the `keptn.sh/pre-deployment-tasks` label.
## Further Information

There is a lot more you can do with KeptnTasks.
See [pre and post deployment checks page](../../implementing/integrate#pre--and-post-deployment-checks) to find out more.
See [pre and post deployment checks page](../implementing/integrate#pre--and-post-deployment-checks) to find out more.

## What's next?

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -286,6 +286,6 @@ for detailed information.
To learn more about the Keptn Metrics Server, see:

- Architecture:
[Keptn Metrics Operator](../architecture/components/metrics-operator/_index.md)
[Keptn Metrics Operator](../architecture/components/metrics-operator.md)
- More information about implementing Keptn Metrics:
[Keptn Metrics](../implementing/evaluatemetrics.md)
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ The following is an imperative walkthrough.
By the end of this page, here is what will be built.
The system will be built in stages.

![system overview](assets/install01.png)
![system overview](../assets/install01.png)

## The Basics: A Deployment, Keptn and DORA Metrics

Expand All @@ -42,7 +42,7 @@ Keptn will monitor the deployment and generate:
- An OpenTelemetry trace per deployment
- DORA metrics

![the basics](assets/install02.png)
![the basics](../assets/install02.png)

Notice though that the metrics and traces have nowhere to go.
That will be fixed in a subsequent step.
Expand Down Expand Up @@ -234,7 +234,7 @@ Open a browser window and go to `http://localhost:8080`

You should see the "Welcome to nginx" page.

![nginx demo app](assets/nginx.png)
![nginx demo app](../assets/nginx.png)

## Step 6: View DORA Metrics

Expand All @@ -257,7 +257,7 @@ 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 prometheus metrics](../assets/keptnprommetrics.png)

Keptn emits various metrics about the state of your system.
These metrics can then be visualised in Grafana.
Expand All @@ -283,7 +283,7 @@ So let's install new Observability components to help us:
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)
![add observability](../assets/install01.png)

## Step 8: Install Cert Manager

Expand Down Expand Up @@ -470,9 +470,9 @@ 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)
![keptn applications dashboard](../assets/keptnapplications.png)

![deployment trace](assets/deploymenttrace.png)
![deployment trace](../assets/deploymenttrace.png)

## Step 14: More control over KeptnApp

Expand Down Expand Up @@ -525,7 +525,7 @@ spec:
that failed to deploy, perhaps because a
`preDeploymentEvaluation` or `preDeploymentTask` failed.
See
[Restart an Application Deployment](../../implementing/restart-application-deployment/)
[Restart an Application Deployment](../implementing/restart-application-deployment/)
for a longer discussion of this.
- **workloads**
- **name** - name of this Kubernetes
Expand All @@ -545,23 +545,23 @@ If used, these fields must be populated manually:
- **preDeploymentTasks** -- list each task
to be run as part of the pre-deployment stage.
Task names must match the value of the `metadata.name` field
for the associated [KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md) resource.
for the associated [KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md) resource.
- **postDeploymentTasks** -- list each task
to be run as part of the post-deployment stage.
Task names must match the value of the `metadata.name` field
for the associated
[KeptnTaskDefinition](../../yaml-crd-ref/taskdefinition.md)
[KeptnTaskDefinition](../yaml-crd-ref/taskdefinition.md)
resource.
- **preDeploymentEvaluations** -- list each evaluation to be run
as part of the pre-deployment stage.
Evaluation names must match the value of the `metadata.name` field
for the associated
[KeptnEvaluationDefinition](../../yaml-crd-ref/evaluationdefinition.md)
[KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md)
resource.
- **postDeploymentEvaluations** -- list each evaluation to be run
as part of the post-deployment stage.
Evaluation names must match the value of the `metadata.name` field
for the associated [KeptnEvaluationDefinition](../../yaml-crd-ref/evaluationdefinition.md)
for the associated [KeptnEvaluationDefinition](../yaml-crd-ref/evaluationdefinition.md)
resource.

## Example
Expand Down Expand Up @@ -589,10 +589,10 @@ You may have noticed that the `KeptnApp` Custom Resources are created automatica

However, you can override this automatic behaviour by creating a custom `KeptnApp` CRD.
In this way, you are in full control of what constitutes a Keptn Application.
See [KeptnApp Reference page](../../yaml-crd-ref/app.md) for more information.
See [KeptnApp Reference page](../yaml-crd-ref/app.md) for more information.

## What's next?

Keptn can run pre and post deployment tasks and SLO evaluations automatically.

Continue the Keptn learning journey by [adding deployment tasks](../../implementing/tasks).
Continue the Keptn learning journey by [adding deployment tasks](../implementing/tasks).
2 changes: 1 addition & 1 deletion docs/content/en/docs/implementing/evaluatemetrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ or another standard dashboard application that you configure
or can be retrieved using standard Kubernetes commands.

For an introduction to Keptn metrics, see
[Getting started with Keptn metrics](../getting-started/usecase_metrics.md).
[Getting started with Keptn metrics](../getting-started/metrics.md).

## Keptn metric basics

Expand Down
2 changes: 1 addition & 1 deletion docs/content/en/docs/implementing/integrate/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ annotation/label is populated:
but not the combined workloads that constitute your deployed application.

See
[Keptn Applications and Keptn Workloads](../../architecture/keptn-apps/)
[Keptn Applications and Keptn Workloads](../../architecture/keptn-apps.md)
for architectural information about how `KeptnApp` and `KeptnWorkloads`
are implemented.

Expand Down
2 changes: 1 addition & 1 deletion docs/content/en/docs/implementing/slo/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ 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/)
* [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.
Expand Down
4 changes: 2 additions & 2 deletions docs/content/en/docs/install/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,15 +34,15 @@ You are then ready to

Keptn running on Kubernetes versions 1.26 and older
uses a custom
[scheduler](../architecture/components/scheduler/),
[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/)
[Keptn integration with Scheduling](../architecture/components/scheduler.md)
for details.

To solve this problem:
Expand Down
2 changes: 1 addition & 1 deletion docs/content/en/docs/install/reqs.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ 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](../architecture/components/scheduler/)
[Keptn integration with Scheduling](../architecture/components/scheduler.md)
for details.

If Keptn is installed on a [vCluster](https://www.vcluster.com/) with
Expand Down
File renamed without changes.
8 changes: 4 additions & 4 deletions docs/content/en/docs/intro/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ simplifying configuration and integration into a single set of metrics.

To learn more, see:

* [Getting started with Keptn metrics](../getting-started/usecase_metrics.md)
* [Getting started with Keptn metrics](../getting-started/metrics.md)
* [Keptn Metrics](../implementing/evaluatemetrics.md) User Guide

## Observability
Expand Down Expand Up @@ -86,7 +86,7 @@ to ensure that your deployments are observable.

To learn more, see:

* [Getting started with Keptn Observability](../getting-started/observability)
* [Getting started with Keptn Observability](../getting-started/observability.md)
* [Standardize observability](usecase-observability.md/)
* [DORA metrics](../implementing/dora) User Guide
* [OpenTelemetry observability](../implementing/otel.md) User Guide
Expand Down Expand Up @@ -134,8 +134,8 @@ or a
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/tasks/)
* [Getting started with release lifecycle management](../getting-started/lifecycle-management.md)
* [Deployment tasks](../implementing/tasks) User Guide
* [Evaluations](../implementing/evaluations.md) User Guide
* [Manage release lifecycle](usecase-orchestrate.md)
* [KeptnApp and KeptnWorkload resources](../architecture/keptn-apps)
* [KeptnApp and KeptnWorkload resources](../architecture/keptn-apps.md)
4 changes: 2 additions & 2 deletions docs/content/en/docs/intro/usecase-observability.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ This is the second of three exercises in the
series:

- In the
[Getting started with Keptn metrics](../getting-started/usecase_metrics.md)
[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.
Expand Down Expand Up @@ -116,7 +116,7 @@ which allows you to trace everything done in the context of that deployment.
You can supplement the DORA Metrics and OpenTelemetry information
with information you explicitly define using Keptn metrics.
The
[Getting started with Keptn metrics](../getting-started/usecase_metrics.md)
[Getting started with Keptn metrics](../getting-started/metrics.md)
exercise discusses how to define Keptn metrics.

## View the results
Expand Down
Loading

0 comments on commit e0a2c05

Please sign in to comment.