Installing and Running a Local Kubernetes Environment on macOS

how to install and run a local kubernetes environment on macos


For a local installation of Kubernetes on macOS the getting started guide recommends minikube is used. This page details the various installation steps required to install this.


Ensure that the software below is installed on the host macOS machine before continuing.
* Docker for Mac
* Homebrew

Installing minikube

As per the minikube documentation

“Minikube is a tool that makes it easy to run Kubernetes locally. Minikube runs a single-node Kubernetes cluster inside a VM on your laptop for users looking to try out Kubernetes or develop with it day-to-day.”

To install minikube, follow the instructions at At the time of writing, version v0.15.0 is the latest release; the appropriate installation commands for this version are as follows:

curl -Lo minikube && chmod +x minikube && sudo mv minikube /usr/local/bin/

Installing the xhyve Driver

By default, minikube uses VirtualBox to host the Kubernetes environment. However, as Docker for Mac uses xhyve, it makes more sense to use the same hypervisor to host our Kubernetes environment.

For this we need to install the appropriate xhyve driver as detailed at

At the time of writing, the appropriate installation commands for this are as follows:

$ brew install docker-machine-driver-xhyve
$ sudo chown root:wheel $(brew --prefix)/opt/docker-machine-driver-xhyve/bin/docker-machine-driver-xhyve
$ sudo chmod u+s $(brew --prefix)/opt/docker-machine-driver-xhyve/bin/docker-machine-driver-xhyve

Installing kubectl

In order to control Kubernetes from the command-line, the kubectl tool is used. Refer to for more information.

To install kubectl, follow the instructions at At the time of writing the latest stable version is v1.5.2; the appropriate installation commands for this version are as follows:

$ curl -LO$(curl -s
$ chmod +x ./kubectl
$ sudo mv ./kubectl /usr/local/bin/kubectl

Starting, Verifying, Inspecting and Stopping minikube

Starting minikube is trivial, as shown below. The first time this command is executed will take longer than for subsequent calls as it will pull the ISO, storing in ~/.minikube/cache/iso/.

$ minikube start --vm-driver=xhyve
Starting local Kubernetes cluster...
Downloading Minikube ISO
 68.95 MB / 68.95 MB [==============================================] 100.00% 0s
Kubectl is now configured to use the cluster.

Verify the status of minikube:

$ minikube status
minikubeVM: Running
localkube: Running

Inspect the environment by bringing up the dashboard, which will open up in the browser.

$ minikube dashboard
Opening kubernetes dashboard in default browser...

Stop the minikube environment:

$ minikube stop
Stopping local Kubernetes cluster...
Machine stopped.

Using Docker for Mac Behind the Corporate Proxy

how to use docker for mac when behind a corporate proxy


Although enabling internet access for Docker for Mac when behind a corporate proxy appears to be difficult, the steps required are surprisingly simple.


A local proxy server should be running on the Mac where Docker is running in order to authenticate with the dreaded corporate proxy. Both Charles Proxy and SquidMan work well for this purpose. It is assumed below that the local proxy server is listening on port 8099; feel free to change this value throughout, if required.

Getting the IP Address of the Docker VM Gateway

Connect to the VM, as detailed in Accessing the Docker For Mac Virtual Machine.

$ screen ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/tty

Press the Enter key, and validate we are on the Docker VM.

/ # hostname

Examine the routing table to see the default gateway: in the example below, this is

/ # netstat -rn
Kernel IP routing table
Destination     Gateway         Genmask         Flags   MSS Window  irtt Iface         UG        0 0          0 eth0     U         0 0          0 docker0     U         0 0          0 br-b46215017f01 U         0 0          0 eth0

Disconnect from the VM using ctrl a \, answering y to the prompt:

Really quit and kill all your windows [y/n] y

Set the Docker for Mac Proxy

Finally, set the proxy in Docker itself, as shown below:
Docker for Mac Proxy Settings

The IP address is the gateway IP address from the Docker VM (i.e.; the port is what the local proxy is listening on (i.e. 8099). Apply the changes and restart Docker, at which point it will now be able to communicate, via the local proxy server, to the internet. Easy!

Accessing the Docker For Mac Virtual Machine

how to access the docker for mac virtual machine


Although Docker for Mac helpfully goes out of its way to appear to be running natively on macOS, behind the scenes it actually runs on an Alpine Linux VM using xhyve. Refer to for more details.

Under most circumstances we won’t need to understand the underlying implementation, but there are occasions where it is helpful to be able to see exactly what Docker is doing. In order to do this, we need access to the actual VM itself. This isn’t a problem when using Docker Machine as we can easily connect to the VirtualBox VM; it is not quite so obvious how to achieve this on the new architecture.

Accessing the Docker Device

The callin device for the Docker VM can be found at ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/tty.

$ ls -l ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/tty
lrwxr-xr-x  1 paul  staff  12 18 Oct 16:54 /Users/paul/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/tty -> /dev/ttys001

As can be seen above, this file is actually a link to the underlying character device file:

$ ls -l /dev/ttys001
crw--w----  1 paul  tty   16,   1 18 Oct 16:54 /dev/ttys001

To access this device interactively, we can simply use the screen utility as follows:

$ screen ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/tty

If the resulting screen is blank, simply hit the Enter key; you should then be presented with the following:

Welcome to Moby
Kernel 4.4.20-moby on an x86_64 (/dev/ttyS0)

                        ##         .
                  ## ## ##        ==
               ## ## ## ## ##    ===
           /"""""""""""""""""___/ ===
      ~~~ {~~ ~~~~ ~~~ ~~~~ ~~~ ~ /  ===- ~~~
           \______ o           __/
             \    \         __/

moby login: root
Welcome to Moby, based on Alpine Linux.

As shown, the login is root; no password is required. And that’s all there is to it: you now have a session on the Docker VM.

For example, to check the Docker images that have been loaded on your Docker for Mac installation:

moby:~# docker images
REPOSITORY                           TAG                 IMAGE ID            CREATED             SIZE
ubuntu                               16.04               c73a085dc378        3 weeks ago         127.1 MB
tykio/tyk-gateway                    latest              34c572d12a1f        9 weeks ago         246.9 MB
redis                                latest              e5181bd07b8e        10 weeks ago        185 MB
swaggerapi/swagger-editor            latest              3727b21e15fc        3 months ago        105.6 MB
tykio/tyk-dashboard                  latest              6249f7af1db2        3 months ago        567.1 MB
tykio/tyk-pump-docker-pub            latest              b0df8680eaab        3 months ago        246.7 MB
alpine                               3.3                 47cf20d8c26c        3 months ago        4.797 MB
jenkins                              latest              d5c0410b1b44        4 months ago        736.9 MB
registry                             latest              bca04f698ba8        8 months ago        422.9 MB

That’s Great … But How do I Get Out of Here?

The key combination you’re looking for is ctrl a \ then answer y to the prompt:

Really quit and kill all your windows [y/n] y