keptn/keptn.github.io

Keptn website and documentation portal

Keptn

Keptn V1 has reached end of life on December 22nd, 2023 and has been replaced.

Keptn is an event-based control plane for continuous delivery and automated operations for cloud-native applications. Please find the documentation on our website, and read the motivation about Keptn on our Why Keptn? page.

In addition, you can find the roadmap of the Keptn project here. It provides an overview of user stories that are currently in the focus of development for the next release.

Keptn Today! Keptn Lifecycle Toolkit Tomorrow!

Keptn: Moving towards our 1.0 milestone!

3 years of hard work will soon reach a long awaited milestone: Keptn 1.0 with LTS (Long Time Support) brings you automated release validation based on SLOs that you can easily integrate into your existing DevOps Tools (deployment, test and observability).

If you want to explore Keptn then keep scrolling down to get all information!

Keptn Lifecycle Toolkit: The kuber-native road ahead!

At KubeCon 2022 in Detroit we announced the direction we are heading: Keptn Lifecycle Toolkit! Keptn Lifecycle Toolkit brings application-aware deployment lifecycle management to your k8s cluster:

• kubernetes-native: no external dependencies, everything in your CRDs and
• pipeline-less: works with any delivery tool (ArgoCD, Flux, Jenkins, GitHub, GitLab, Harness ...) without having to integrate it with Keptn

To decide whether you want to stick with Keptn 1.0 or focus on Keptn Lifecycle Toolkit do this:

1. Watch our Keptn Lifecycle Toolkit in a Nutshell video including live demo
2. Try Keptn Lifecycle Toolkit yourself: GitHub Repo

Quickstart

Keptn runs on Kubernetes. To get started, you can follow our Quickstart guide.

Developing Keptn

The easiest way to develop is to spin up a Kubernetes cluster locally by using K3d (requires docker) via the following commands:

curl -s https://raw.githubusercontent.com/rancher/k3d/main/install.sh | TAG=v5.3.0 bash
k3d cluster create mykeptn -p "8082:80@loadbalancer" --k3s-arg "--no-deploy=traefik@server:*"

Afterwards, install Keptn CLI:

curl -sL https://get.keptn.sh | bash

And install Keptn using Helm:

helm repo add keptn https://charts.keptn.sh && helm repo update
helm install keptn keptn/keptn \
-n keptn --create-namespace \
--wait \
--set=apiGatewayNginx.type=LoadBalancer

In case you want to install helm-service and jmeter-service, execute:

helm install jmeter-service keptn/jmeter-service -n keptn
helm install helm-service keptn/helm-service -n keptn

Please follow the instructions printed by the CLI to connect to your Keptn installation.

Installing Keptn from Master branch

Note: This will install a potentially unstable version of Keptn.

If you want to install the latest master version of Keptn onto your cluster you can do that by using the development helm charts repository located at https://charts-dev.keptn.sh . By default, the global registry used is ´ghcr.io/keptn´, so you will need to override it.

helm repo add keptn-dev https://charts-dev.keptn.sh    # Add the keptn-dev helm repo
helm repo update                                       # Update all repo contents
helm search repo keptn-dev --devel --versions          # List all versions present in the keptn-dev repo

# Select a chart version from the previous command that you want to install

helm install -n keptn-dev keptn keptn-dev/keptn --set=global.keptn.registry=ghcr.io/keptn --create-namespace --version "<the-version-you-selected-previously>"

You can find more information in our docs.

Community

Please find details on regular hosted community events as well as our Slack workspace in the keptn/community repo.

Keptn Versions compatibilities

We manage the Keptn core components in versions. The versions of the Keptn core components and the services are compatible with each other. However, contributed services as well as services that are not considered core components might not follow the same versioning schema.

We are tracking compatibility of those services on our website.

Container Images

Keptn provides container images of all core components. The respective images in their versions are stored on the following container registries:

• GitHub Container Registry
• Quay.io Container Registry

From version 0.19.0, all released container images are signed using cosign with a keyless signing mechanism. That means that Keptn uses short-lived code signing certificates and keys together with OIDC and a transparency log to sign all its container images. More info on keyless signed container images can be found here.

Helm Chart

Keptn provides Helm charts for easy installation of all control plane components. From version 0.19.0, the charts are signed and can be verified with the public key that can be found in assets/pubring.gpg and attached to every release. More info on signed Helm charts can be found here.

Contributions

You are welcome to contribute using Pull Requests to the respective repositories. Before contributing, please read our Contributing Guidelines and our Code of Conduct. Please also check out our list of good first issues.

License

Keptn is an Open Source Project. Please see LICENSE for more information.

Adopters

For a list of users, please refer to ADOPTERS.md.

Further information

• The Keptn`s website has the documentation of Keptn and its use cases.
• Please join the Keptn community.

keptn.github.io's Issues

Explain requirements for execution plane services in the dev docs

Each service in the execution plane has to fulfill the same requirements. This should be explained for developers.

Content:

• https://keptn.sh/docs/0.7.x/integrations/custom_integration/
• https://keptn.sh/docs/0.7.x/integrations/sli_provider/
• https://keptn.sh/docs/0.7.x/integrations/action_provider/

Tasks:

• The service has to listen for POST requests (default on port 8080).
• The service has to send a task.started as well as a task.finished event to the public API of keptn
• Extend docs with an architecture diagram
• Extend developer docs for external contributions (incl. deployment template for the sidecar)

Definition of Done:

• An external contributor can write a Keptn-service running in the execution-plane, which adheres to all requirements

setup instruction for AWS EKS in wrong place

setup instructions for AWS EKS should be pushed into the section "Kubernetes" instead of having the next to Kubernetes.

Mark "development docs" in a different color than outdated docs

At the moment the development docs are also marked in red, see:
https://keptn.sh/docs/develop/

The color used for development docs should be different from the deprecation one (unsupported).

Explain what keptn is in plain English

I am a software engineer and after reading

• The main webpage
• The docs
• The announcement blog post

I still don't understand what keptn is exactly. The main webpage explains benefits in marketing speech.

The "what is keptn" page just mentions a list of high level points but it still doesn't say what keptn is
For example: "The solution - keptn is fully serverless" doesn't really say anything about what keptn actually is.

The current information about keptn focuses too much on low-level concepts such as its architecture and its components but there is no information on what it actually does.

It should also be useful to have a clear overview on what tools keptn is reusing (e.g. Helm, git) and what brand new concepts it introduces (e.g. the shipyard files)

Finally the docs need a clear distinction on

1. information for people who want to install keptn (i.e. operators, SREs)
2. information for people who want to use keptn as end users (i.e. developers)
3. information for people who want to extend keptn (advanced users)

Currently there is no such distinction.

Document API enhancements in References > Keptn API

In the develop and 0.6.0 (!) folder, update the documentation in Keptn API to reflect the current improvements and the available GET endpoints:

• GET /v1/project - Returns list of projects
• GET /v1/project/{projectName} - Returns meta information about project
• GET /v1/project/{projectName}/stage - Returns stages from a project
• GET /v1/project/{projectName}/stage/{stageName}/service - Returns services from a stage

Besides, add the architecture diagram to explain technical details.

Update Screenshots for Keptn's Bridge in 0.6.x docs

• Update all appearances of Keptn's Bridge with appropriate screenshots
• Also fix the typo on the title of this pic: https://keptn.sh/docs/0.6.0/usecases/deployments-with-quality-gates/assets/quality_gates.png

Quality Gates for external Deployments Tutorial: keptn_deployment tag is misleading

In the Quality Gates for external Deployments tutorial and when validating a Dynatrace-monitored service, the keptn_deployment tag is misleading and has no meaning. There is no reason why this tag is needed.

Solution: In the tutorial, the tag should be removed and a custom SLI configuration should be provided, to override the default SLI queries as implemented in the dynatrace-sli-service. The custom SLI configuration has to look as follows:

---
spec_version: '1.0'
indicators:
  throughput: "builtin:service.requestCount.total:merge(0):count?scope=tag(keptn_project:$PROJECT),tag(keptn_stage:$STAGE),tag(keptn_service:$SERVICE))"
  error_rate: "builtin:service.errors.total.count:merge(0):avg?scope=tag(keptn_project:$PROJECT),tag(keptn_stage:$STAGE),tag(keptn_service:$SERVICE))"
  response_time_p50: "builtin:service.response.time:merge(0):percentile(50)?scope=tag(keptn_project:$PROJECT),tag(keptn_stage:$STAGE),tag(keptn_service:$SERVICE))"
  response_time_p90: "builtin:service.response.time:merge(0):percentile(90)?scope=tag(keptn_project:$PROJECT),tag(keptn_stage:$STAGE),tag(keptn_service:$SERVICE))"
  response_time_p95: "builtin:service.response.time:merge(0):percentile(95)?scope=tag(keptn_project:$PROJECT),tag(keptn_stage:$STAGE),tag(keptn_service:$SERVICE))"

Update architecture jpg

Channels in architecture.jpg needs to be updated to reflect current channel list:

https://github.com/keptn/keptn.github.io/blob/master/content/docs/0.2.1/concepts/architecture/assets/architecture.jpg

https://github.com/keptn/keptn/blob/edbae83257a2f6c78dba7da1adf4ffa8135e5b04/core/eventbroker-ext/src/lib/types/KeptnRequestModel.ts#L5

Remove the next channel and add new artifact.

Sequence diagram for Keptn internal service

As a: new user to keptn
I'd like to: understand how the events in Keptn hang together.
Given that: I issue a new-artifact command
What happens next?

I'm imagining something like this:

api-service:
receives new-artifact command
>>
configuration-service:
does something
>>
helm-service:
deploys new artifact and sends a tests-started event
>>
jmeter-service:
performs tests according to shipyard definition and sends tests-finished event.
>>
lighthouse-service:
Reacts to tests-finished and sends a get-sli event to retrieve SLIs. Marks build accordingly (pass, warning or fail) and sends an evaluation-done event.
>>
gatekeeper-service:
Reacts to the evaluation done event. Decides whether or not to promote build.
etc.

This detail isn't documented for all workflows though. For example, what exactly happens when I trigger a start-evaluation?

Imrove messaging and onboarding

As also described in #198, the website does not male clear what keptn actually is.
Additionally, a clear call-to-action to get started is missing

Let's fix that.

Update documentation for Keptn Bridge

In Keptn 0.7 the Keptn Bridge has changed in quite a few directions, e.g. new screens, turned into an active role (accepting/declining approvals) etc.

These enhancements has to be reflected by the documentation in the section: keptn.sh/docs/develop/reference/bridge

Tasks:
"Landing page of Bridge"

• Remove the section Expose/Lockdown Bridge
• High-level overview of the two screens (environment screen, service screen) with new screenshots + explanation

Deep links into Keptn Bridge

• Move this section into a new sub-page
• Add explanation of how to deep-link the heatmap

Delivery Assistant

• Explain how to accept/decline an approval in the environment screen

Daily Version Check

• Add an additional point to explain who to enable/disable the feature when using the bridge the first time:
  https://keptn.sh/docs/develop/reference/bridge/version_check/#how-to-enable-diable-the-feature
• Update of screenshots (feature toggle)

Basic Authentication

• Remove the --action=expose flag

---

Definition of Done:

• Documentation for Bridge is up-to-date according to the above tasks

Documentation of required PersistentVolumeClaim

Explain the purpose of the following to PVS:

• configuration-volume: https://github.com/keptn/keptn/blob/master/installer/manifests/keptn/charts/control-plane/templates/core.yaml#L487
• mongodata: https://github.com/keptn/keptn/blob/master/installer/manifests/keptn/charts/control-plane/charts/mongodb/templates/pvc.yaml

Also provide a recommendation of their size.

Definition of Done:

• PVS and size recommendation is explained

Clarify Docs

Please clarify this paragraph:

Note: A basic health-check (i.e., accessing /health of the carts-service) is always triggered before the functional and performance tests are executed. This means, that if a basiccheck.jmx file is available, it will be executed first. The reason is that performance tests should not be executed if a basic health check fails.

I read this as: "A single request to /health is always performed, regardless of any functional or performance tests. Then any functional or performance tests are executed (if they're present)."

The following line then contradicts this by mentioning an added resource. What if there is no added resource? Is the /health endpoint triggered in that case?

Instructions for configuring a remediation provider

Update of the page: https://keptn.sh/docs/develop/automated_operations/remediation/ to explain how to configure remediation actions.

Therefore, KEP 09 works as reference: https://github.com/keptn/enhancement-proposals/pull/9/files

Definition of Done:

• It is descript how to configure remediation providers that reaction a problem

Tutorial for Integrating ArgoCD with Keptn

Provide a Glossary for terms used in Keptn

Provide a single place to go for looking up terms introduced and used in Keptn.
In this glossary, describe terms like shipyard, uniform, etc.

Improve documentation around Keptn Quality Gates

Status quo
In https://keptn.sh/docs/0.7.x/quality_gates/, just the artifacts for a quality gate (SLO/SLI) are explained including a reference to SLI-provider. Besides, the https://keptn.sh/docs/concepts/quality_gates/ provides just a high-level overview of what a Quality Gate is.

Task

• What is needed to set up a quality gate with Keptn?
• How to integrate a quality gate in an existing pipeline
• How to trigger a quality gate with the Keptn CLI
• How to get the evaluation of a quality gate with the Keptn CLI
• How to trigger a quality gate with the Keptn API
• How to get the evaluation of a quality gate with the Keptn API

Definition of Done

• As a user, I find all the information to set up a new quality gate and to customize existing ones.

Document required Kubernetes version

At the moment the required Kubernetes version on the landing page is incomplete:

We actually support Kubernetes 1.13, 1.14 and 1.15 for the full installation, but we support a variety of other versions for the quality-gates use-case installation.

We should document this on a separate page (let's name it compatibility matrix or something like that), and remove the detailed information from the landing page. An example would be here in the helm repo: https://github.com/helm/helm-www/pull/481/files

Side note: I just tried to install Keptn 0.6.1 on Kubernetes 1.16 and it does not work. 1.15 works though. See keptn/keptn#1529 for details.

News section in Keptn.sh/docs to mention security bulletins

Update carts:0.10 to carts:0.11 in tutorials of Keptn 0.6.1

A new version of carts is available that addressed a fix regarding slow-down in 0.11.2. This new version has to be used in the tutorials of 0.6.1.

Provide documentation for architectural topics in Keptn

For someone how is looking for documentation on how certain things are implemented from an architectural perspective, the most important topics (e.g., event-based, GitOps, tool integration) should be explained.

Ideas for sub-pages are:

• Architecture
  • Kubernetes native
  • Event-based Automation
  • Seperation of Concerns
  • Tool Integration
  • Built-in Observability
  • GitOps

Creating a project with git-upstream is the recommended approach

Task 1:

In the documentation, it must be clear that creating a project without git upstream is not recommended and for test/demo environments only. It must be highlighted that the upstream is the backup of the stored configuration.

Task 2:

After the issue keptn/keptn#1517 is implemented, an update of the documentation must be conducted, to reference the keptn update project command whenever a project without git upstream is created.

Defintion of Done:

• Docs for 0.6.2 are updated
• Docs for 0.7.0 are updated

Change release documentation from tutorial focus to how-to-do

Tutorials are moved to a new place so that they won't be maintained in the release documentation anymore. However, documentation must be provided to explain the features and implementation details of Keptn releases.

The agreed approach is to change the "Tutorial" section into a "How to" section with focused content about Keptn features grouped by use cases and operational tasks.

Include auto-generated docs for Keptn CLI

This is a sub-task of keptn/keptn#1611

Prepare Release 0.7.2

Please address the following items before release 0.7.2:

Note: Update the folder 0.7.x and develop folder when touching a file ❗

• Improve the install instructions for dynatrace-service - as described here: #641
• Double-check the documentation for distributors, e.g., kubectl -n keptn get deployment dynatrace-service-distributor -o wide does not work since the dynatrace-service-distributor is now a side-car -> PR #657
• Bridge: explain how to (see: #644)
  • Configuring the download link for the CLI
  • Enable/disable the version check and api token

---

Release tasks:

• Add release notes to announcement section

Duplicate logos in "Get in touch!" section

The "Get in touch!" section contains duplicate logos. They should be removed.

Restructure getting started documentation

We want to restructure the getting started documentation to provide an easier onboarding experience.

Remove "develop" directory from google search

Right now a search for keptn + minikube will find a tutorial from the "develop" docs:

We should configure our site such that anything in the develop folder is not in the search-index of search engines.

Setup Dynatrace bug (restarting pods breaks Jenkins)

keptn.github.io/content/docs/0.2.1/monitoring/dynatrace/index.md

Line 54 in 1606983

kubectl delete pods --all -n keptn

Suggests that we restart (delete) all pods but that breaks Jenkins:

1. If Jenkins becomes available again, it takes Jenkins a long time to become available again.
   a) First attempt, Jenkins restarted after 20 mins with a blank new job page.
   b) Second attemp, Jenkins still hasn't started after 50 mins.

adam@bastion:~/keptn/install/scripts$ ./deployDynatrace.sh
# This completes successfully.

adam@bastion:~/keptn/install/scripts$   kubectl delete pods --all -n keptn
pod "authenticator-jfw9p-deployment-c77c8bb68-twfnh" deleted
pod "control-zswg5-deployment-7f77ccd6b6-hkxx6" deleted
pod "docker-registry-66bb5d6d98-jgxt4" deleted
pod "event-broker-86msz-deployment-644d9b866f-44xzs" deleted
pod "event-broker-ext-zmkws-deployment-5b46bf9645-b2jpj" deleted
pod "github-service-dmr4z-deployment-5b6c5d86b6-s9nx9" deleted
pod "jenkins-deployment-d9d5d95d9-n6qhl" deleted
pod "jenkins-service-7xqqz-deployment-7447bc767d-qss7w" deleted

adam@instance-1:~/keptn/install/scripts$ kubectl get pods -n keptn
NAME                                                 READY   STATUS    RESTARTS   AGE
authenticator-jfw9p-deployment-c77c8bb68-mkt9x       2/3     Running   0          50m
control-zswg5-deployment-7f77ccd6b6-74ksw            2/3     Running   0          50m
docker-registry-66bb5d6d98-288j7                     2/2     Running   0          50m
event-broker-86msz-deployment-644d9b866f-t69gf       2/3     Running   0          50m
event-broker-ext-zmkws-deployment-5b46bf9645-7k2nl   2/3     Running   0          50m
github-service-dmr4z-deployment-5b6c5d86b6-qj5t7     2/3     Running   0          50m
jenkins-deployment-d9d5d95d9-v254d                   2/2     Running   0          50m
jenkins-service-7xqqz-deployment-7447bc767d-njkmk    2/3     Running   0          50

Create end-to-end tutorial for developers

The current keptn documentation is missing a very critical item. An end-to-end tutorial for developers that explains how to use keptn.

Let's say that I am a developer and I already have a cluster with keptn installed. I also have an application with a simple dockerfile. What should I do next in order to use keptn?

Document "expose keptn's bridge" story in Bridge Reference document

Right now the command is only documented in the (auto-generated) CLI docs.

We should also document the behaviour including the step with basic authentication here:
https://keptn.sh/docs/develop/reference/keptnsbridge/

Configure Istio for Continuous Delivery

• Install Istio (if not already available)

• Install Isito Gateway (GW)

• Configure GW for Helm-service

Definition of Done

• keptn.sh/docs/develop/continuous_delivery/ provides how-to install Istio/ configure GW

How to backup and restore a Keptn installation

We need documentation for 0.6.x and 0.7.x on how to backup and restore Keptn data.

This is especially important for the following two Kubernetes deployments:

• mongodb (contains all cloud-events; used by mongodb-datastore)
• configuration-service (contains all config repos)

Please note: Between 0.6.x and 0.7.x we have moved mongodb from the keptn-datastore namespace into the keptn namespace (and with 0.7.1 the namespace name can be arbitrary)

Use case: As a user, I want to create a backup of the configuration and cloud-events that I use with Keptn. If I ever accidentally delete the Keptn namespace, I want to be able to reinstall Keptn and restore data.

Why this came up: What if the upgrade from 0.6.2 to 0.7 fails? We should provide the user with an option to revert to the previously working installation (e.g., 0.6.2).

Required research

Properly backing up mongodb is non-trivial and needs to be researched. We want to avoid backing up an inconsistent state.

What it feels like for the user

1. Create a new cluster
2. Install Keptn 0.6.x or 0.7.x
3. Create projects, onboard services, send cloud-events (e.g., new-artifact, start-evaluation, ...)
4. Take a look at Bridge: Note down projects, services and cloud-events
5. Create a backup according to our documentation
6. Uninstall Keptn (and make sure to delete everything from the keptn and/or keptn-datastore namespace)
7. Install Keptn 0.6.x or 0.7.x (same version as before)
8. Restore data from a backup according to our documentation
9. Access Bridge: All projects, services and cloud-events that have been visible before are visible again

Out of scope

• Backing up helm related data
• Backing up istio related data
• Backing up Kubernetes namespaces, secrets, etc...
• Restoring data of an incompable Keptn version

Definition of Done

• The backup documentation does not require any third party tools to be installed locally, except for kubectl and bash
• The backup documentation must be such that data is backed up to a local drive, and restored from a local drive (read: the backup should not be stored in the cluster).
• Documentation is provided for Keptn 0.6.x on how to backup and restore mongodb and configuration-service
• Documentation is provided for Keptn 0.7.x on how to backup and restore mongodb and configuration-service
• Upgrade Guide from 0.6.x to 0.7.x contains a link to the backup documentation (e.g., please create a local backup following this guide before proceeding with the upgrade)

Fix writing of keptn CLI to use a lowercase k in docs

There are several occurances of Keptn CLI in the docs, which need to be changed to a lowercase k.

Please note, that the docs for the actual CLI (see content/docs/develop/cli/commands) are auto-generated, they need to be fixed in keptn/keptn#1718

Improve installation docs for dynatrace-service

From https://keptn.sh/docs/0.7.x/monitoring/dynatrace/install/

1. The command

kubectl -n keptn create secret generic dynatrace
--from-literal="DT_API_TOKEN=<DT_API_TOKEN>" 
--from-literal="DT_TENANT=<DT_TENANT>" 
--from-literal="KEPTN_API_URL=<KEPTN_API_URL>" 
--from-literal="KEPTN_API_TOKEN=<KEPTN_API_TOKEN>"
-oyaml --dry-run | kubectl replace -f -

is split over multiple lines and can not be copy pasted.
2. The same command should use the variables $DT_API_TOKEN etc... that are defined a couple of lines before.
3. The command kubectl -n keptn get deployment dynatrace-service-distributor -o wide does not work as we do not ship a separate distributor anymore with Keptn 0.7.1 -> remove this command from the docs.
4. The command kubectl apply -f https://raw.githubusercontent.com/keptn-contrib/dynatrace-service/$VERSION/deploy/service.yaml -n keptn explains that $VERSION needs to be set AFTER the command. It should be set prior to the command, with a link to the keptn-contrib/dynatrace-service compatibility matrix.

Documentation of deep links into Keptn Bridge and update of screenshots

The deep links, as implemented in keptn/keptn#1316, should be explained in https://keptn.sh/docs/0.6.0/reference/keptnsbridge/.

• Besides, an update of the screenshots should be done.

Deep links are:

• 'project/:projectName': opens project page of projectName
• 'project/:projectName/:serviceName': opens project page of projectName and expands serviceName
• 'project/:projectName/:serviceName/:contextId': opens project page of projectName, expands serviceName and selects root event with contextId
• 'project/:projectName/:serviceName/:contextId/:eventId': opens project page of projectName, expands serviceName, selects root event with contextId and scrolls to event with eventId
• 'trace/:shkeptncontext': will load that root event and redirect to 'project/:projectName/:serviceName/:contextId'
• 'trace/:shkeptncontext/:stage': will load that root event and redirect to 'project/:projectName/:serviceName/:contextId/:eventId' where eventId is the id of the first event on the specific stage
• 'trace/:shkeptncontext/:eventtype': will load that root event and redirect to 'project/:projectName/:serviceName/:contextId/:eventId' where eventId is the id of the last event with the specific eventtype

Preview not working correctly

When opening a PR the preview version that is created includes links to the production version of the website.
How to reproduce:

• on the preview website, click on Docs
• click on Release 0.2.0
• click on Concepts

this will forward you to the production version of the website instead of keeping the preview version

Add a "we work with your tooling" panel

A core strength of Keptn is that it integrates with almost any external tool. The Keptn homepage should highlight this.

A section that shows logos for integrations currently built. This could be a static graphic, but better would be a section that is dynamically built from logos placed into a certain directory.

For example:

Explain the use of Istio in Keptn

In the current documentation, the use of Istio is not explained.

Tasks:

• State which version of Istio is used
• Explain the context of Istio in Keptn

Definition of Done:

• A dedicated Istio section [Traffic shift with Istio] is provided in: https://keptn.sh/docs/develop/continuous_delivery/

Simplify installation - Do not install Istio nor NGNIX-ingress

• Update docs for installation with the preferred service-type for each Cloud Provider: Each platform has different ways of using the service types NodePort and LoadBalancer, but we can tackle this with recommending the preferred option for the respective platform (e.g., GKE, AKS, EKS – Loadbalancer; MiniKube, K3s, MicroK8s: NodePort; OpenShift, MiniShift: ???)

• Document how to expose Keptn Bridge and API using service-type LoadBalancer or NodePort

• If the user wants to use an ingress-controller (e.g., nginx-ingress, istio, traefik) for API/Bridge, the recommended way is to use ClusterIP and apply an ingress manifest manually.

• Update docs for installation with a troubleshooting guide if API can not be reached (e.g., refer to Kubernetes services and description of ClusterIP vs. NodePort vs. LoadBalancer)

• Remove the experimental tutorial about reusing an existing ingress-gateway (e.g., Istio)

Tasks

• Provide a visual to explain the install process

• Implement the install guide according to the process

Definition of Done

• keptn.sh/docs/develop/operate/install/ provides an install guide as outlined above
• Double-check docs/develop for used keptn install commands: quickstart, k8s_support
• Keptn with pre-installed Istio/NGINX (experimental) removed

Tutorial section on top level

As a new Keptn user, I go to keptn/docs and would like to see Tutorials/Examples I can use to familiarize myself with the concepts of Keptn.

Improve Troubleshooting guide for 0.6.x

1. If the user creates a project, onboards services, and then deletes the project, the namespaces and helm deployments stay in the cluster. Let's document this behaviour and tell the user what to do in that case.

2. If the user creates a project, onboards services, deletes the project, and does the same thing again with the same project and service name, the user might run into a problem. Let's document the error message that the user gets and provide the user with a solution.

It would be good in have a page in keptn.sh that list the available "adapters/connectors" that Keptn support integrating

It would be great to enhance the keptn.sh web site to include a page that list out the list of available adapters/connectors that integrate with keptn. I find it difficult to find it without knowing it was in the github.com/keptn-contrib.

Font size too small

when expanding the sections of the docs, the font size gets very small.

Please improve by providing a bigger font size.

Update develop docs: Keptn configure bridge now contains --user and --password

Reported by @ermin-muratovic

In the develop docs we need to adapt the keptn configure bridge command to always include --user and --password.

According to @bacherfl this has been done already (but maybe not on all occurances)

get.keptn.sh points to old version

In the quickstart guide https://keptn.sh/docs/quickstart/#2-1-install-the-keptn-cli the link points to the old version of Keptn 0.5.0 instead of 0.5.2.
See here: https://get.keptn.sh/

would be happy to fix it but I honestly don't know where this file lives.

Improve documentation on how to use the delivery assistant (approval strategy, manual approval)

We just have this note regarding approval strategy regarding writing a shipyard file here: https://keptn.sh/docs/0.7.x/continuous_delivery/multi_stage/#approval-strategy and we have some docs about how to use this feature in the UI: https://keptn.sh/docs/0.7.x/reference/bridge/delivery_assistent/ (typo? assistent?)

While we did document the commands (e.g., keptn send event approval.finished and keptn get event approval.triggered), there is no information at all on how to use the delivery assistant (similar to what we want to do with quality-gates).

I am thinking of documenting it like this:

1. Configure your project to have a manual approval step

2. Send a new-artifact event
   keptn send event new-artifact --project=... --tag=0.11.2

3. Keptn at some point decides that a manual approval is required, which can be seen in Bridge (Screenshot), or via
   keptn get event approval.triggered --project=...

4. Finally, send an approval finished (or use Bridge to send it)
   keptn send event approval.finished ...
   or optionally, do not send it to deny the artifact.

Reorganize "Get started" section into "Concepts" section

Everything that is currently situated in the Get started section:

should be moved into a release-independent section.

As a proposal, we could call it "A brief introduction to Keptn" with a reference to its core principles.

Document how to reset the Keptn API Token

In some cases the user might want to reset their API Token, e.g., when the token was leaked (by accident).

I believe it's rather easy to do this, e.g.:

$ kubectl -n keptn edit secret keptn-api-token

but afterwards we need to restart the api service (not the api gateway, right?) as it uses an environment variable

            - name: SECRET_TOKEN
              valueFrom:
                secretKeyRef:
                  name: keptn-api-token
                  key: keptn-api-token

and we need to re-authenticate the local Keptn CLI.

In addition, information about the API token is currently hard to find in the docs.

We have some information in the keptn CLI reference: https://keptn.sh/docs/0.6.0/reference/cli/#authentication

And within the API we have a link to the CLI: https://keptn.sh/docs/0.6.0/reference/api/#prerequisites

I think we should move that information to a separate page adn cross-link it. For the development folder this page could live in the "Operate Keptn" section. For 0.6.x it could live in the Reference section.

Definition of Done

• For both, development and the 0.6.x docs, create a page that tells the user on how to access, edit and create the token.
• When editing the token, add information about which services rely on the token and need to be restarted
  • Let the user know that the CLI needs to be re-authenticated
  • Let the user know that any third-party services that require the token (e.g., Dynatrace sends Problem events to the Keptn API and requiers the token) need to be updated
• Reference the API Token page within the API and CLI in the respective sections.

List all installation options (examples feature flags in Keptn Bridge, continuous-delivery.enabled, prefixPath) that can be used with the Helm install

We need to add docs (somewhere around the Installation section) that lists and explains installation options, e.g.:

https://github.com/keptn/keptn/blob/release-0.7.2/installer/manifests/keptn/values.yaml

• Whether to install just the control-plane or the CD part of Keptn (continuous-delivery.enabled)
• PrefixPath
• apiGatewayNginx.type
• in the bridge section about the environment variables introduced in the following issues/PRs:
  • keptn/keptn#2257
  • keptn/keptn#2319
  • keptn/keptn#2320
• If you know any other options, list them too (looking at @agrimmer )