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.11-gke.14)
    • One n1-standard-8 node
    • Image type ubuntu or cos (Note: If you plan to use Dynatrace monitoring, select ubuntu for a more convenient setup.)
    • Sample script to create such cluster:
    // 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 github.com/keptn/
  • 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: Copy the executable to the desired folder and add the executable to your PATH environment variable.

  • 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 Linux / macOS 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 the platform flag to select the target platform you would like to install Keptn on. Currently supported platforms are:

  • Azure Kubernetes Services (AKS):

    keptn install --platform=aks --keptn-version=release-0.6.0.beta2
    
  • Amazon Elastic Kubernetes Service (EKS):

    keptn install --platform=eks --keptn-version=release-0.6.0.beta2
    
  • Google Kubernetes Engine (GKE):

    keptn install --platform=gke --keptn-version=release-0.6.0.beta2
    
  • OpenShift 3.11:

    keptn install --platform=openshift --keptn-version=release-0.6.0.beta2
    
  • Pivotal Container Service (PKS):

    keptn install --platform=pks --keptn-version=release-0.6.0.beta2
    

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
    • eventbroker
    • gatekeeper-service
    • helm-service
    • jmeter-service
    • lighthouse-service
    • mongodb-datastore
    • 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)

Note: If you want to install Keptn just for the use case of Keptn Quality Gates, you have the option to roll-out Keptn without components for automated delivery and operations. Therefore, the use-case flag must be set to quality-gates:

keptn install --platform=[aks|eks|gke|openshift|pks|kubernetes] --keptn-version=release-0.6.0.beta2 --use-case=quality-gates

Configure a custom domain (required for EKS)

If you have a custom domain or cannot use xip.io (e.g., when running Keptn on EKS with an ELB (Elastic Load Balancer) from AWS), there is the CLI command keptn configure domain to configure Keptn for your custom domain:

keptn configure domain YOUR_DOMAIN --keptn-version=release-0.6.0.beta2

Uninstall

  • 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.