Skip to content

Local Kubernetes cluster on macOS with Ubuntu Multipass and K3s

Install Multipass

Install via Homebrew:

brew install multipass

Launch Ubuntu Nodes

Launch 3 virtual nodes running Ubuntu 22.04 LTS:

multipass launch 22.04 --name ubuntu-k3s-01 --cpus 1 --memory 2G --disk 8G
multipass launch 22.04 --name ubuntu-k3s-02 --cpus 1 --memory 2G --disk 8G
multipass launch 22.04 --name ubuntu-k3s-03 --cpus 1 --memory 2G --disk 8G

Verify that the nodes are running:

multipass list
You should see output similar to this:

Name                    State             IPv4             Image
ubuntu-k3s-01           Running           192.168.64.2     Ubuntu 22.04 LTS
ubuntu-k3s-02           Running           192.168.64.3     Ubuntu 22.04 LTS
ubuntu-k3s-03           Running           192.168.64.4     Ubuntu 22.04 LTS

Verify that you can connect to each node:

multipass shell ubuntu-k3s-01
multipass shell ubuntu-k3s-02
multipass shell ubuntu-k3s-03

Install K3s

K3s Server Node

multipass exec ubuntu-k3s-01 -- bash -c "curl -sfL https://get.k3s.io | sh -"

After running this installation:

  • The K3s service will be configured to automatically restart after node reboots or if the process crashes or is killed
  • Additional utilities will be installed, including kubectl, crictl, ctr, k3s-killall.sh, and k3s-uninstall.sh
  • A kubeconfig file will be written to /etc/rancher/k3s/k3s.yaml and the kubectl installed by K3s will automatically use it.

Verify that the server node is running:

multipass exec ubuntu-k3s-01 -- sudo kubectl get nodes -o wide

List the running pods:

multipass exec ubuntu-k3s-01 -- sudo kubectl get pods --all-namespaces -o wide

K3s Agent Nodes

A single-node server installation is a fully-functional Kubernetes cluster, including all the datastore, control-plane, kubelet, and container runtime components necessary to host workload pods. It is not necessary to add additional server or agents nodes, but you may want to do so to add additional capacity or redundancy to your cluster.

To install additional agent nodes and add them to the cluster, run the installation script with the K3S_URL and K3S_TOKEN environment variables.

First get the server IP address:

K3S_SERVER=$(multipass info ubuntu-k3s-01 | grep IPv4 | awk '{print $2}')

Next get the join token for the agents:

K3S_TOKEN=$(multipass exec ubuntu-k3s-01 sudo cat /var/lib/rancher/k3s/server/node-token)

Quick Checkpoint:

echo $K3S_SERVER
echo $K3S_TOKEN

Next add the rest of the Ubuntu nodes to the cluster:

# add ubuntu-k3s-02
multipass exec ubuntu-k3s-02 -- \
bash -c "curl -sfL https://get.k3s.io | K3S_URL=https://$K3S_SERVER:6443 K3S_TOKEN=$K3S_TOKEN sh -"

# add ubuntu-k3s-03
multipass exec ubuntu-k3s-03 -- \
bash -c "curl -sfL https://get.k3s.io | K3S_URL=https://$K3S_SERVER:6443 K3S_TOKEN=$K3S_TOKEN sh -"

Verify that the nodes have joined the cluster:

multipass exec ubuntu-k3s-01 -- sudo kubectl get nodes -o wide

You should see output similar to this:

NAME            STATUS   ROLES                  AGE   VERSION        INTERNAL-IP    EXTERNAL-IP   OS-IMAGE             KERNEL-VERSION       CONTAINER-RUNTIME
ubuntu-k3s-01   Ready    control-plane,master   40m   v1.29.6+k3s2   192.168.64.2   <none>        Ubuntu 22.04.4 LTS   5.15.0-117-generic   containerd://1.7.17-k3s1
ubuntu-k3s-02   Ready    <none>                 29m   v1.29.6+k3s2   192.168.64.3   <none>        Ubuntu 22.04.4 LTS   5.15.0-117-generic   containerd://1.7.17-k3s1
ubuntu-k3s-03   Ready    <none>                 10s   v1.29.6+k3s2   192.168.64.4   <none>        Ubuntu 22.04.4 LTS   5.15.0-117-generic   containerd://1.7.17-k3s1

Cleanup

Stop the Ubuntu instances:

multipass stop ubuntu-k3s-03
multipass stop ubuntu-k3s-02
multipass stop ubuntu-k3s-01

Delete the Ubuntu instances:

multipass delete ubuntu-k3s-03
multipass delete ubuntu-k3s-02
multipass delete ubuntu-k3s-01

To purge all unused multipass images:

multipass purge