IBM Security Verify

 View Only

OpenShift on MacOS

By Jon Harry posted Fri August 09, 2019 07:11 AM



For the last couple of days I've been trying to get a development instance of OpenShift working natively on my Mac.  There are quite a few articles about this but most of them are from a while ago and didn't work for me.  I thought I would write up my experience for others that are trying to get started with this platform.

I'm running on a Mac with 16GB RAM and SSD.  I'm not sure it would be possible to run OpenShift on anything smaller.

You will need port 8443 to be available on localhost (
You will need ports 80 and 443 to be available on all IP addresses (this is where the OpenShift router listens).

OpenShift 3.x vs. OpenShift 4.x

The first thing I discovered is that there are two versions of OpenShift.  OpenShift 4.x is the latest version but, as far as I can tell, there isn't any way to get it running as an all-in-one deployment on a workstation.  OpenShift 4.x is designed to run exclusively on RedHat Enterprise Linux CoreOS and, as such, can't run natively on other platforms.  I'm sure it could run under virtualization but I get the impression it mandates separate OS installs for Master and Worker nodes which would require more resources than I have available on my workstation.

OpenShift 3.x can run inside Docker containers and works with any x86_64 OS with a supported version of Linux-kernel Docker (>=1.12).  There's also an Open Source upstream version of OpenShift 3.x which is OKD (a.k.a OpenShift Origin).  This can be used to create an all-in-one deployment for development and learning purposes.

MiniShift vs. "oc cluster up"

There are a few ways to run OpenShift Origin.

OKD provides a VM-based deployment called MiniShift.  This downloads and runs a Linux VM which includes Docker and OKD components pre-installed and configured.  Running MiniShift requires a supported hypervisor for the platform you're using.  It supports hyperkit, Virtual Box, and VMWare Fusion on MacOS.  It's easy to get running but it doesn't share the docker images (or docker environment) with the host machine.  It also has more isolated networking because its running in a Virtual Machine.

The option I went with is running a containerized version of OpenShift Origin on Docker Community Edition running on my Mac.  Granted, this still involves a hypervisor layer (to get the Linux kernel) but it is part of the Docker Community Edition install and seems very lightweight.  It also means my OpenShift deployment shares images with native Docker.  This containerized version of OpenShift Origin is provided by the Openshift 3.x oc command.  The command to start it is "oc cluster up" (hence the name).  The OKD documentation doesn't mention support of MacOS.  Perhaps that's the reason I had some issues getting it to work.

Setup Steps

Install Docker Community Edition

Using "oc cluster up" with the latest versions of Docker Community Edition mostly works but there is a strange, unaddressed, issue related to proxies.  To allow containers to pick up changes to system proxy information without restarting Docker, the recent versions of Docker Community Edition on Mac inject proxy definitions (docker.gateway.internal) into all containers.  This cannot be disabled and breaks OKD ability to access its internal image registry.

You can use the latest versions of Docker Community Edition if you only want to consume published images (for installation of IBM Security Verify Access for example) but it will not work if you want to write and consume images using the internal registry.  This latest version can be downloaded here.

If you want to have a fully working OpenShift system (where you can build applications from source or use Image Streams) then you need to use an old version of Docker Community Edition.  I use version Version 17.09.1-ce-mac42 (21090).  The install disk image (.dmg) for this old version can be downloaded here.

Configure Docker Community Edition

Once you have Docker Community Edition installed, you need to configure it.  There are a few changes to make.  These changes are made in "Preferences..." of the Docker app.  You must save and apply changes (which restarts Docker) on each tab.

If you're using an old version of Docker CE, disable "Automatically check for updates" in the General tab.  Otherwise Docker will keep asking you to update.


In the Advanced tab, increase memory usage to 8GB.  The default 2GB isn't enough to run OpenShift Origin.

In the Daemon tab, add to the insecure registries list.  This allows docker to pull images from the OpenShift built-in image registry.

In the latest versions of Docker Community Edition, insecure registries are configured by adding the following line into the JSON of the configuration file:

{ "insecure-registries": [ "" ] }

Create /var/lib/kubelet/device-plugins directory

When running "oc cluster up", the origin container attempts to mount the /var/lib/kubelet/device-plugins directory from the host.  This directory is used to hold a shared socket.  This directory doesn't exist on MacOS and isn't created by the installer.  To allow the cluster to run, this directory needs to be manually created and authorized for mounting in Docker.

To create the directory, and set permissions, use the following commands in MacOS terminal:

sudo mkdir /var/lib/kubelet
sudo mkdir /var/lib/kubelet/device-plugins
sudo chgrp staff /var/lib/kubelet/device-plugins
sudo chmod 770 /var/lib/kubelet/device-plugins

Now authorize Docker to mount this directory.  This is done in "Preferences..." of the Docker app.

In the File Sharing tab, add /var/lib/kubelet/device-plugins to the list of directories that can be bind-mounted.  You will need to manually type this directory name - using the chooser won't work.

Save and apply the changes (Docker will restart).

Install socat

The "oc" command uses socat to provide socket functionality (for port forwarding etc.).  I installed this using Homebrew (which you can install from here).  Once you have Homebrew installed, you simply run:

brew install socat

Install oc

Many blog posts show how to use Homebrew to install the oc command.  However, this will install the OpenShift 4.x version which doesn't provide the ability to run a local cluster.  I downloaded the Mac oc package (as a zip) from here.  Once you have the zip unpacked, move the oc binary to the /usr/local/bin directory or add it to your path in some other way.

Start the cluster

Before starting the cluster, make sure that nothing is listening on ports 443 or 8443.  These are needed by OpenShift - 8443 for the web console and 443 for the router.  Also, make sure that Docker Community Edition is running.

When you start the cluster it will, by default, create a directory in the current directory.  To create this directory in an absolute location, use the following command to specify the base directory:

oc cluster up --base-dir=${HOME}/openshift.local.clusterup

*Note: If your home directory includes special characters (like @) then this will cause start up to fail.  In this case, use a different path, for example /Users/Shared/openshift.local.clusterup.

You'll see quite a lot of output on the console as images are downloaded from Docker Hub and started.  If you have issues you can also look at the log of the origin container.  At the end of the startup process, you should see the following message:

OpenShift server started.

The server is accessible via web console at:

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

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

Congratulations, your OpenShift Cluster is running.  You can execute commands with oc or you can connect to the web console by pointing a browser at

Here is the oc command to check status:

oc status

In project My Project (myproject) on server

You have no services, deployment configs, or build configs.
Run 'oc new-app' to create an application.OpenShift server started.

Deploying IBM Security Verify Access

If you want to deploy IBM Security Verify Access in this OpenShift environment, check out my assets at  There is a link here to a cookbook with step-by-step instructions for installation and configuration.

You will need to perform a couple of additional steps to prepare.

The easist approach is to map the required hostnames to  However, if you want to exactly match the setup described in the cookbook, you will need to create IP aliases for and and create static host mappings for these addresses.  Details on this below.

Option 1: Add host entries for

Modify entry in /etc/hosts

Append the entry for in /etc/hosts with the static host entries needed for the cookbook: localhost

Option 2: Add new IP address aliases

Create IP aliases

On a Mac, you can't automatically use 127.0.0.x IP addresses (other than  To make these IP addresses available, you need to run the following commands:

sudo ifconfig lo0 alias
sudo ifconfig lo0 alias

These aliases are only active until the system is rebooted.  After that you will have to run these commands again to recreate the aliases.

Add entries to /etc/hosts

You will need to add these entries to your /etc/hosts file for static host mapping:





Mon September 07, 2020 04:05 AM

Thanks Frank.  I've updated in response to this.  You still need the old version of Docker CE to get full function but newer version will work when only using published images.

Sat September 05, 2020 03:02 AM

not bad, works at once, also at later version ( Docker with new Preferences UI, Desktop:, Docker Engine: 19.03.12 )

the only thing to be aware of, insecure-registries screen looks new and has to be a json format:

"insecure-registries": [
see also:

Thanks a lot !, Frank

Mon August 12, 2019 01:06 AM

Good article Jon.