In this tutorial you'll learn how to run and customize Keptn-in-a-Box. Keptn-In-A-Box is a Bash script that will convert a plain Ubuntu machine in a Single Node Kubernetes Cluster with Keptn installed and configured (among other cool features which will set sail for your autonomous cloud journey). The script is programmed in a modular way so you can select the 🧩 installationBundle that better suits your needs.

Keptn-in-a-Box is a 🚀 rocket launcher for enabling tutorials or workshops in an easy, fast and resource efficient way.

In a matter of minutes you'll have a fully configured Single Node Kubernetes Cluster for learning Keptn tutorials, trying out new functionalities, building your own pipeline or even delivering Performance-as-a-Self-Service.

Keptn-in-a-Box runs on microk8s, which is a simple production-grade upstream certified Kubernetes made for developers and DevOps.

The mantra behind Keptn-In-A-Box is that you

keptn-in-a-box

You can actually just run the program without any customization, but let's take the time to understand what Keptn-in-a-Box does for you and how you can customize the installation.

What you'll learn

Recommended

⦿

Optional

○

Prerequisite

The only prerequisite for Keptn-in-a-Box is that you get an Ubuntu machine and that it has an internet connection. This can be a VirtualMachine running in your datacenter, on your laptop or in a cloud provider such as Microsoft Azure, Amazon Web Services, Google Cloud among others.
The tested distributions are Ubuntu Server 18.04 LTS & 20.04 LTS

☁️Get a cloud VM

Don't have a VM or a Cloud Account? Don't worry, here you can sign for a free tier in:

💻Get a local VM

Want to try it locally? Not a problem. Check out multipass! a great way for spinning instant Ubuntu VMs in Windows, Mac or Linux computers.

📏Sizing

For most usecases we recommend 4 Cores, 16 Gigs of RAM and 20 Gigs of diskspace. Our tests on aws have shown that the minimum required for running Keptn-in-a-Box with the default installation bundle is a t2.medium (2 vCPU and 4 Gib of RAM) and 10 Gigabytes of disk space. Nevertheless this won't leave much space for spinning other services or onboarding applications.

For the 😎 ultimate experience you could get a t2.2xlarge with 8 Cores, 32 Gigs of RAM and 20 Gigs of diskspace.

AWS sizings for reference

Below is a table for the sizing reference.

-

Size

vCPUs

Memory (GiB)

😓

t3.medium

2

4

🙂

t3.large

2

8

😊

t3.xlarge

4

16

🤓

t3.2xlarge

8

32

☎️ Open ports

If you define security rules in the Cloud provider or on your datacenter, your instance only needs to have the following ports accessible:

Other considerations

💻 Login to your Ubuntu

When your Ubuntu machine is up and running, let's log in into it.

ssh yourusername@the-bind-ip-or-dns

Download keptn-in-a-box.sh

Now let's download the keptn-in-a-box.sh file and make it executable.

curl -O https://raw.githubusercontent.com/keptn-sandbox/keptn-in-a-box/release-0.9.2/keptn-in-a-box.sh
chmod +x keptn-in-a-box.sh

For the best experience we recommend that you enable Dynatrace monitoring.

By only providing your Dynatrace credentials, Keptn-in-a-Box will:

If you don't have a Dynatrace tenant yet, sign up for a free trial or a developer account.

Create a Dynatrace API Token

Log in to your Dynatrace tenant and go to Settings > Integration > Dynatrace API. Then, create anew API token with the following permissions

Take a look at this screenshot to double check the right token permissions for you.
Dynatrace API Token

Create a Dynatrace PaaS Token

In your Dynatrace tenant, go to Settings > Integration > Platform as a Service, and create a new PaaS Token.

Enter your Dynatrace Credentials

Now that you have an API-Token and a PaaS-Token, we can enter the credentials.
In the keptn-in-a-box.sh file enter your credentials under the section "Define Dynatrace Environment".

# ---- Define Dynatrace Environment ---- 
# Sample: https://{your-domain}/e/{your-environment-id} for managed or https://{your-environment-id}.live.dynatrace.com for SaaS
TENANT="https://mytenant.live.dynatrace.com"
PAASTOKEN="myDynatracePaaSToken"
APITOKEN="myDynatraceApiToken"

That's it! When you run the program, it will detect that you enter your credentials and will download and configure Dynatrace for you.

Default configuration (public IP)

By default Keptn-in-a-Box will curl ifconfig.me to get the public IP where it's running and will convert the IP into a magic 🧙‍♂️ domain with nip.io. For example if your Box is public accessible over the IP 116.203.255.68 it will convert it to 116-203-255-68.nip.io. NIP.IO is a simple wildcard DNS resolution for any IP Address.

✅ If your box has a public ip, you can go with the defaults and leave the DOMAIN variable empty.

Configuration for an internal IP

For example, I want to run Keptn-in-a-Box inside my home network and the VM gets the ip 192.168.0.10. I will convert the IP to a magic domain. This way the requests to any subdomain, for example to https://keptn.192.168.0.10.nip.io/api will get resolved to 192.168.0.10 and then kubernetes will take care of forwarding the request internally to the Keptn API service.

Just enter the IP in a magic domain notation as shown below. The ip can contain dashes (-) or dots (.). I just like dashes more, they are prettier 💄.

# ---- Define your Domain ----   
DOMAIN="192-168-0-10.nip.io"

With the above example you'll be able to access the teaser at http://192-168-0-10.nip.io

autonomous-cloud-teaser

👨‍💻 A common feature is to use this box for workshops providing access to a guest user. If you spin the instances with a private key and you don't want to share your SSH Key, this feature will create a user, clone the home directory of the $USER who runs the program with its folders (such as keptn-examples) and configurations for the bash and clients like helm, istioctl,kubectl, docker and keptn.

The following variables will define the User Account and the SSH password. Set the variables as you desire:

# ---- Workshop User  ---- 
NEWUSER="dynatrace"
NEWPWD="dynatrace"

This functionality is disabled by default but can be independently enabled with any installation bundle. The function flag

create_workshop_user=true

needs to be active and defined after the installation bundles section. More about functions, control flags and installationBundles in the step select the Installation Bundle.

↳ Programs logic

Before selecting the installation Bundle, let's understand how Keptn-in-a-box.sh works and what it will do.

keptn-in-a-box.sh is the controller. Here we have been defining our variables. When executing this script, it will download and load the functions defined in functions.sh. Which ⨍ functions to execute are controlled by their 🚦control flags. Now, an 🧩installation Bundle is the enablement for multiple control flags.

🧩installation Bundles & 🚦control flags

Now that we have understood the delegation of the program's logic and it's main components, here is a table of the installation Bundles and their respective enabled flags:

🧩installation Bundles

🚦control Flags

🚦control flag

Demo

Workshop

KeptnOnly

QualityGates

PerfAaS

All

update_ubuntu

✅

✅

✅

✅

✅

✅

docker_install

✅

✅

✅

✅

✅

✅

microk8s_install

✅

✅

✅

✅

✅

✅

setup_proaliases

✅

✅

✅

✅

✅

✅

enable_k8dashboard

-

✅

-

✅

✅

✅

enable_registry

-

-

-

-

-

✅

istio_install

✅

✅

✅

-

-

✅

helm_install

✅

✅

✅

-

✅

✅

certmanager_install

-

-

-

-

-

✅

certmanager_enable

-

-

-

-

-

✅

git_deploy

✅

✅

-

-

-

✅

git_migrate

✅

✅

-

-

-

✅

keptn_install

✅

✅

✅

✅

✅

✅

keptn_examples_clone

✅

✅

✅

✅

✅

✅

resources_clone

✅

✅

✅

✅

✅

✅

dynatrace_savecredentials

✅

✅

✅

✅

✅

✅

dynatrace_configure_monitoring

✅

✅

✅

✅

✅

✅

keptndeploy_homepage

✅

✅

✅

✅

✅

✅

keptndemo_cartsload

✅

✅

-

-

-

✅

keptndemo_unleash

✅

✅

-

-

-

✅

keptndemo_unleash_configure

✅

✅

-

-

-

✅

keptndemo_cartsonboard

✅

✅

-

-

-

✅

expose_kubernetes_api

✅

✅

✅

✅

✅

✅

expose_kubernetes_dashboard

-

✅

-

✅

✅

✅

patch_kubernetes_dashboard

-

✅

-

-

-

✅

create_workshop_user

-

-

-

-

-

✅

jenkins_deploy

-

-

-

-

-

✅

keptn_bridge_disable_login

✅

✅

-

-

-

✅

keptn_install_qualitygates

-

-

-

✅

✅

✅

The dynatrace_ control flags will be disabled if you don't enter your Dynatrace credentials.

The Default Installation Bundle

🧩The default installation bundle is installationBundleDemo. You can change installation bundles by commenting them out in the section.

# ==================================================
#    ----- Select your installation Bundle -----   #
# ==================================================
# Uncomment for installing only Keptn 
# installationBundleKeptnOnly

# - Comment out if selecting another bundle
installationBundleDemo

Enable or disable specific functionality

You can also override and enable/disable specific modules after you select the installationBundle. For example lets enable the workshop account regardless of the installationBundle we selected.

# ==================================================
# ---- Enable or Disable specific functions -----  #
# ==================================================
create_workshop_user=true

The Installation function

# ==================================================
#  ----- Call the Installation Function -----      #
# ==================================================
doInstallation

At the end of keptn-in-a-box.sh we call the installation function. This function is defined at the end of the functions.sh file. This function defines the order in which the different modules are to be executed since they have a chronological dependency. For example, in order to onboard an application we first need to have Keptn installed, and Keptn needs Microk8s installed and so on...

Yay! now let's see Keptn-in-a-box in action 🤘!

Now that we understand how it works and we have customized the box as we want, let's trigger the installation.

Run the script with sudo rights and send the process to the background.

sudo bash -c './keptn-in-a-box.sh &'

Why run it in the background and where is the output of the program you say? Well, keptn-in-a-box is actually optimized to be executed for non-interactive shells at the initialization of an instance. This is done programmatically passing the script as user data while creating dynatrace environments and spinning multiple instances for each student. This is achieved with the Dynatrace Rest Tenant Automation program. Yes, we love ❤️ automation 🤖and the customization, creation and configuration of environments and instances is done programmatically.

What happens in the background

The script will clone the keptn-in-a-box repository in the 🏠home directory of the user that executed it. It will execute the functions marked as true. The installation will take between 4 and 10 minutes, depending on the amount of features, internet connection speed and computing power available.

🔍Inspect the script at runtime

To inspect how the installation is going, type

less +F /tmp/kiab-install.log

This will open the installation log and read from the input stream. To exit just type CTRL + C and then quit.

Installation complete 🙌

At the end of the installation file you should see something similar

[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |======================================================================
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |============ Installation complete :) ============
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |______________________________________________________________________
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |>->-> It took 8 minutes and 10 seconds <-<-<|
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |======================================================================
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |============ Keptn & Kubernetes Exposed Ingress Endpoints ============
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |______________________________________________________________________
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |>->-> Below youll find the adresses and the credentials to the exposed services. <-<-<|
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |>->-> We wish you a lot of fun in your Autonomous Cloud journey! <-<-<|

NAMESPACE      NAME                   CLASS    HOSTS                                                                                                                                ADDRESS     PORTS     AGE
default        homepage-ingress       <none>   192-168-0-10.nip.io                                                                                                                 127.0.0.1   80, 443   2m48s
default        k8-api-ingress         <none>   api.kubernetes.192-168-0-10.nip.io                                                                                                  127.0.0.1   80, 443   4m16s
istio-system   istio-ingress          <none>   *                                                                                                                                    127.0.0.1   80, 443   4m16s
istio-system   sockshop-ingress       <none>   carts.sockshop-dev.192-168-0-10.nip.io,carts.sockshop-staging.192-168-0-10.nip.io,carts.sockshop-production.192-168-0-10.nip.io     127.0.0.1   80, 443   12s
istio-system   unleash-ingress        <none>   unleash.unleash-dev.192-168-0-10.nip.io                                                                                             127.0.0.1   80, 443   2m22s
jenkins        jenkins-ingress        <none>   jenkins.192-168-0-10.nip.io                                                                                                         127.0.0.1   80, 443   2m1s
keptn          api-keptn-ingress      <none>   keptn.192-168-0-10.nip.io                                                                                                           127.0.0.1   80, 443   2m54s
kube-system    k8-dashboard-ingress   <none>   kubernetes.192-168-0-10.nip.io                                                                                                      127.0.0.1   80, 443   4m16s
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |======================================================================
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |============ Unleash-Server Access ============
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |______________________________________________________________________
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |>->-> Username: keptn <-<-<|
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |>->-> Password: keptn <-<-<|
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |======================================================================
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |============ Jenkins-Server Access ============
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |______________________________________________________________________
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |>->-> Username: keptn <-<-<|
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |>->-> Password: keptn <-<-<|
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |======================================================================
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |============ Workshop User Access (SSH Access) ============
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |______________________________________________________________________
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |>->-> ssh student@192-168-0-10.nip.io <-<-<|
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |>->-> Password: secr3t <-<-<|
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |======================================================================
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |============ Git-Server Access (SSH Access) ============
[Keptn-In-A-Box|INFO] [2020-08-04 17:01:23] |______________________________________________________________________
...

Let's say we selected the 🧩installationBundleWorkshop and we installed keptn-in-a-box in a VM in our home network and the student is dynatrace with the password dynatrace and the domain is 192-168-0-10.nip.io (for ip 192.168.0.10)

After a shell login

ssh dynatrace@192-168-0-10.nip.io

🏠The home directory

List the content of the home directory:

ls 
examples keptn-in-a-box snap

You'll have 3 directories; a clone of the keptn examples, a clone of keptn-in-a-box repository and the configuration of microk8s in snap.

💻 Configured clients

The clients are configured and ready to use helm, istioctl,kubectl, docker and keptn.

For example type:

keptn status
Starting to authenticate
Successfully authenticated
Using a file-based storage for the key because the password-store seems to be not set up.
CLI is authenticated against the Keptn cluster https://keptn.192-168-0-10.nip.io/api

to see that keptn is installed and already configured or type

kubectl get all -n sockshop-dev

to list the cart sample pods and services of the development stage. You'll notice that autocomplete is also enabled.

💻 Available services

Service

URL

Teaser

https://192-168-0-10.nip.io

Kubernetes Dashb.

https://kubernetes.192-168-0-10.nip.io

Kubernetes API

https://api.kubernetes.192-168-0-10.nip.io

Git-Server Repos

https://git.192-168-0-10.nip.io/explore/repos

Git-Server API

https://git.192-168-0-10.nip.io/api/swagger

Keptn API (swagger)

https://keptn.192-168-0-10.nip.io/api/swagger-ui

Keptn Bridge

https://keptn.192-168-0-10.nip.io/bridge

Unleash

https://unleash.unleash-dev.192-168-0-10.nip.io

Carts pipeline overview

https://192-168-0-10.nip.io/pipeline/

The Teaser contains links to most of the available services. You can print also the services by showing the configured ingresses in kubernetes

kubectl get ing -A

Continue innovating 🚀

Now that you have your single node Kubernetes Cluster configured and up and running, you are all set to continue your journey to the autonomous cloud. Start typing kubectl commands, onboard applications with keptn, or maybe create your own unbreakable pipeline locally? What about creating your own Keptn Service? Take a look at more Keptn tutorials.

If you want to verify that the installation finished without errors. Inspect the log with this command:

cat /tmp/kiab-install.log | grep -i error

If there is no output it means that no error was found in the installation log.

If there is an issue, or maybe there wasn't but you want to start new, here is how we recommend to reboot your Microk8s and everything installed in your single kubernetes cluster.

Search the functions.sh file, it should be inside the keptn-in-a-box directory. Load it to the shell and run the function removeMicrok8s

source functions.sh && removeMicrok8s

This will ask for the sudo password since we are basically removing microk8s and purging its data with the command sudo snap remove microk8s --purge . It will also print the directories that were cloned such as the examples or keptn-in-a-box. It's recommended to delete them if you are upgrading versions. Before deleting any directory make sure to save a copy of keptn-in-a-box.sh or at least the variables defined in there for example the DOMAIN or the Dynatrace credentials.

We load the functions in the current shell and we set the flag for all features to be active. Then we can enable module by module.

source functions.sh && installationBundleAll

Here are some examples:

Enable Jenkins

Now we enable the modules we want to activate, for example we want to deploy Jenkins, we type

jenkinsDeploy

Enable Kubernetes Dashboard and patch its access

Let's say we want to enable the default Kubernetes Dashboard and disable the login for experimenting and learning.

microk8sEnableDashboard
exposeK8Services
patchKubernetesDashboard

Enable own GIT server & Migrate Keptn projects to it.

DOMAIN=$(kubectl get configmap domain -n default -ojsonpath={.data.domain})
gitDeploy
gitMigrate

Create a(nother) Workshop account.

Now we to create a workshop account for Tony. For this we need elevated rights since we will restart the SSH service, enable authentication via SSH. Since we want to copy the home directory and it's properties of the user (e.g. ubuntu) but also need root rights, this needs a couple of more steps.

As the normal user (not root) we type the following series of commands.
First become root and load the functions in the shell (again since it's a new shell)

sudo su
source functions.sh && installationBundleAll

Then we tell the script from where we copy the home directory and settings. This is normally the user you were before which is by default saved in the var $SUDO_USER in interactive shells. We also mark the new userid and it's password. Finally we run the function.

USER=$SUDO_USER
NEWUSER="tony"
NEWPWD="SuperTony"
createWorkshopUser

Now tony is able to login to the KIAB machine via SSH and interact with kubectl and keptn.

Please visit us in our Keptn Slack and tell us how you like Keptn and this tutorial! We are happy to hear your thoughts & suggestions!

Also, make sure to follow us on Twitter to get the latest news on Keptn, our tutorials and newest releases!