Setup OpenShift on Windows
Red Hat OpenShift is a container application platform that brings docker and Kubernetes to the enterprise. You can think of OpenShift as an operating system, images as applications that you run on them, and the containers as the actual running instances of those applications. For developers, OpenShift comes with the ability to run a production like environment on their local machine. Thus, testing of new features and fixes becomes easy and more reliable.
However, the first time setup is not that easy. This guide helps you to bypass common pitfalls installing OpenShift on your local machine.
Prerequisites
OpenShift is designed to run on Unix operated systems. Therefore, running OpenShift using MS Windows requires a virtual machine. We will use Hyper-V since it is shipped with almost any Windows 10 installation. Maybe you will have to enable Hyper-V on your machine. To do so, please refer to the Microsoft documentation. In addition, you will need to create a Virtual Switch using the Hyper-V Manager.
Finally, you must set the environment variable HYPERV_VIRTUAL_SWITCH
to the Virtual Switch’s name:
1 |
$ set HYPERV_VIRTUAL_SWITCH=External (Wireless) |
Using the Command Prompt, you must not use quotes. If you are using PowerShell, you need to use quotes.
Please be aware that the Virtual Switch is bound to a concrete network adapter. If you change the network you are connected to (for example from LAN to W-LAN) you will have to create another Virtual Switch and reset the value in HYPERV_VIRTUAL_SWITCH
.
The VM for running OpenShift will required a minimum of 2GB of RAM. However, I would recommend attaching at least 4GB – depending on the number and kind of containers you want to run.
Minishift
Minishift is a tool that helps you run OpenShift locally by running a single-node OpenShift cluster inside a VM. You can download the latest Minishift binaries from GitHub. When writing this article the current release version is 1.16.1.
Extract the contents of the archive to any directory on your machine. Please note that due to an unresolved issue, you need to place the Minishift binary on the same local drive as your Windows installation (this is most likely C:). You cannot run Minishift from a network drive. Add the Minishift binary to your PATH environment variable.
Minishift will use any SSH binary found on the PATH in preference to internal SSH code. Ensure that any SSH binary in the system PATH does not generate warning messages, as this will cause installation problems.
Start your OpenShift cluster
So, finally we are ready to start our OpenShift cluster:
1 |
$ minishift start |
Make sure that you are running your console as administrator (use “run as administrator” when starting the console). If everything goes fine, Minishift creates and starts new virtual machine, pulls and runs the latest OpenShift docker image within that VM. Depending on your internet connection, the first start will take some minutes. When the OpenShift cluster was successfully started, you should see the following lines in your console:
1 2 3 4 5 6 7 8 9 10 11 |
OpenShift server started. The server is accessible via web console at: https://192.168.2.159:8443 You are logged in as: User: developer Password: <any value> To login as administrator: oc login -u system:admin |
Now, you can copy the link and access the web console for example. Username and password are printed only on first start.
Your first app
To test my setup I will create a simple hello world application:
1 2 3 |
$ oc login -u system:admin $ oc new-app openshift/hello-openshift $ oc expose svc/hello-openshift |
oc login
connects you to your cluster. By default, you are now using project ‘myproject’. A project is used to group a couple of related applications.oc new-app
creates a new application, pulls the given docker image and starts a container for that image. To make the application available for others we need to create a so called service usingoc expose
(A service serves as an internal load balancer in order to proxy the connections it receives to one or more containers). This should only take some seconds. You can test your first application using curl (or the web browser):
1 2 |
$ curl -s http://hello-openshift-myproject.192.168.2.159.nip.io/ Hello OpenShift! |
That’s it! Now, you can run all your apps on your local machine in your own OpenShift cluster.
Troubleshooting
I already tried to note all possible mistakes and traps in the setup. However, if you are facing any problems, have a look at my troubleshooting compendium.
Changing your network
This is probably the nastiest issue. When starting Minishift for the first time the OpenShift setup creates some certificates that are bound to your current IP address. Now, if you change the network you are connected to (just assume you pick your laptop and go home), the virtual machine is certainly not going to boot again:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
$ minishift start Starting OpenShift using openshift/origin:v3.9.0 ... -- Starting OpenShift container ... Starting OpenShift using container 'origin' Waiting for API server to start listening FAIL Error: cannot access master readiness URL https://192.168.2.158:8443/healthz/ready Details: Last 10 lines of "origin" container log: W0504 16:05:24.219585 2747 docker<em>sandbox.go:340] failed to read pod IP from plugin/docker: Couldn't find network status for through plugin: invalid network status for I0504 16:05:24.281898 2747 controller</em>utils.go:1019] Waiting for caches to sync for scheduler controller I0504 16:05:24.374928 2747 logs.go:41] http: TLS handshake error from 192.168.2.134:59218: remote error: tls: bad certificate Caused By: Error: Get https://192.168.2.158:8443/healthz/ready: x509: certificate is valid for 127.0.0.1, 172.18.0.1, 172.20.10.4, 172.30.0.1, not 192.168.2.158 Error during 'cluster up' execution: Error starting the cluster. |
There is no solution yet. A workaround could be to start Minishift using different profiles, e.g. ‘home’ and ‘office’ (A profile is an isolated instance of the Minishift VM. Each Minishift profile is created with its own configuration regarding memory, CPU, disk size, and so on). This works for me. However, you will have to install all your apps twice.
Hyper-v commands have to be run as an Administrator
Missing administrator privileges you might see this error when starting Minishift:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
$ minishift start -- Starting profile 'minishift' -- Checking if https://github.com is reachable (using proxy: "No") ... OK -- Checking if requested OpenShift version 'v3.9.0' is valid ... OK -- Checking if requested OpenShift version 'v3.9.0' is supported ... OK -- Checking if requested hypervisor 'hyperv' is supported on this platform ... OK -- Checking if Hyper-V driver is installed ... OK -- Checking if Hyper-V driver is configured to use a Virtual Switch ... 'External VM Switch (W-LAN)' ... OK -- Checking if user is a member of the Hyper-V Administrators group ... OK -- Checking the ISO URL ... OK -- Checking if provided oc flags are supported ... OK -- Starting local OpenShift cluster using 'hyperv' hypervisor ... -- Minishift VM will be configured with ... Memory: 2 GB vCPUs : 2 Disk size: 20 GB -- Starting Minishift VM ..... FAIL E0427 11:38:06.709969 16780 start.go:369] Error starting the VM: Error creating the VM. Error with pre-create check: "Hyper-v commands have to be run as an Administrator". Retrying. Error starting the VM: Error creating the VM. Error with pre-create check: "Hyper-v commands have to be run as an Administrator" |
Make sure to start your console using the “run as administrator” command. If there error does not go away, maybe a look into Minishift documentation might help you.
Insufficient memory
The default Minishift setup initializes the virtual machine with only 2 GB of memory. Starting a couple of services might quickly get you running out of memory. An indicator for that issue can be a service that is circularly crashing when starting or deploying.
You can fix this by increasing the memory in Hyper-V Manager (the VM needs to be stopped). You could also set the memory limit when starting Minishift for the first time:
1 |
$ minishift start --cpus 3 --memory 8096 |
For more options have a look at the Minishift documentation.
Connecting to the Minishift VM
Sometime you might need to alter the OpenShift installation – an issue might be missing permissions on the file system. To do so, you can connect into the Minishift VM by simply typing minishift ssh
.
Further reading
If you still have problems, try to have a look at Minishift’s getting started guide or the Minishift troubleshooting pages.