Identity and Access Management (IAM)

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.

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.  If you want to have a fully working OpenShift system (where you can build applications from source) then you need to use an old version of Docker Community Edition.  I used version Version 17.09.1-ce-mac42 (21090).  The install disk image (.dmg) 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..." or the Docker app.  You must save and apply changes (which restarts Docker) on each tab.

In the General tab, disable "Automatically check for updates".  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.

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.

If you want to deploy Access Manager in OpenShift, check out my assets at




Mon August 12, 2019 01:06 AM

Good article Jon.