The easiest way to install Kubernetes on a Mac

• Steve Francis
• September 29, 2020

So you want to install Kubernetes on your Mac? The easiest way 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.

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 (the same talosctl is used for Kubernetes on bare metal, VMWare, or cloud providers).

Download the latest release as shown below (or from Github here.)

curl -Lo /usr/local/bin/talosctl https://github.com/talos-systems/talos/releases/latest/download/talosctl-$(uname -s | tr "[:upper:]" "[:lower:]")-amd64
chmod +x /usr/local/bin/talosctl

Creating a local cluster is as simple as:

talosctl cluster create

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

The creation of the kubernetes cluster takes a while to process (a few minutes on my Macbook Pro), and you may 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. Once the services do start, the installation proceeds correctly.

talosctl cluster create

validating CIDR and reserving IPs
generating PKI and tokens
downloading ghcr.io/talos-systems/talos:v0.11.3
creating network talos-default
creating master nodes
creating worker nodes
renamed talosconfig context "talos-default" -> "talos-default-1"
waiting for API
bootstrapping cluster
waiting for etcd to be healthy: 1 error occurred:
    * 10.5.0.3: service "etcd" not in expected state "Running": current state [Preparing] Running pre state
waiting for etcd to be healthy: OK
waiting for apid to be ready: OK
waiting for kubelet to be healthy: OK
waiting for all nodes to finish boot sequence: OK
waiting for all k8s nodes to report: OK
waiting for all k8s nodes to report ready: OK
waiting for all control plane components to be ready: OK
waiting for kube-proxy to report ready: OK
waiting for coredns to report ready: OK
waiting for all k8s nodes to report schedulable: OK

merging kubeconfig into "/Users/stevefrancis/.kube/config"
PROVISIONER       docker
NAME              talos-default
NETWORK NAME      talos-default
NETWORK CIDR      10.5.0.0/24
NETWORK GATEWAY   10.5.0.1
NETWORK MTU       1500

NODES:

NAME                      TYPE           IP         CPU    RAM      DISK
/talos-default-master-1   controlplane   10.5.0.2   2.00   2.1 GB   -
/talos-default-worker-1   join           10.5.0.3   2.00   2.1 GB   -

The cluster create command will create a kubeconfig for you.

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

talosctl config nodes 10.5.0.2 10.5.0.3 

Note that these are the default 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, or from the output of the cluster create command.

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:

talosctl containers
talosctl logs etcd
talosctl containers -k
talosctl logs -k kubelet
talosctl services

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

You can also explore Kubernetes on your Mac with Kubernetes commands:

kubectl  get nodes
NAME                   STATUS ROLES  AGE VERSION
talos-default-master-1 Ready  master 25h v1.19.0
talos-default-worker-1 Ready  none   25h v1.19.0

Also try:
kubectl  get pods -A

Creating more complex clusters

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 is not recommended unless you have a powerful machine.) e.g. to create a cluster with 3 masters and 1 worker, use:

talosctl cluster create   --wait-timeout 40m0s  --masters 3 --workers 1 --cpus 4;

(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.)

While you can runa multi-master cluster, there are some limitations to running on docker in a Mac – the networking is limited, so things like virtual IPs will not work correctly.

There are other ways to run Kubernetes on MacOS. 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!