Install CLI and Keptn

Prerequisites

• kubectl

Create or bring a Kubernetes cluster

To create a Kubernetes cluster, select one of the following options:

Quick Start

💡 If you would like to install Keptn in a default way, please go to Quick Start.

Use this page if you have already Keptn experience and would like to install it according to your needs.

Install Keptn CLI

Every Keptn release provides binaries for the Keptn CLI. These binaries are available for Linux, macOS, and Windows.

• Download the version for your operating system from: GitHub
• Unpack the archive

• Find the keptn binary in the unpacked directory

  • Linux / macOS: Add executable permissions (chmod +x keptn), and move it to the desired destination (e.g. mv keptn /usr/local/bin/keptn)

  • Windows: Copy the executable to the desired folder and add the executable to your PATH environment variable.

• Now, verify that the installation has worked and that the version is correct by running:

  • Linux / macOS

  keptn version
  

  • Windows

  .\keptn.exe version
  

Note: For the rest of the documentation we will stick to the Linux / macOS version of the commands.

Install Keptn

Keptn consists of a Control Plane and an Execution Plane:

• The Control Plane allows using Keptn for the Quality Gates and Automated Operations use cases. To install the control plane containing the components for quality gates and automated operations, execute:

  keptn install
  

• The Control Plane with the Execution Plane (for Continuous Delivery) allows to implement Continuous Delivery on top of quality gates and automated operations use cases. Please not that for this use-case Istio is required as well, as this is used for traffic routing between blue/green versions during deployment. To install the control plane with the execution plane for continuous delivery, execute:

  keptn install --use-case=continuous-delivery
  

How to access Keptn?

Before installing Keptn on your cluster, please also consider how you would like to access Keptn. Kubernetes provides the following four options:

• Option 1: Expose Keptn via an LoadBalancer
• Option 2: Expose Keptn via a NodePort
• Option 3: Expose Keptn via a Ingress
• Option 4: Access Keptn via a Port-forward

An overview of the four options is provided in the graphic below and the respective steps of all options are described below.

Option 1: Expose Keptn via a LoadBalancer

This option exposes Keptn externally using a cloud provider’s load balancer (if available).

1. Install Keptn: For installing Keptn on your cluster, please use the Keptn CLI. Depending on whether you would like to install the execution plane for continuous delivery, add the flag --use-case=continuous-delivery. Furthermore, if you are on OpenShift, please add --platform=openshift.

   keptn install --endpoint-service-type=LoadBalancer (--use-case=continuous-delivery) (--platform=openshift)
   

2. Get Keptn endpoint: Get the EXTERNAL-IP of the api-gateway-ngix using the command below. The Keptn API endpoint is: http://<ENDPOINT_OF_API_GATEWAY>/api

   kubectl -n keptn get service api-gateway-nginx
   

   NAME                TYPE        CLUSTER-IP    EXTERNAL-IP                  PORT(S)   AGE
   api-gateway-nginx   ClusterIP   10.117.0.20   <ENDPOINT_OF_API_GATEWAY>    80/TCP    44m
   

   Optional: Store Keptn API endpoint in an environment variable.

   For Linux and Mac:

   KEPTN_ENDPOINT=http://<ENDPOINT_OF_API_GATEWAY>/api
   

   For Windows:

   $Env:KEPTN_ENDPOINT = 'http://<ENDPOINT_OF_API_GATEWAY>/api'
   

⚠️ Warning: If you do not set up TLS encryption, all your traffic to and from the Keptn endpoint is not encrypted.

Option 2: Expose Keptn via a NodePort

This option exposes Keptn on each Kubernetes Node’s IP at a static port. Therefore, please make sure that you can access the Kubernetes Nodes in your network.

1. Install Keptn: For installing Keptn on your cluster, please use the Keptn CLI. Depending on whether you would like to install the execution plane for continuous delivery, add the flag --use-case=continuous-delivery. Furthermore, if you are on OpenShift, please add --platform=openshift.

   keptn install --endpoint-service-type=NodePort (--use-case=continuous-delivery) (--platform=openshift)
   

2. Get Keptn endpoint: Get the mapped port of the api-gateway-nginx using the command below.

   API_PORT=$(kubectl get svc api-gateway-nginx -n keptn -o jsonpath='{.spec.ports[?(@.name=="http")].nodePort}')
   

   Next, get the internal or external IP address of any Kubernetes node:

   EXTERNAL_NODE_IP=$(kubectl get nodes -o jsonpath='{ $.items[0].status.addresses[?(@.type=="ExternalIP")].address }')
   INTERNAL_NODE_IP=$(kubectl get nodes -o jsonpath='{ $.items[0].status.addresses[?(@.type=="InternalIP")].address }')
   

   The Keptn API endpoint (either via the internal or external IP; try both if unsure) is: http://${INTERNAL_NODE_IP}:${API_PORT}/api or http://${EXTERNAL_NODE_IP}:${API_PORT}/api

   Optional: Store Keptn API endpoint in an environment variable.

   For Linux and Mac:

   KEPTN_ENDPOINT=http://${EXTERNAL_NODE_IP}:${API_PORT}/api
   

   For Windows:

   $Env:KEPTN_ENDPOINT = 'http://${EXTERNAL_NODE_IP}:${API_PORT}/api'
   

⚠️ Warning: If you do not set up TLS encryption, all your traffic to and from the Keptn endpoint is not encrypted.

Option 3: Expose Keptn via an Ingress

1. Install Keptn: For installing Keptn on your cluster, please use the Keptn CLI. Depending on whether you would like to install the execution plane for continuous delivery, add the flag --use-case=continuous-delivery. Furthermore, if you are on OpenShift, please add --platform=openshift.

   keptn install (--use-case=continuous-delivery) (--platform=openshift)
   

2. Install an Ingress-Controller and create an Ingress: Please first install your favorite Ingress-Controller and then apply an Ingress object in the keptn namespace, which points to the service api-gateway-nginx on port 80. Note that the Kubernetes Ingress allows to setup TLS encryption. Note: Using Openshift 3.11 requires to use a configuration for this platform.

   Commonly used Ingress-Controller are e.g. Istio and NGINX:

   Istio 1.8+ (recommended for use-case continuous delivery)

   • Istio provides an Ingress Controller. To install Istio, please refer to the official documentation.

   • Determine the ingress IP:

   kubectl -n istio-system get svc istio-ingressgateway
   

   • Create an ingress-manifest.yaml manifest for an Ingress object in which you set IP-ADDRESS or your hostname and then apply the manifest. (Note: In the example below, nip.io is used as wildcard DNS for the IP address.)

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     annotations:
       kubernetes.io/ingress.class: istio
     name: api-keptn-ingress
     namespace: keptn
   spec:
     rules:
     - host: <IP-ADDRESS>.nip.io
       http:
         paths:
         - path: /
           pathType: Prefix
           backend:
             service:
               name: api-gateway-nginx
               port:
                 number: 80
   

   kubectl apply -f ingress-manifest.yaml
   

   Istio 1.8+ on OpenShift 3.11

   • Istio provides an Ingress Controller. To install Istio, please refer to the official documentation.

   • Determine the ingress IP:

   kubectl -n istio-system get svc istio-ingressgateway
   

   • Create an ingress-manifest.yaml manifest for an Ingress object in which you set IP-ADDRESS or your hostname and then apply the manifest. (Note: In the example below, nip.io is used as wildcard DNS for the IP address.)

   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     annotations:
       kubernetes.io/ingress.class: istio
     name: api-keptn-ingress
     namespace: keptn
   spec:
     rules:
     - host: <IP-ADDRESS>.nip.io
       http:
         paths:
         - backend:
             serviceName: api-gateway-nginx
             servicePort: 80
   

   kubectl apply -f ingress-manifest.yaml
   

   NGNIX Ingress

   • To install an NGINX Ingress Controller, please refer to the official documentation.

   • Determine the ingress IP:

   kubectl -n ingress-nginx get svc ingress-nginx
   

   • Create an ingress-manifest.yaml manifest for an ingress object in which you set IP-ADDRESS or your hostname and then apply the manifest. (Note: In the example below, nip.io is used as wildcard DNS for the IP address.)

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     annotations:
       kubernetes.io/ingress.class: nginx
     name: api-keptn-ingress
     namespace: keptn
   spec:
     rules:
     - host: <IP-ADDRESS>.nip.io
       http:
         paths:
         - path: /
           pathType: Prefix
           backend:
             service:
               name: api-gateway-nginx
               port:
                 number: 80
   

   kubectl apply -f ingress-manifest.yaml
   

   NGNIX Ingress on Openshift 3.11

   • To install an NGINX Ingress Controller, please refer to the official documentation.

   • Determine the ingress IP:

   kubectl -n ingress-nginx get svc ingress-nginx
   

   • Create an ingress-manifest.yaml manifest for an ingress object in which you set IP-ADDRESS or your hostname and then apply the manifest. (Note: In the example below, nip.io is used as wildcard DNS for the IP address.)

   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     annotations:
       kubernetes.io/ingress.class: nginx
     name: api-keptn-ingress
     namespace: keptn
   spec:
     rules:
     - host: <IP-ADDRESS>.nip.io
       http:
         paths:
         - backend:
             serviceName: api-gateway-nginx
             servicePort: 80
   

   kubectl apply -f ingress-manifest.yaml
   

3. Get Keptn endpoint: Get the HOST of the api-keptn-ingress using the command below. The Keptn API endpoint is: http://<HOST>/api

   kubectl -n keptn get ingress api-keptn-ingress
   

   NAME                HOSTS                  ADDRESS         PORTS   AGE
   api-keptn-ingress   <HOST>                 x.x.x.x   80      48m
   

   Optional: Store Keptn API endpoint in an environment variable.

   For Linux and Mac:

   KEPTN_ENDPOINT=http://<HOST>/api
   

   For Windows:

   $Env:KEPTN_ENDPOINT = 'http://<HOST>/api'
   

⚠️ Warning: If you do not set up TLS encryption, all your traffic to and from the Keptn endpoint is not encrypted.

Option 4: Access Keptn via a Port-forward

This option does not expose Keptn to the public but exposes Keptn on a cluster-internal IP.

1. Install Keptn: For installing Keptn on your cluster, please use the Keptn CLI. Depending on whether you would like to install the execution plane for continuous delivery, add the flag --use-case=continuous-delivery. Furthermore, if you are on OpenShift, please add --platform=openshift.

   keptn install (--use-case=continuous-delivery) (--platform=openshift)
   

2. Setup a Port-Forward: Configure the port-forward by using the command below.

   kubectl -n keptn port-forward service/api-gateway-nginx 8080:80
   

   To listen on any local address

   By default, kubectl port-forward binds to 127.0.0.1. If you want to listen on any local address, add --address 0.0.0.0:

   kubectl -n keptn port-forward service/api-gateway-nginx 8080:80 --address 0.0.0.0
   

3. Get Keptn endpoint: The Keptn API endpoint is: http://localhost:8080/api

   Optional: Store Keptn API endpoint in an environment variable:

   KEPTN_ENDPOINT=http://localhost:8080/api
   

Authenticate Keptn CLI

To authenticate the Keptn CLI against the Keptn cluster, the exposed Keptn endpoint and API token are required. After installing Keptn, you already have your Keptn endpoint.

KEPTN_API_TOKEN=$(kubectl get secret keptn-api-token -n keptn -ojsonpath={.data.keptn-api-token} | base64 --decode)

keptn auth --endpoint=$KEPTN_ENDPOINT --api-token=$KEPTN_API_TOKEN

$Env:KEPTN_ENDPOINT = 'http://<ENDPOINT_OF_API_GATEWAY>/api'

$tokenEncoded = $(kubectl get secret keptn-api-token -n keptn -ojsonpath='{.data.keptn-api-token}')
$Env:KEPTN_API_TOKEN = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($tokenEncoded))

keptn auth --endpoint=$Env:KEPTN_ENDPOINT --api-token=$Env:KEPTN_API_TOKEN

set KEPTN_ENDPOINT=http://<ENDPOINT_OF_API_GATEWAY>/api

kubectl get secret keptn-api-token -n keptn -ojsonpath={.data.keptn-api-token}

abcdefghijkladfaea

certutil -decode keptn-api-token-base64.txt keptn-api-token.txt

set KEPTN_API_TOKEN=keptn-api-token

keptn.exe auth --endpoint=$Env:KEPTN_ENDPOINT --api-token=$Env:KEPTN_API_TOKEN

Authenticate Keptn Bridge

After installing and exposing Keptn, you can access the Keptn Bridge by using a browser and navigating to the Keptn endpoint without the api path at the end of the URL. You can also use the Keptn CLI to retrieve the Bridge URL using:

keptn status

The Keptn Bridge has basic authentication enabled by default and the default user is keptn with an automatically generated password.

• To get the username for authentication, execute:

kubectl get secret -n keptn bridge-credentials -o jsonpath="{.data.BASIC_AUTH_USERNAME}" | base64 --decode

• To get the password for authentication, execute:

kubectl get secret -n keptn bridge-credentials -o jsonpath="{.data.BASIC_AUTH_PASSWORD}" | base64 --decode

• If you want to change the user and password for the authentication, follow the instructions here.

Change how to expose Keptn

If you would like to change the way of exposing Keptn, you can do this by re-installing Keptn and selecting the desired configuration. When the CLI asks you if you would like to overwrite the installation, confirm this with yes. This will keep all your data including the Git repos and events.

Advanced: Install Keptn using the Helm chart

Please see our guide at Advanced Installation Options for more information.

Troubleshooting

1. Verify the Keptn installation.

2. Generate a support-archive and ask for help in our Slack channel.

3. Uninstall Keptn by executing the keptn uninstall command before conducting a re-installation.