Technical Articles
Installing Kyma locally on Windows 10 – The not so hard way
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:
- Go to the app “Control Panel”.
- Open “Programs and Features”.
- Select “Turn Windows Features on or off” on the left-hand side of the menu.
- 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
Great stuff Christian. I tried installing Kyma locally on my 8GB mac but failed because of hardware. Kyma has come a long way and has tried to smoothen the process of installation on various cloud platforms. I was able to finally get it up and running on my GCP instance.
Overall installing is something from scratch teaches us so many things rather than just getting a fully ready system.
Thanks once again for sharing this important experience.
Nabheet thanks for sharing your experience.
Most of the developers in the kyma team are using kyma on minikube on a daily basis. We are all aware of the current resource limitation when running a kind of cloud infrastructure like kubernetes & kyma on a desktop pc or notebook.
On the other hand, we all love that kind of developer experience and easiness to work on a dedicated system, which you can easily carry with you. So we are continually working on to improve the developer experience using minikube. We will make the kyma installation even more modular in the future. Thus you as a user can decide which Kyma components you really need and probably just skip some of these when deploying kyma on a laptop using minikube.
In addition, we are going to provide some of the kyma components in different flavors. If you don’t need HA capabilities during the development phase, you can use the more lightweight flavor of these components.
And finally, we are also working with the community of all the components kyma is based on (Knative, ISTIO, Service Catalog, etc) to improve the overall developer experience. As an example, in newer releases the K8S service catalog will not require a dedicated etcd instances anymore, and with that reduce already the resource consumption (needed memory).
And like always saying, your feedback and feature wishes – and for sure PRs- are highly appreciated. All the channels for interaction can be found here: https://kyma-project.io .
Hi Nabheet,
thanks for your comment. Indeed in general, you learn more, when there are some obstacles in the way ... otherwise, it would be too boring 😉
Cheers
Christian
Hi Christian.
Thanks a lot for sharing your experience on installing Kyma on Windows 10.
What I can share from my side is, that running minikube on Windows is still something like a second class journey. Minikube runs fine on all Linux/Unix based operating systems, where container support is just built in. On Windows today it requires to install Hyper-V (consisting already of several components to install) which is a kind prerequisite to run docker natively on windows. But also be aware Hyper-V is not always smoothly cooperating with other virtualization software – sometimes generating even another set of problems.
We are all waiting for the new WSL 2 (Windows Subsystem for Linux), announced by Microsoft some weeks ago. WSL 2 will support containerization natively (which is not supported by WSL 1.x today), and with that, we will get to similar user experience for running Kyma on Windows as we have already today when working with Kyma on minikube on MacOS and Linux. So till WSL 2.0 is available any hints and best practices to overcome the current more complex installation steps on Windows are highly appreciated.
Running Kyma on minikube is just one way to work with it, especially during the development phase. But running Kyma on all different cloud providers is the other option, and with the next releases of the SAP Cloud Platform Extension Factory we will continuously increase the number of options there. We also have plans to extend the Kyma CLI, so that from the command line you can quickly provision a Kyma cluster running at the different hyperscalers. And all these new features might also find their way into the SAP Cloud Platform Extension Factory.
With Kyma we running an Open Development Process (not just Open Source), so like you said, any pull request is highly welcome. Besides that, any feature wishes, comments, questions, and also criticism is more than appreciated, whether these come from our colleagues at SAP or any other user, developer or customer in the community working with Kyma or SAP Extension Factory.
Our vision is to get to an excellent and productive developer experience when developing software around today’s business application and especially addressing all the daily obstacles when extending and customizing existing solutions while trying to address new business requirements or to improve the overall user or customer experience. And all this with providing freedom of choice to the developer and software architects and helping to address today’s software challenges wrapped up in the simple words “cloud native” (build-for-cloud, elasticity, e2e-monitoring, devops, resource and cost efficiency, federation, e2e-security etc.).
In other words, like one of my colleague is saying: “Let us make today’s complex things easier for all of us developers again.”
Hi Ralf,
thanks for the insights and what has to expected further down the road (and I am also looking forward to WSL 2 for native container support).
As you stated in the last sections: Kyma is running on an open development process and that is what you "feel" when you take a closer look at Kyma itself but also at its evolution - and that is basically what I like most about it.
I also couldn't agree more with your last statement - the focus when extending software must be on the business problem to solve not on complexities that add no business value to the solution.
Cheers
Christian
Hi Christian,
I'm really happy to see that you liked the Kyma CLI.
I like to point out, that we are currently adding more documentation, command by command, so that you can expect first improvements already in next release, see first ticket focussing on the "install" command. The misleading error message in the "Kyma install" command will be improved as well, see this ticket.
Thanks a lot for your feedback,
Andreas
Hi Andreas,
great to see that the stuff is already addressed and scheduled in your sprint backlog. Keep up the great work with Kyma!
Best regards
Christian
Hi Christian,
Great blog! - thanks for the detailed steps for Kyma setup.
I just followed your steps and completed with Kyma installation; I could see the message "Happy Kyma-ing" in the console after kyma install command.
But when I log in to https://console.kyma.local/ with credentials I see an error message on the browser saying "Ups.. Looks like Luigi was not configured. Please use Luigi.setConfig(config) function to configure Luigi"
Do you have any idea about this error message? am I missing anything here?
Thanks in advance,
Anil
Hi Anil,
I did not come across that issue up to now. Maybe the Slack channel of Kyma might be a place where folks can help you with that issue.
Best regards
Christian
Ok Christian, Thanks a lot!
Hey Christian,
Thanks a lot for the detailed steps.
The commands below are for linux, what about windows ?
Regards,
Anvesh
Hi Anvesh,
"minikube" is the general CLI for minikube, so the command
is available on Windows too. With the command you log onto your minikube VM, which is Linux. Hence, to shut down the VM you have to use the Linux command:
Best regards
Christian
Ok Got it...!
Thanks,
Christian
Hi Christian,
I didnt get any password after installation of kyma:
please help..
thank You!
Hi Rajiv,
this issue was fixed on the 27th of November 2019 and it will be available with the next version of the Kyma CLI (1.9.0).
FOr more info, please refer to the fix here: https://github.com/kyma-project/cli/pull/318
Cheers,
Borja
I've just just seen that the kyma CLI is now also available through Chocolatey
https://chocolatey.org/packages/kyma-cli
Hope it will come for Winget too 🙂
Hi Christian, I am facing the error unknown flag error while using the command below.
/> `kyma provision minikube --vm-driver hyperv --hypervVirtualSwitch "minikube_switch"`
/> `Error: unknown flag: --vm-driver`