Home Cloud How to run Local Openshift Cluster with Minishift

How to run Local Openshift Cluster with Minishift

April 16, 2019

(Last Updated On: April 16, 2019)

This article has been written to walk you through the simplest way to get a running Openshift OKD environment on a Linux system. If you’re unfamiliar with the core concepts of OKD, don’t worry as this guide is easy to follow and doesn’t need prior understanding of Openshift Container platform.

In our previous guide, we covered the installation of Openshift Container platform on Ubuntu. This round, we will focus on a generic way of running a Local Openshift cluster on any Linux system.

What is Minishift?

Minishift is an open source tool that helps you run a single-node OpenShift cluster locally inside a VM. You can try out OpenShift or develop with it, day-to-day, on your local host.

Minishift requires a hypervisor to start the virtual machine on which the OpenShift cluster is provisioned. We will start with the installation of hypervisor of your choice before Minishift setup.

Step 1: Install Hypervisor

For Linux users, the common hypervisor choices are KVM and VirtualBox. Check below guides:

How to Install VirtualBox on Fedora, Kali Linux, Linux Mint, Ubuntu 18.04/16.04/Debian 9

How to install KVM on RHEL/CentOS 8, Fedora, Arch Linux, CentOS, Ubuntu/Debian, SLES

Step 2: Setting up Minishift hypervisor Driver

Minishift embeds the VirtualBox driver plug-in, so no additional steps are required to configure it. However, KVM users needs to manually install the driver plug-in.

Install KVM Driver ( For KVM users)

For Fedora / CentOS

sudo usermod -a -G libvirt $(whoami)
newgrp libvirt || newgrp libvirtd
curl -L https://github.com/dhiltgen/docker-machine-kvm/releases/download/v0.10.0/docker-machine-driver-kvm-ubuntu16.04 -o docker-machine-driver-kvm
sudo mv docker-machine-driver-kvm /usr/local/bin/docker-machine-driver-kvm
sudo chmod +x /usr/local/bin/docker-machine-driver-kvm

For Ubuntu / Debian

sudo usermod -a -G libvirtd $(whoami)
newgrp libvirt
curl -L https://github.com/dhiltgen/docker-machine-kvm/releases/download/v0.10.0/docker-machine-driver-kvm-centos7 -o docker-machine-driver-kvm
sudo mv docker-machine-driver-kvm /usr/local/bin/docker-machine-driver-kvm
sudo chmod +x /usr/local/bin/docker-machine-driver-kvm

For Arch Linux / Manjaro

sudo usermod -a -G kvm,libvirt $(whoami)
sudo sed -ri 's/.?group\s?=\s?".+"/group = "kvm"/1' /etc/libvirt/qemu.conf
newgrp libvirt
curl -L https://github.com/dhiltgen/docker-machine-kvm/releases/download/v0.10.0/docker-machine-driver-kvm-centos7 -o docker-machine-driver-kvm
sudo mv docker-machine-driver-kvm /usr/local/bin/docker-machine-driver-kvm
chmod +x /usr/local/bin/docker-machine-driver-kvm

Start the default KVM network.

sudo virsh net-start default
sudo virsh net-autostart default

Step 3: Install Minishift

Download the archive for your operating system from the Minishift Releases page and extract its contents.

export VER="1.33.0"
curl -L https://github.com/minishift/minishift/releases/download/v$VER/minishift-$VER-linux-amd64.tgz -o minishift-$VER-linux-amd64.tgz
tar xvf minishift-$VER-linux-amd64.tgz

Add the minishift binary to your $PATH environment variable.

sudo mv minishift-$VER-linux-amd64/minishift /usr/local/bin

Confirm installation.

$ minishift version
minishift v1.33.0+ba29431

Step 4: Starting Minishift

We have all the required dependencies installed and we’re ready to start a single node Openshift cluster using Minishift. Please note that this cluster is optimized for development workflows.

The following steps describe how to get started with Minishift on a Linux operating system with the KVM hypervisor driver.

1.. Run the minishift start command:

$ minishift start

This will do a number of check then provision Minishift VM with below configurations:

Memory: 4 GB
vCPUs : 2
Disk size: 20 GB

Sample output:

-- Starting Minishift VM .................. OK
-- Checking for IP address ... OK
-- Checking for nameservers ... OK
-- Checking if external host is reachable from the Minishift VM ... 
   Pinging 8.8.8.8 ... OK
-- Checking HTTP connectivity from the VM ... 
   Retrieving http://minishift.io/index.html ... OK
-- Checking if persistent storage volume is mounted ... OK
-- Checking available disk space ... 1% used OK
-- Writing current configuration for static assignment of IP address ... WARN
   Importing 'openshift/origin-control-plane:v3.11.0'  CACHE MISS
   Importing 'openshift/origin-docker-registry:v3.11.0'  CACHE MISS
   Importing 'openshift/origin-haproxy-router:v3.11.0'  CACHE MISS
-- OpenShift cluster will be configured with ...
   Version: v3.11.0
-- Pulling the OpenShift Container Image ................................................ OK
-- Copying oc binary from the OpenShift container image to VM ... OK
-- Starting OpenShift cluster .........................................................................................
Getting a Docker client ...
Checking if image openshift/origin-control-plane:v3.11.0 is available ...
Pulling image openshift/origin-cli:v3.11.0
..........................................
Login to server ...
Creating initial project "myproject" ...
Server Information ...
OpenShift server started.

The server is accessible via web console at:
    https://192.168.42.106:8443/console

You are logged in as:
    User:     developer
    Password: <any value>

To login as administrator:
    oc login -u system:admin


-- Exporting of OpenShift images is occuring in background process with pid 11207.

If you’re running VirtualBox, use the --vm-driver virtualbox flag when starting Minishift VM.

$ minishift start --vm-driver virtualbox

To persistent configuration so that you to run minishift start without explicitly passing the –vm-driver virtualbox flag each time, run:

$ minishift config set vm-driver virtualbox

The IP is dynamically generated for each OpenShift cluster. To check the IP, run the minishift ip command.

Accessing Openshift

You can access your newly deployed Openshift cluster from the web console or CLI. For access from web console, use the URL shown after cluster start.

The server is accessible via web console at:
    https://192.168.42.106:8443/console

You can run this command in a shell after starting Minishift to get the URL of the Web console:

$ minishift console --url
https://192.168.42.106:8443/console

Alternatively, after starting Minishift, you can use the following command to directly open the console in a browser:

$ minishift console
Opening the OpenShift Web console in the default browser…
 [16398:16398:0416/224729.206639:ERROR:sandbox_linux.cc(364)] InitializeSandbox() called with multiple threads in process gpu-process.
 [16359:16381:0416/224729.313961:ERROR:browser_process_sub_thread.cc(209)] Waited 5 ms for network service
 Opening in existing browser session.

To login as administrator, use:

Username: system
Password: admin

For operation of Openshift from CLI, proceed to step 5.

Step 5: Install OpenShift Client Binary (oc)

The minishift start command creates an OpenShift cluster and copies the ocbinary onto your host. This binary is located in the ~/.minishift/cache/oc/v(VER) directory. We need to copy it to /usr/local/bin for all users to access it.

sudo cp ~/.minishift/cache/oc/v3.11.0/linux/oc /usr/local/bin

Alternatively, you can add this binary to your PATH using minishift oc-env, which displays the command you need to type into your shell.

$ minishift oc-env
export PATH="/home/jmutai/.minishift/cache/oc/v3.11.0/linux:$PATH"

# Run this command to configure your shell:
# eval $(minishift oc-env)

Check if it is working.

$ oc version
oc v3.11.0+0cbc58b
kubernetes v1.11.0+d4cacc0
features: Basic-Auth GSSAPI Kerberos SPNEGO
Server https://192.168.42.106:8443
kubernetes v1.11.0+d4cacc0

This tells you the server IP address and port. To login as administrator, use the system account:

$ oc login -u system:admin
Logged into "https://192.168.42.106:8443" as "system:admin" using existing credentials.
 You have access to the following projects and can switch between them with 'oc project ':
 default kube-dns kube-proxy kube-public kube-system
 myproject
 openshift
 openshift-apiserver
 openshift-controller-manager
 openshift-core-operators
 openshift-infra
 openshift-node
 openshift-service-cert-signer
 openshift-web-console 
 Using project "myproject".

The client certificates used for access are stored in ~/.kube/config

To view the available login contexts, run:

$ oc config view
 apiVersion: v1
 clusters:
 cluster:
 certificate-authority-data: REDACTED
 server: https://192.168.42.106:8443
 name: 192-168-42-106:8443
 contexts:
 context:
 cluster: 192-168-42-106:8443
 namespace: myproject
 user: developer/192-168-42-106:8443
 name: minishift
 context:
 cluster: 192-168-42-106:8443
 namespace: myproject
 user: developer/192-168-42-106:8443
 name: myproject/192-168-42-106:8443/developer
 context:
 cluster: 192-168-42-106:8443
 namespace: myproject
 user: system:admin/192-168-42-106:8443
 name: myproject/192-168-42-106:8443/system:admin
 current-context: myproject/192-168-42-106:8443/system:admin
 kind: Config
 preferences: {}
 users:
 name: developer/192-168-42-106:8443
 user:
 token: QdSKNK5DbaLA2AOFM__8-_fJ-Pt7BikZP1uFwsqyNx0
 name: system:admin/192-168-42-106:8443
 user:
 client-certificate-data: REDACTED
 client-key-data: REDACTED

How to stop Minishift

To stop your Openshift cluster and Minishift VM, run:

$ minishift stop
Stopping the OpenShift cluster…
Cluster stopped.

You can restart OpenShift cluster at any time by running

$ minishift start