OpenShift

Getting started with oc cluster up/down

Posted admin

The same OpenShift code base can be deployed to a number of different form factors. These can include planet wide Public Cloud implementations, third party managed service offerings, a private owner-operated deployment on the company Intranet through to local installation on your own workstation. This makes for a very convenient platform for evaluating, learning and testing OpenShift based workloads. Skills developed on a local instance are transferable to more complex distributed topologies. We summarise one of the local installation options known as “oc cluster up/down“. So sit back and let Taffy with a little help from her friends show you how to get started on Linux, Mac OS/X or Windows 10 environments.  This lab is another in the OpenShift MiniLabs series.

taffy

Objective

Described are three approaches for starting and stopping a local OpenShift cluster such that system state is labelled ($PROFILE) and preserved upon restart. Windows 10 users new to OpenShift should consider the PowerShift option. Matters related to storage and creating and claiming volumes are covered in Storage Made Easy with OpenShift. Check the Troubleshooting section at end of this page if you encounter any issues. Described here are:

  1. Direct invocation using the oc CLI – oc cluster up/down
  2. The convenience wrapper tool known as oc-cluster-wrapper – Linux only
  3. The Python based convenience tool known PowerShift – Linux or Windows 10

Setup

oc client tools

All approaches require that the oc client tools are installed on your system. This is a matter of downloading the oc distribution and ensuring the oc executable is visible on your path. This varies across operating systems. The various oc releases are downloadable from https://github.com/openshift/origin/releases. You can experiment with different releases by just changing which version of the oc binary appears on your path. Expanded installation instructions can be reviewed at: at https://docs.openshift.com/enterprise/3.2/cli_reference/get_started_cli.html. You can verify your setup on a Linux, Mac OS/X  or Windows 10 PowerShell terminal session as per below. Your output may vary.

$ which oc
/usr/local/bin/oc

$ oc version
oc v3.6.0+c4dd4cf
kubernetes v1.6.1+5115d708d7
features: Basic-Auth

Server https://127.0.0.1:8443
openshift v3.6.0+c4dd4cf
kubernetes v1.6.1+5115d708d7

Docker

By default, “oc cluster up” requires a working Docker connection and so you will be needing Docker installed in your workstation.  Choose Docker for Windows or Docker for Mac where available. The system state saving (profiling) feature described later assumes a native Docker installation and so is not available when using a Docker Machine (e.g. as via Docker Toolbox).

Check the oc cluster up/down website for specific configuration instructions for your environment. You may also be prompted later to add an entry to the insecure_registries, e.g. 172.30.0.0/16. For Docker for Mac, these can be both configured using the Preferences GUI.  Once installed, verify docker is functioning before proceeding. Note that if you will be attempting more memory intensive use cases, increase the assigned memory for Docker. Try starting and stopping a cluster before proceeding. The first attempt may take a few minutes as it downloads the OpenShift Origin distribution.

$ docker version
$ docker run hello-world
$ oc cluster up
$ oc cluster down

Mac OS/X users who hit a “socat” missing executable problem may want to visit and review guidance at http://macappstore.org/socat/ and then retry above.

nip.io

Resolving routing end points of applications created using a local OpenShift instance depend on the nip.io magic domain name. Check that your workstation has Internet connectivity and that nip.io is not blocked by your service provider. From time to time you may want to flush your DNS. Google appropriate instructions for your operating system. For example on Windows 10 it would be “ipconfig /flushdns” while for Mac OS/X (Sierra) try “sudo killall -HUP mDNSResponder”.

$ nslookup 127.0.0.1.nip.io
Server:  61.9.195.193
Address: 61.9.195.193#53

Non-authoritative answer:
Name: 127.0.0.1.nip.io
Address: 127.0.0.1

Python

Optionally, if you intend to use the powershift tool described later, you will need Python 3.5 or later.  Installers for Python can be sourced from the Python Software Foundation (PSF) at: https://www.python.org/downloads/. Follow the operating system specific instructions for Python and then verify that the correct version is accessible on your path. Tested combinations for oc/Python are v1.3.x/v3.5.x or v1.4.x/v3.6 respectively.

$ python --version
Python 3.5.2

Instructions

For the following instructions, replace $HOME to reflect your operating system and $PROFILE to denote your labelled profile as necessary, e.g.:

  • HOME=/Users/johndoe
  • PROFILE=containersascode

1. oc cluster CLI

Direct invocation examples using the oc CLI are described below. Expanded installation instructions are at https://github.com/openshift/origin/blob/master/docs/cluster_up_down.md#overview. The following assumes a native Docker installation as we are going to showcase saving system state via a named profile. The oc cluster up switch –create-machine is therefore not used.

Linux/Mac OS/X

On linux, the OpenShift Console will be accessible at http://127.0.0.1:8443/console once started.

Starting First Time

$ oc cluster up \
   --public-hostname='127.0.0.1' \
   --host-data-dir=$HOME/.oc/profiles/$PROFILE/data \
   --host-config-dir=$HOME/.oc/profiles/$PROFILE/config \
   --use-existing-config

Stopping

$ oc cluster down

Windows

On Windows, the OpenShift Console will be accessible at an IP addressed that is published to the terminal session during startup, for example, http://10.0.75.2:8443/console.

Starting First Time

$ oc cluster up ^
   --host-data-dir='/c/$HOME/oc/profiles/$PROFILE/data' ^
   --host-config-dir='/c/$HOME/oc/profiles/$PROFILE/config' ^
   --use-existing-config

Stopping

$ oc cluster down

Using the Red Hat Registry

The “oc cluster up” command uses the OpenShift Origin (upstream) repository by default. An advantage of this direct CLI method is that you can access additional runtime switches. For example, if you wish to point to the Red Hat supported registry as an image source you can do so by adding the following options to the “oc cluster up” commands described above.

   --image=registry.access.redhat.com/openshift3/ose \
   --version=v3.4 \

2. oc-cluster-wrapper for Linux/Mac OS/X only

This is a convenience tool tested for Linux and Mac OS/X that wraps useful oc cluster commands. A profile ($PROFILE) saving system system state will be created at: $HOME/.oc/profiles/$PROFILE

Installation

Clone down the repo and add the oc-cluster tool to your path. Check https://github.com/openshift-evangelists/oc-cluster-wrapper for expanded details and installation instructions. Verify using:

$ oc-cluster list

(Re)Starting

The OpenShift Console will be accessible from the URL as indicated below. If $PROFILE is not specified default is assumed.

$ oc-cluster up $PROFILE
$ oc-cluster console

Stopping

$ oc-cluster down

3. PowerShift for Linux, Mac OS/X and Windows

This Python based tool will work on Linux, Mac OS/X or Windows 10 (tested using PowerShell). Check https://github.com/getwarped/powershift-cluster for details and authorship. A profile ($PROFILE) saving system system state will be created at $HOME/.powershift/profiles/$PROFILE (Linux) or $HOME/PowerShift/profiles/$PROFILE (Windows).

Installation

Ensure that the correct version of Python is functioning then install as follows:

$ python --version
$ pip3.5 install powershift-cluster
$ powershift --help

(Re)Starting

The Browser based OpenShift Console will be launched at a URL formed for your operating system via the “console” call as per below.

$ powershift cluster up $PROFILE
$ powershift console

Stopping

$ powershift cluster down

Updates

PowerShift is always being improved. Update your version from time to time using:

pip install -U powershift-cluster

Verify Success

Whichever approach you prefer you can verify your environment and OpenShift profile behaviour with the following steps.

  1. Start the OpenShift cluster with a specific labelled profile
  2. Create an application
  3. Stop the OpenShift cluster
  4. Restart the OpenShift cluster with the same labelled profile
  5. Verify the application is preserved

Starting, stopping and restarting the OpenShift cluster have already been covered. To create an application do as per below. Replace $IP-ADDRESS, e.g. 10.0.75.2, as appropriate for your cluster instance in your operating system.

Note that on your first attempt, it may take a few minutes for all of the (source-to-image) catalog including the php templates (5.6, 5.6) to be downloaded. You can browse progress by refreshing the catalog on the Console.

$ oc login -u developer -p developer
$ oc project myproject
$ oc new-app --name='cotd' -l name='cot' php~https://bitbucket.org/emergile/cotd.git
$ oc expose service cotd --name=cotd -l name='cotd'
$ oc status 
$ curl http://cotd-myprojevt.$IP-ADDRESS.nip.io/item.php

Trivia

Go and star the great work being down at https://github.com/getwarped/powershift-cluster and https://github.com/openshift-evangelists/oc-cluster-wrapper GitHub repos.

Appendix

Troubleshooting

github.com not reachable

Experiencing a “cannot resolve github.com” during build error? To fix, try changing the DNS entry to 8.8.8.8 (only). Mac OS/X users can do this by visiting System Preferences>Network>Wi-Fi>Advanced>DNS. To verify, oc cluster down, restart Docker, then oc cluster up and try a rebuild. Another remedy may be to remove the –public-hostname switch from your cluster start command invocation.

Windows 10 Profiles/Persistance fails for v1.3+

Some weirdness has recently crept into later versions of the oc client which appears to break the profile/persistence support on Widows 10. If you encounter such a problem revert to oc v1.3.0.

The Docs

Hitting some other mischief? Check out the troubleshooting guide at https://github.com/openshift/origin/blob/master/docs/debugging-openshift.md and https://github.com/openshift/origin/issues/10139.

Mac Stuff

If you have set up Docker for Mac with “Automatic Updates” (not recommended) you may experience an “oc cluster up”  breakage from time to time. To recover revert back to the best last known working Docker release. Downloading prior releases requires knowledge of the  URL of the specific release of interest, e.g. https://download.docker.com/mac/stable/1.12.6.14937/Docker.dmg. For more on this check https://github.com/docker/for-mac/issues/1120 .

Some other useful resources on OpenShift are collated here. Mac users should check here too https://blog.switchbit.io/openshift-cluster-up-with-docker-for-mac/ if they run into difficulties. It is a good idea to factory reset your local Docker environment from time to time.  Disk space reserved for image repositories can grow significantly and may not be released and reclaimed effectively. Mac OS/X users can view logs by, e.g. typing “Docker” into the search criteria for the system.log using the Console application found in /Applications/Utilities.

Bash for Windows

You may also wish to experiment in this shell. Have tested this configuration on Windows 10 (Intel NUC) after downloading and copying across a 64bit oc executable to the /usr/local/bin location. Note that when using oc commands such as “oc login”, you may need to pass the OpenShift server location, e.g. 10.0.75.2:8443. Start and stop the OpenShift cluster from the PowerShell (due to Docker for Windows support) and then proceed to Bash for executing instructions. When switching to Bash, you will find your C: directory at /mnt/c.

Occasions where you might prefer Bash for Windows over PowerShell include when you need to execute commands that contain Windows unfriendly characters such as:

  1. “oc patch” CLIs may be “fragile” due to issues with PowerShell interpreting delimiters and the ‘ character;
  2.  copying/pasting Linux like command line instructions from the MiniLabs, e.g. “$ while … ; done”

Ubuntu

Google up the official installation instructions for setting up docker for Ubuntu. To set the insecure-registry check http://developmentalmadness.com/2016/03/09/docker-configure-insecure-registry-for-systemd/. After that instructions are as per Linux variants.

Changing oc Versions

If you experience some “oc cluster up” weirdness after upgrading your oc CLI version, consider resetting Docker and just starting again. When you do make sure you update the insecure registries setting as described in the Setup section, memory and any shared folder locations.

Vagrant

But wait there’s more. You can also choose to use the upstream origin all-in-one (vagrant) virtual machine as a fourth technique for launching a local cluster. Another source for an all-in-one image is http://developers.redhat.com .

MiniShift

But wait there’s more more. Check out progress on the MiniShift project at https://github.com/minishift/minishift from time to time. For a quick tour try the steps below, as verified on a Mac OS/X, Sierra. Replace MINISHIFT-IP for that returned in your environment. If you run into difficulties, delete the $HOME/.minishift directory and try again. We will have a lot more to say in the first half of 2017, including reproducing the saving system state as a named profile feature described above.

$ brew cask install minishift

$ minishift start \  --vm-driver virtualbox \  --skip-registry-check \  --memory 4098 $ oc login -u developer -p developer $ oc project myproject $ oc new-app php:5.6~https://bitbucket.org/emergile/cotd.git --name cotd $ oc expose service cotd $ minishift ip $ curl cotd-myproject.$MINISHIFT-IP.nip.io $ minishift console $ minishift stop

OpenShift Online V3 Preview

But why stop there. Many of the labs do not require admin access and so can also be completed using the OpenShift (V3) Cloud based service known as OpenShift Online. This was on preview release status as at December 2016. The first thing to do is to visit the main OpenShift landing page and follow the links to grab yourself a free (preview) account. Once your account is enabled, revisit the OpenShift  website to find and then login to the Console.  The instructions to use the CLI are here. From the CLI, create a project and application to verify all is OK.

$ oc login https://api.preview.openshift.com --token=YOUR-TOKEN
$ oc new-project myproject
$ oc new-app --name='cotd' -l name='cotd' php~https://bitbucket.org/emergile/cotd.git
$ oc expose service cotd
$ curl http://cotd-myproject.44fs.preview.openshiftapps.com/item.php

Leave a Reply