Install Keptn

Prerequisites

Setup Kubernetes cluster

Select one of the following options:

Azure Kubernetes Service (AKS)

  1. Install local tools

  2. Create AKS cluster

    • Master version >= 1.12.x (tested version: 1.12.8)
    • One B4ms node

Amazon Elastic Kubernetes Service (EKS)

  1. Install local tools

  2. Create EKS cluster on AWS

    • version >= 1.13 (tested version: 1.13)
    • One m5.xlarge node
    • Sample script using eksctl to create such a cluster
    eksctl create cluster --version=1.13 --name=keptn-cluster --node-type=m5.xlarge --nodes=1 --region=eu-west-3
    

    In our testing we learned that the default CoreDNS that comes with certain EKS versions has a bug. In order to solve that issue we can use eksctl to update the CoreDNS service like this:

    eksctl utils update-coredns --name=keptn-cluster --region=eu-west-3 --approve
    

Google Kubernetes Engine (GKE)

  1. Install local tools

  2. Create GKE cluster

    • Master version >= 1.12.x (tested version: 1.13.7-gke.24)
    • One n1-standard-8 node
    • Image type ubuntu or cos (if you plan to use Dynatrace monitoring, select ubuntu for a more convenient setup)
    • Sample script to create such cluster (adapt the values according to your needs)
    // set environment variables
    PROJECT=name_of_gcloud_project
    CLUSTER_NAME=name_of_cluster
    ZONE=us-central1-a
    REGION=us-central1
    GKE_VERSION="1.13.7-gke.24"
    
    gcloud beta container --project $PROJECT clusters create $CLUSTER_NAME --zone $ZONE --no-enable-basic-auth --cluster-version $GKE_VERSION --machine-type "n1-standard-8" --image-type "UBUNTU" --disk-type "pd-standard" --disk-size "100" --metadata disable-legacy-endpoints=true --scopes "https://www.googleapis.com/auth/devstorage.read_only","https://www.googleapis.com/auth/logging.write","https://www.googleapis.com/auth/monitoring","https://www.googleapis.com/auth/servicecontrol","https://www.googleapis.com/auth/service.management.readonly","https://www.googleapis.com/auth/trace.append" --num-nodes "1" --enable-cloud-logging --enable-cloud-monitoring --no-enable-ip-alias --network "projects/$PROJECT/global/networks/default" --subnetwork "projects/$PROJECT/regions/$REGION/subnetworks/default" --addons HorizontalPodAutoscaling,HttpLoadBalancing --no-enable-autoupgrade
    

OpenShift 3.11

  1. Install local tools

  2. On the OpenShift master node, execute the following steps:

    • Set up the required permissions for your user:
      oc adm policy --as system:admin add-cluster-role-to-user cluster-admin <OPENSHIFT_USER_NAME>
    
    • Set up the required permissions for the installer pod:
      oc adm policy  add-cluster-role-to-user cluster-admin system:serviceaccount:default:default
      oc adm policy  add-cluster-role-to-user cluster-admin system:serviceaccount:kube-system:default
    
    • Enable admission WebHooks on your OpenShift master node:
      sudo -i
      cp -n /etc/origin/master/master-config.yaml /etc/origin/master/master-config.yaml.backup
      oc ex config patch /etc/origin/master/master-config.yaml --type=merge -p '{
        "admissionConfig": {
          "pluginConfig": {
            "ValidatingAdmissionWebhook": {
              "configuration": {
                "apiVersion": "apiserver.config.k8s.io/v1alpha1",
                "kind": "WebhookAdmission",
                "kubeConfigFile": "/dev/null"
              }
            },
            "MutatingAdmissionWebhook": {
              "configuration": {
                "apiVersion": "apiserver.config.k8s.io/v1alpha1",
                "kind": "WebhookAdmission",
                "kubeConfigFile": "/dev/null"
              }
            }
          }
        }
      }' >/etc/origin/master/master-config.yaml.patched
      if [ $? == 0 ]; then
        mv -f /etc/origin/master/master-config.yaml.patched /etc/origin/master/master-config.yaml
        /usr/local/bin/master-restart api && /usr/local/bin/master-restart controllers
      else
        exit
      fi
    

Pivotal Container Service (PKS)

  1. Install local tools

  2. Create PKS cluster on GCP

    // set environment variables
    CLUSTER_NAME=name_of_cluster
    HOST_NAME=host_name
    PLAN=small
    
    pks create-cluster $CLUSTER_NAME --external-hostname $HOST_NAME --plan $PLAN
    

Install Keptn CLI

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

  • Download the version for your operating system from https://github.com/keptn/keptn/releases/tag/0.5.0
  • Unpack the download
  • 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

    move/copy the executable to the desired folder and, optionally, add the executable to your PATH environment variable for a more convenient experience.

  • Now, you should be able to run the Keptn CLI:

    • Linux / macOS

      keptn --help
      
    • Windows

      .\keptn.exe --help
      

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

Install Keptn

To install the latest release of Keptn on a Kuberntes cluster, execute the keptn install command and provide the requested information. Since v0.3 of Keptn, the install command accepts a parameter to select the platform you would like to install Keptn on. Currently supported platforms are:

  • Azure Kubernetes Services (AKS):

    keptn install --platform=aks
    
  • Amazon Elastic Kubernetes Service (EKS):

    keptn install --platform=eks
    
  • Google Kubernetes Engine (GKE):

    keptn install --platform=gke
    
  • OpenShift 3.11:

    keptn install --platform=openshift
    
  • Pivotal Container Service (PKS):

    • Please make sure that your local kubectl CLI is configured for your target PKS cluster:

      kubectl config current-context
      
    • Install Keptn on PKS:

      keptn install --platform=kubernetes
      

In the Kubernetes cluster, this command creates the keptn, keptn-datastore and istio-system namespace. While istio-system contains all Istio related resources, keptn and keptn-datastore contain the complete infrastructure to run Keptn.

The keptn and keptn-datastore namespace contain:
  • mongoDb database for the Keptn’s log
  • NATS cluster
  • Keptn core services:
    • api
    • bridge
    • configuration-service
    • distributors
    • event-broker
    • gatekeeper-service
    • helm-service
    • jmeter-service
    • mongodb-datastore
    • pitometer-service
    • remediation-service
    • shipyard-service
    • wait-service
  • Services to deploy artifacts and to demonstrate the self-healing use cases:
    • prometheus-service
    • servicenow-service
    • openshift-route-service (OpenShift only)

Configure a custom domain (required for EKS)

In case you have a custom domain or cannot use xip.io (e.g., when running Keptn on EKS, AWS will create an ELB), there is a CLI command to configure Keptn for your custom domain:

keptn configure domain YOUR_DOMAIN

Uninstall

  • In order to uninstall Keptn from your cluster, run the uninstall command using the Keptn CLI:

    keptn uninstall
    
  • To verify the cleanup, retrieve the list of namespaces in your cluster and ensure that the keptn namespace is not included in the output of the following command:

    kubectl get namespaces
    

Troubleshooting

Please note that in case of any errors, the install process might leave some files in an inconsistent state. Therefore keptn install cannot be executed a second time without keptn uninstall. To address a unsuccessful installation:

  1. Verify the Keptn installation.

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