Docker For Mac Kubernetes

So you want to install Kubernetes on your Mac? The easiest way to get going is to run Kubernetes on Docker, using Talos OS - Talos OS will install and configure Kubernetes on Docker for you. (Note that Docker Desktop does have support for Kubernetes built in, but it is an older version of Kubernetes, and limited to a single node cluster.) You can be up and exploring Kubernetes on Mac within 10 minutes, with all the advantages of an API managed, immutable, secure Kubernetes OS.

  1. Docker For Mac Kubernetes Dashboard
  2. Docker For Mac Kubernetes Not Starting

The newest version of Docker Desktop for Windows already adds a hosts file entry: kubernetes.docker.internal. You had to do use kubernetes.docker.internal URL as a hostname in Ingress definition if you want to point to

  1. Install the most recent version of Docker for Mac, one that includes the Kubernetes cluster functionality. Click the Docker menu bar icon Preferences, then click the Kubernetes tab. Click the checkbox to enable Kubernetes and switch the default orchestrator to Kubernetes. Docker might take a few minutes to install more components here.
  2. The Docker Desktop installation includes Docker Engine, Docker CLI client, Docker Compose, Notary, Kubernetes, and Credential Helper. Install and run Docker Desktop on Mac Double-click Docker.dmg to open the installer, then drag the Docker icon to the Applications folder.

First, install Docker Desktop.

Run Docker, give it the access it asks for, and you'll see it chugging along in the menu bar. It will launch a wizard, which you can skip if you just want to run Talos and Kubernetes on your Mac.

A key component of Talos is talosctl, the CLI (Command Line Interface) which lets you interact with the OS running on your kubernetes nodes (virtual nodes in this case, but the same talosctl is used for Kubernetes on bare metal, VMWare, or cloud providers).

Docker For Mac Kubernetes

To get going with talosctl you need to download the latest release as shown below (or from Github here.)

Now, test if it’s working by running:

Creating a local cluster is as simple as:

This command will create a simple two node cluster, with one master node and one worker node.

You can create a more complex kubernetes cluster on your Mac by passing in different parameters. Note that creating a larger cluster in Docker uses a lot of resources and takes quite a while, and is not recommended unless you have a powerful Mac. e.g. to create a cluster with 3 masters and 1 worker, use:

(Note that in order to install a new Talos OS based kubernetes cluster on the same Mac, you should talosctl cluster destroy the old cluster first, else you will run into naming conflicts. You can manually assign unique names and run multiple clusters - but it's certainly easier to just destroy the old cluster, then create a new cluster.)

The creation of the kubernetes cluster takes a while to process (a few minutes on my Macbook Pro for a two node cluster), and you can expect to see some errors, as below, where the installation system expects services to be up, but they take longer on a docker based system than expected. Note that once the services do start, the installation proceeds correctly.

As well as the command output, you can also watch the progress from the Docker dashboard (click the Docker icon in the menu bar and select Dashboard.) Click the node talos-default-master-1, and you will see the logs of the master node, and be able to watch services start:

Once the cluster create command has exited successfully, you need to set the Kubernetes configuration so it knows how to reach the API server:

talosctl config nodes
talosctl kubeconfig .
kubectl --kubeconfig kubeconfig config set-cluster talos-default --server

Finally, we just need to modify the talosctl config to specify which nodes you want to get information on. Talosctl can operate on one or all the nodes in the cluster - this makes cluster wide commands much easier.


talosctl config nodes

Note that these are the default node addresses for a one master, one worker cluster. If you already have a variety of containers running, or created more master or worker nodes, you can verify the node addresses using docker inspect or talosctl cluster show

You now have a complete (albeit simple) kubernetes cluster running on your mac. You can use talosctl to operate and examine the nodes. Some commands to try are:

For further options with talosctl see the getting started guide and the Git repo.

You can also explore kubernetes on your Mac with kubernetes commands (passing in the kubeconfig):


There are other more flexible ways to run Kubernetes on MacOS - we'll explore a qemu based installation in a later article. But if you want to get Kubernetes on a Mac up and running quickly so you can start learning and testing - Docker and Talos OS is the way to do it. And if you want to see similar ease of use in bare metal kubernetes - check out Sidero!

This is a step-by-step guide to installing and running Kubernetes on your Mac so that you can develop applications locally.

You will be guided through running and accessing a Kubernetes cluster on your local machine using the following tools:

  • Homebrew
  • Docker for Mac
  • Minikube
  • virtualbox
  • kubectl
Docker for mac kubernetes is starting

Installation Guide

The only pre-requisite for this guide is that you have Homebrew installed. Homebrew is a package manager for the Mac. You’ll also need Homebrew Cask, which you can install after Homebrew by running brew tap caskroom/cask in your Terminal.

  1. Install Docker for Mac. Docker is used to create, manage, and run our containers. It lets us construct containers that will run in Kubernetes Pods.

  2. Install VirtualBox for Mac using Homebrew. Run brew cask install virtualbox in your Terminal. VirtualBox lets you run virtual machines on your Mac (like running Windows inside macOS, except for a Kubernetes cluster.)

    Skip to step three if everything has worked to this point.

    In my case, I already had the non-Homebrew VirtualBox app installed which caused issues when trying to start minikube.

    If you already have VirtualBox installed, start the installation as before with brew cask install virtualbox. You will get a warning that confirms this saying Warning: Cask 'virtualbox' is already installed.. Once this is confirmed, you can reinstall VirtualBox with Homebrew by running brew cask reinstall virtualbox.

    If you happen to have VirtualBox already running when you do this, you could see an error saying Failed to unload org.virtualbox.kext.VBoxDrv - (libkern/kext) kext is in use or retained (cannot unload).

    This is because the kernel extensions that VirtualBox uses were in use when the uninstall occurred. If you scroll up in the output of that command, beneath Warning! Found the following active VirtualBox processes: you’ll see a list of the processes that need to be killed.

    Kill each of these in turn by running kill first_column_number (first_column_number is the process identifier for that process).

    Now re-run brew cask reinstall virtualbox and it should succeed.

  3. Install kubectl for Mac. This is the command-line interface that lets you interact with Kuberentes. Run brew install kubectl in your Terminal.

  4. Install Minikube via the Installation > OSX instructions from the latest release. At the time of writing, this meant running the following command in Terminal…

    Minikube will run a Kubernetes cluster with a single node.

  5. Everything should work! Start your Minikube cluster with minikube start. Then run kubectl api-versions. If you see a list of versions, everything’s working! minikube start might take a few minutes.

  6. At this point, I got an error saying Error starting host: Error getting state for host: machine does not exist. because I had previously tried to run Minikube. You can fix this by running open ~/.minikube/ to open Minikube’s data files, and then deleting and deleting the machines directory. Then run minikube start again.

Come Together

You’ve installed all these tools and everything looks like it’s working. A quick explanation of how the components relate is needed.

Docker For Mac Kubernetes Dashboard


Docker For Mac Kubernetes Not Starting

  • VirtualBox is a generic tool for running virtual machines. You can use it to run Ubuntu, Windows, etc. inside your macOS operating system host.
  • Minikube is a Kubernetes-specific package that runs a Kubernetes cluster on your machine. That cluster has a single node and has some unique features that make it more suitable for local development. Minikube tells VirtualBox to run. Minikube can use other virtualization tools—not just VirtualBox—however these require extra configuration.
  • kubectl is the command line application that lets you interact with your Minikube Kubernetes cluster. It sends request to the Kubernetes API server running on the cluser to manage your Kubernetes environment. kubectl is like any other application that runs on your Mac—it just makes HTTP requests to the Kubernetes API on the cluster.