Introduction

Installing Kyma locally on a Windows 10 system with Hyper-V in the “early days” of Kyma (around version 0.3/0.4) was only very limited fun. Several install scripts had to be adopted to make the installation pass. However, it was not only Kyma that gave you a hard time but also the installation of its foundation Minikube (I still have the impression that Windows was and is not the preferred OS for Minikube and, hence, when installing Kyma you suffered twice).

Then Kyma release 1.2 was released and the following promise was made:

As I think that Kyma is one of the hottest things out there when it comes to extensibility, I gave it a try to see if this is true.

To make a long story short (spoiler alert): yes, the Kyma community did a great job and there is much less to do around Kyma. However, the installation has some pitfalls (I have the feeling I came across every single one when it comes to Minikube, Windows 10, Hyper-V and Kyma, but maybe I am wrong), so I want to share my personal “best practices” for the installation of Kyma from scratch to make your journey to Kyma a smooth experience.

Nevertheless, this is no official documentation, so everything you do is at your own risk ?

Prerequisites

My Set Up

My OS is Windows 10 Pro Version 1903. It is running on Intel Nuke i7 with 32 GB of memory. Please be aware that the Kyma VM by default uses 8GB of RAM. I did not change that parameter, so before you start make sure that your hardware is sized right to start the Kyma journey. I also run Hyper-V for the virtualization, so this blog will not deal with the specifics of VirtualBox (which can also be used – I failed, but I also did not spend too much time in figuring out why). Hyper-V is supported for Windows 10 Professional, Enterprise and Education. It is not supported for Home edition. So please also check this prerequisite before you start.

Step 1 – Activating Hyper-V

As mentioned before, we start the journey from scratch, so let us first get the basic setup done. The first thing you must check is that VT-x/AMD-v virtualization is enabled in BIOS. The concrete location of the setting depends on your BIOS, so you might have to look a bit around.

If this condition is met, you must activate Hyper-V. To achieve this, go along the following steps:

1. Go to the app “Control Panel”.
2. Open “Programs and Features”.
3. Select “Turn Windows Features on or off” on the left-hand side of the menu.
4. Tick “Hyper-V” (root node, all sub-nodes should be ticked automatically) and click OK.
   

The system will ask you to reboot, which is necessary to activate the feature and which you must do. This will be the only point where a reboot is necessary

Step 2 – Virtual Switch

Next, you should create a dedicated virtual switch for your Minikube VM. To do so, start the “Hyper-V manager” app. Navigate to the “Virtual Switch Manager”

Create a new switch for you Minikube VM. I called it “minikube_switch”. I will use this identifier throughout the rest of the blog. The configuration finally looks like this (your might deviated with respect to the external network):

Now we have prepared the system with respect to the virtualization. The next step is to install the required software for Kyma.

Install the Software

Kyma comes with some prerequisites that are listed in the official documentation:

I personally recommend installing Chocolatey as a package manager for Windows in order to install and maintain the software in a comfortable manner. So let us first install Chocolatey. Open a Windows PowerShell as an Administrator and key in the following command:

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

That was it. Now let us install the required software via Chocolatey. Be aware that Kyma is a bit picky about software versions, so make sure that the versions meet the requirements. Having said that, I deviated from the Minikube version as 1.0 and 1.0.1 has some hiccups with Windows 10 and Hyper-V (surprise, surprise ?). The next best thing available was Minikube 1.1.1 (and this worked).

choco install minikube

choco install kubernetes-cli --version 1.12.1

choco install kubernetes-helm --version 2.10.0

choco install jq

choco install wget

The Kyma CLI has to be installed manually as described in the GitHub repo (available at https://github.com/kyma-project/cli). Do not forget to add the CLI to your PATH variable and check that you can call it.

So far so good, virtualization is set up, required software is installed: what comes next? Let us check if we can get Minikube itself running.

Starting up Minikube

Up to now, we have installed Minikube but that does not mean that it can be started up. Let us find out if this works without any Kyma specifics ( in case it does not, this makes it easier to identify the bug). Open a Windows PowerShell as an Administrator and key in the following command:

minikube start --vm-driver hyperv --hyperv-virtual-switch "minikube_switch"

This command tells Minikube to use Hyper-V as a driver for the VM and to make use of the virtual switch that we created before. If you are curious what happens behind the scenes you can also use this command:

minikube start --vm-driver hyperv --hyperv-virtual-switch "minikube_switch" --logtostderr -v7

This logs all the actions that take place when the Minikube is started to your console. You will see that a lot is happening there. This should run through without any problems. Nevertheless, you should be patient as this takes a while to finish. When Minikube is up (console output will tell you that) you can check its status via:

minikube status

Next, you should check one thing in the Hyper-V manager namely the setting of the dynamic memory allocation. Use the Hyper-V manager app as shown below to navigate to the settings of the virtual machine:

The setting for the “Dynamic Memory” should be disabled by default in the installed Minikube version (1.1.1), but better to be on the safe side. If this is not the case, you should disable it manually.

Now you must stop the Minikube VM in order to start the Kyma installation. Easier said than done as the command “minikube stop” will not work (it will time-out). The workaround is to issue the following commands:

minikube ssh
sudo poweroff

This is as far as I could find out a known issue and the only workaround (not too much Minikube love out there for Windows user 🙁 )

But if there is a workaround there is hope and we finally arrived at the point where we check how the promise of the Kyma CLI resolves as all prerequisites are met.

Edit 04.11.2019: In case you run into issues with respect to the supported version of kubernetes you can explicitly specifiy the version in the minikube start command e.g.

minikube start –vm-driver hyperv –hyperv-virtual-switch “minikube_switch”  –kubernetes-version v1.14.6

Installing Kyma

Good news – we are only two commands away from getting Kyma up and running. First, you must provide a fitting Kubernetes cluster on Minikube for Kyma. As we use Hyper-V as VM driver we must adopt the command from the official documentation a bit as by default it uses VirtualBox and not Hyper-V. So this is the command you need to make it work with Hyper-V and the virtual switch:

kyma provision minikube --vm-driver hyperv --hypervVirtualSwitch "minikube_switch"

The relevant point in this new installation is that you will be asked if the existing Minikube cluster should be removed. Agree with that as the configuration of the Kyma Minikube deviates from a vanilla Minikube e. g. with respect to the allocated memory of the VM.

At the end of the provisioning, your console should show the following output:

Attention: the screen not only shows success messages but also a task you must do before proceeding to the installation of Kyma on the cluster. Adopt your /etc/hosts file in accordance with the data shown in the screenshot (I did that via Visual Studio Code and had no issues, it just asked for Administrator permission when saving the changes – I think that editing this file was a bit tricky in my prior run, but I am not quite sure about that).

The next, long-awaited and last step is the installation of Kyma (yes up to this point everything was prework!). Key in the following command and the installation will kick off:

kyma install

There might be an error message that the installation of the component “Istio” failed (see screenshot below). You can ignore that as the software will be installed in the right sequence after that message:

Again, you need some patience – less than when starting Minikube, but it is not done in seconds).

Small remark: I recognized that the output in the console has some delay comparing it to the output of the kubectl logs (via: “kubectl logs -n kyma-installer -l name=kyma-installer”), but that is not an issue, just do not be surprised if you check them in parallel.

This also should run through smoothly and at the end of the installation you will see:

And I guess you like what you see – congratulations: You have a local installation of Kyma up and running now! You can log on to Kyma console (https://console.kyma.local) and enter the world of extensions with Kyma.

You can check what is running in the cluster via:

kubectl get pods -–all-namespaces

This leads to the following output (and an idea what took so long during the installation – quite some stuff is running here):

Shutting Down and Restarting Kyma

If you want to shut Kyma down, remember that you must do it via ssh into Minikube as mentioned above.

To restart Kyma after shutdown, use the “kyma provision” command, but this time do not(!) delete the existing cluster. Kyma will then spin up the existing Minikube VM with the preinstalled components.

What’s Next?

As Kyma is up and running, you can now dive into the examples (https://kyma-project.io/docs/root/kyma#examples-examples) and/or the material of the openSAP course that is located in the Kyma incubator repository (https://github.com/kyma-incubator/opensap).

Summary

The local installation of Kyma is quite some work. There are several pitfalls but they are basically due to the interplay of Minikube, Windows 10 and Hyper-V. I hope with this blog I could help you with your journey to a local Kyma installation without too much pain so that you can focus on the main stuff: how to extend applications with Kyma.

The promise of the Kyma project that the CLI makes the process of local installation easier is fulfilled, however, a bit more documentation e. g. with respect to the available options for the CLI and how to use them might lower the entry barrier even more (… but I think that is what pull requests are made for …).

What more is to say now than … Happy Kyma-ing!

Additional information

Here are some additional information and links that might be of interest in the context of Kyma, Minikube, Windows 10 and Hyper-V

• Microsoft official documentation for Hyper-V: https://docs.microsoft.com/en-US/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v
• Official page of the package manager “Chocolatey”: https://chocolatey.org/
• Overview of software available with Chocolatey: https://chocolatey.org/packages
• Official Kyma documentation: https://kyma-project.io/docs/root/kyma/
• Kyma CLI on Github: https://github.com/kyma-project/cli
• “Deep Dive” Kyma CLI:
  • In case you want to take a closer look into the default configuration, the CLI uses for the different OS take a look into the GitHub repo at https://github.com/kyma-project/cli/tree/07d1041389d1cb0b8a9e69cda40e3afa762bbc72/pkg/kyma/cmd/provision/minikube
  • If you want to check the available options (not flags) of the Kyma CLI take a look at this code: https://github.com/kyma-project/cli/blob/61bea1aada078bbb23d0fa6adae4b6520dde9f6c/pkg/kyma/cmd/provision/minikube/cmd.go