Learn OpenShift with Minishift

The days of micro-managing users on a shared UNIX server are over. The modern system administrator deals with a cloud of ephemeral compute nodes and the scripts that orchestrate them. There are a few different implementations of this infrastructure model, and one of the most important is Red Hat OpenShift.

Learning how to navigate the cloud can seem daunting at first, especially given the inherent assumption that you have a cluster of computers to orchestrate. If you don't happen to have a spare data center at your disposal, you can sign up for an account on OpenShift.io, which provides you with an online hosted OpenShift 4 experience.

If that approach sounds overwhelming, though, there's an even easier way to log time in the cloud. Red Hat's web-based learn.openshift.com lab offers six separate courses, depending on what aspect of cloud management you need to learn. But if you're the kind of admin who wants to know how the cloud is built in the first place, and not just how to use it, then you need to start at a lower level.

That level is Minishift. This tool was created by the OKD community project, which was formed to separate the product that relies upon Red Hat's infrastructure from the technology available to everyone. This community is the upstream origin of OpenShift and their Minishift tool allows you to run a containerized single-node cluster so you can develop for Kubernetes on your local machine. Minishift and OpenShift 4 are very different, but Minishift is nevertheless a powerful introduction to the concept of running a cluster, creating projects, monitoring tasks, and maintaining a cloud infrastructure.

Ensure your machine supports virtualization

You can run both Kubernetes and Minishift on Linux or MacOS. This article uses Red Hat Enterprise Linux 8 (but practically any Linux distribution will do). If you're not currently running Linux, then see my article Introduction to Red Hat Enterprise Linux for tips on getting started with RHEL.

An important note: You should not attempt to follow along with this article in a virtual machine. Part of this exercise is to create a virtualized environment. Virtualization inside of virtualization is an advanced topic not officially supported by most virtualization environments.

Most modern computers have virtualization capabilities, but it never hurts to check. Open a terminal on your Linux system and type this command to search for virtualization CPU flags:

$ egrep --only-matching --word-regexp 'vmx|svm' /proc/cpuinfo

Intel CPUs with virtualization return vmx, and AMD CPUs return svm. If this command gives no output, then your CPU does not support virtualization (or you typed the command wrong, or you're using a non-Intel or non-AMD CPU, meaning you must adapt this article for your hardware).

Install the prerequisites

The native virtualization module in Linux is the Kernel-based Virtual Machine (KVM)—which is included in the mainline Linux kernel. This module provides your virtual machines access to your computer's physical CPU and RAM, so there's no need to install that functionality. However, you must add a few applications and the libraries they depend upon before installing Kubernetes and Minishift.

There is more to even virtual machines than just CPU and RAM. QEMU provides some of these additional capabilities. To install this tool on Red Hat Enterprise Linux or Fedora, run this command to install all available qemu-kvm packages:

$ sudo yum install qemu-kvm*

You also must install libvirt, a library that provides the rest of your system an API for virtualization. You can install libvirt directly, or you can install libvirt as part of the @virtualization-host-environment group on Red Hat Enterprise Linux. To install the entire group, enter the following:

$ sudo yum group install --with-optional \
virtualization-host-environment

After installing the library, no matter which method you chose, start and enable it with systemctl by running:

$ sudo systemctl enable --now libvirtd

Installing libvirt creates a new system group. You can see it yourself by typing:

$ grep libvirt /etc/group

By adding yourself to this new group, you can use the OKD toolchain without escalating privileges to root. Use the usermod command to append the group to your user attributes, and then the newgrp command to log into the new group by running:

$ sudo usermod -a -G libvirt seth
$ newgrp - libvirt
$ groups
seth wheel libvirt

Finally, you must install some container tools. You can use Podman or Docker. The Open Containers Initiative is working to diversify container runtimes, but for now, Docker is the default. Run the following to install Docker, set its permissions, and move it into place:

$ curl --location \
https://github.com/docker/machine/releases/download/v0.16.1/docker-machine-Linux-`uname -i` > \
~/Downloads/docker-machine
$ chmod +x ~/Downloads/docker-machine
$ sudo mv ~/Downloads/docker-machine /usr/local/bin/

Next, install the Docker KVM driver to manage Docker containers through the existing kernel hypervisor:

$ curl --location \
https://github.com/dhiltgen/docker-machine-kvm/releases/download/v0.10.0/docker-machine-driver-kvm-centos7 > \
~/Downloads/docker-machine-driver-kvm
$ chmod +x ~/Downloads/docker-machine-driver-kvm
$ sudo mv ~/Downloads/docker-machine-driver-kvm /usr/local/bin/

You now have all the components you need for your virtualization stack. At this point, you could spin up KVM-based containers manually, and manage them with tools like virsh and even GNOME Boxes. While doing so offers invaluable experience, this process doesn't scale as well as OpenShift.

Install Minishift

Minishift is distributed as a self-contained, pre-compiled binary. Like everything else this article has required so far, you can compile this tool from source code if you prefer, provided you have a Go development environment.

For the sake of simplicity, download the Minishift binary from the project's Github repository. Once downloaded, unarchive it and place it somewhere in your PATH like this:

$ wget -qO- \
https://github.com/minishift/minishift/releases/download/v1.34.0/minishift-1.34.0-linux-amd64.tgz \
| tar --extract --gzip --verbose -C ~/bin/

For convenience, run the following to create a symlink to the minishift executable:

$ ln --symlink \
~/bin/minishift-1.34.0-linux-amd64/minishift \
~/bin/minishift

Set up your single-node cluster

Minishift lets you provision and manage your single-node cluster. You can think of Minishift as your virtual infrastructure (though not the actual virtual machines themselves). This tool is optimized for development work, and should only be used for development work. A real OpenShift install requires the redundancy provided by many nodes, and the diversity provided by different kinds of nodes.

Now you can get started running Minishift to learn and to develop for it. The typical routine you'll find yourself repeating is the launch process: start Minishift, enable the oc command, and get to work.

To start Minishift, use the start parameter:

$ minishift start
-- Starting profile 'minishift'
-- Checking if https://github.com is reachable ... OK
-- Checking if KVM driver is installed ...
Driver is available at /usr/local/bin/docker-machine-driver-kvm ...
Checking driver binary is executable ... OK
-- Checking if Libvirt default network is active ... OK
-- Checking if provided oc flags are supported ... OK
-- Starting the OpenShift cluster using 'kvm' hypervisor ...
-- Starting Minishift VM ............
...output omitted...
-- Starting OpenShift cluster.........
...output omitted...

This process can take a long time, depending on your hardware, so be patient. In the end, you are left with information about where to find your imaginary cluster on your virtualized network:

Server Information ...
OpenShift server started.

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

The URL provided at the end of the process is a dynamically generated address, so it's probably different on your computer than the sample output here. Open a web browser on your local computer and navigate to this URL.

Because Minishift uses a self-generated SSL certificate, your browser will warn you that the connection is insecure. Click through the warnings to add an exception to permit access to this address and reach the Minishift login screen:

On a real install of OpenShift, one of your first tasks would be to either change the self-signed certificate to a CA-signed certificate, or to package your self-signed certificates and distribute them to your authorized users. For the purpose of local development and education, though, you can continue to use the self-signed certs.

Create a project

The web console is a good front-end to provide your developers so that they can create, deploy, and monitor applications. To get an idea of your developer experience, log into the web console using developer as the username and developer as the password.

The Minishift landing page offers an overview of the templates available for developers to use as the basis for new applications. However, before creating any application, a project must exist. The default developer profile can create projects, so click on the Create Project button on the web console's top right corner. Enter a name for the project, a display name, and a description, and then click Create.

Click the project name in the project list to enter its Overview panel.

From the project's Overview page, a developer can deploy existing images or build one from a template. To get a feel for the workflow, click the Browse Catalog button and select the basic Nginx template (available in either the All or Other tabs).

In the configuration window that appears, click the Try Sample Repository link to auto-fill the fields -filled with demo content from the OpenShift project's Github repository, and then click Create.

Once you've created the sample application, close the pop-up window and click the Overview tab on the left of the web console. In this tab, click the title of your new application to view its progress and state.  Allowing for some time for the application to be downloaded and built into a pod, the overview panel displays the URL to view the application, the existing route to it, and how many pods of the application to maintain.

Click the URL in the Routes section to view the sample application. It's not much to look at, but then again you've just successfully deployed an NGINX web server in all of two minutes!

There's a lot more to the web console, so send your developers (or yourself, if you walk the line of development and administration) to learn.openshift.com for an excellent, interactive walk-through of its many features.

Create a new application

OpenShift provides several means of interaction, including the web console, an API, and the oc command. If you're the administrator of a Minishift or OpenShift install, then the oc command is probably destined to be your primary interface.

To interact with Minishift from a terminal, you need to bring the oc toolchain into your working environment by running the following:

$ minishift oc-env
$ eval `minishift oc-env`

Then, log in as the admin:system user:

$ oc login -u system:admin

On a production OpenShift instance, you can manage user authentication in many different ways, including LDAP, Keystone, and oAuth. On MiniShift, however, you can easily mimic users. Log into your cluster with any username and password you please and a user is created to match.

For instance, you already logged into the web console using the developer username, so you can expect at least one user to exist. You can check by running:

$ oc get users
NAME       UID         FULL NAME IDENTITIES
developer  0c40...2f25              anypassword:developer

Your fake developer has also created a project, which you can view with oc projects.

The oc command can perform the same actions as the web console. To create a new project run the following:

$ oc new-project wednesday \
--display-name=Wednesday \
--description="Today's new project"

Create a new application within the project using a sample from OpenShift:

$ oc new-app \
centos/ruby-25-centos7~https://github.com/sclorg/ruby-ex.git

The oc command is helpfully verbose and tries to guide you through a probable workflow. For instance, after the sample application deploys, oc provides you with the commands to monitor its progress and status.

Learn more

Minishift is a local, single-node cluster. It's a powerful introduction to how the cloud is built and maintained. Install it now to get familiar with hybrid cloud technology, and then head over to try.openshift.com to apply the principles you've learned.