Step by step guide for Developer’s using Multipass and k3d
K3s is a lightweight Kubernetes distribution designed for resource-constrained environments, making it ideal for local development or edge computing. However, building K3s from source on macOS isn’t straightforward, since K3s requires a Linux environment to compile. In this guide, we’ll walk through how to build K3s from source using Canonical’s Multipass, transfer the resulting image to your Mac, and then run it using k3d.
Prerequisites:
Before we begin, ensure that Homebrew is installed on your macOS system. You can install all required dependencies using Homebrew.
🔧 Install Multipass
Multipass is a fast and easy way to spin up lightweight Linux virtual machines (VMs) on macOS. We’ll use it to create a Linux environment where K3s can be built. Install it via Homebrew:
brew install multipass
Verify Installation: After the installation is complete, you can verify it by checking the version
multipass version
Learn More : For additional details about Multipass and alternative installation methods, visit the Multipass Installation Guide.
🔧 Install K3d
Install k3d, a lightweight wrapper for running K3s clusters in Docker, using Homebrew:
brew install k3d
Verify Installation: After the installation is complete, you can verify it by checking the version
~ k3d version
k3d version v5.8.3
k3s version v1.31.5-k3s1 (default)
🚀 Launch Multipass and Set Up the Build Environment
Now, let’s create a Linux VM using Multipass to serve as the build environment for K3s.
Launch a Multipass Instance: Run the following command to create a Multipass VM named k3sServer with 2 CPUs, 3GB of memory, and 20GB of disk space.
multipass launch --name k3sServer --cpus 2 --memory 3G --disk 20G
Login to the Multipass Instance: Once the VM is up, log into it using:
multipass shell k3sServer
You’ll now be inside the Multipass shell, and You’ll be greeted with the prompt:
ubuntu@k3sServer:~$
Install Required Tools Inside VM:
To build K3s, you’ll need Docker and make installed inside the Multipass VM.
Install Docker: Run the following commands to install Docker:
sudo apt update
sudo apt install docker.io
Docker Configuration (Optional): If you encounter issues with docker build, ensure the Docker daemon is properly configured. You may need to add a DNS configuration as below:
~ cat /etc/docker/daemon.json
{
"dns": ["172.17.0.1", "8.8.8.8"]
}
Install make: Install the make utility:
sudo apt install make
🧪 Clone and Build K3s
Now that the environment is ready, let’s proceed with building K3s.
Clone the K3s Repository: Clone the official K3s GitHub repository
git clone --depth 1 https://github.com/k3s-io/k3s.git
Navigate to the Repository: Go into the K3s directory
cd k3s
Prepare the Build Environment: Run the following commands to download dependencies and generate required files. Run these commands one by one if you want to check what each step is doing
sudo mkdir -p build/data && make download && make generate
Build K3s: Finally, build K3s with the following command (The SKIP_VALIDATE=true flag skips some validation steps, making the build process faster.)
sudo SKIP_VALIDATE=true make
Build Documentation: Build instructions are available at the official repo:
👉 https://github.com/k3s-io/k3s/blob/master/BUILDING.md
📦 Verify Docker Images
Once the build is complete, you can verify the generated Docker images.
List Docker Images: Take note of the rancher/k3s image you just built
sudo docker images
REPOSITORY TAG IMAGE ID SIZE
rancher/k3s v1.33.0-k3s-c2efae3e-arm64 9ae40bc58195 227MB
k3s master 622b36d40a23 1.25GB
...
Identify the K3s image (e.g., rancher/k3s:v1.33.0-k3s-c2efae3e-arm64) for the next step.
🔁 Transfer Image to macOS Host
To use the built K3s image on your macOS host, transfer the Docker image from the Multipass instance to Mac
Save the Docker Image: Inside the Multipass shell, save the K3s Docker image as a compressed .tar.gz file
sudo docker save rancher/k3s:v1.33.0-k3s-c2efae3e-arm64 | gzip > rk3s.tar.gz
Exit the Multipass Shell: Exit the Multipass instance or user can use another terminal for next step
Transfer the Image to macOS: Use the multipass transfer command to copy the tar file to your macOS host
multipass transfer k3sServer:rk3s.tar.gz ~/Downloads
Load the Image into Docker: On your macOS host, load the image into Docker
docker load -i ~/Downloads/rk3s.tar.gz
🌐 Create a K3s Cluster with k3d
Create Cluster: Now create a Kubernetes cluster using the built image you just loaded
k3d cluster create --image rancher/k3s:v1.33.0-k3s-c2efae3e-arm64
If you run into any issues, use the --verbose or --trace flags to get more details during cluster creation.
Verify Cluster:
~ k3d cluster list
NAME SERVERS AGENTS LOADBALANCER
k3s-default 1/1 0/0 true
Check Pods:
~ kubectl get pods -A
NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system coredns-697968c856-gbvc8 1/1 Running 0 25h
kube-system helm-install-traefik-crd-vlrvr 0/1 Completed 0 25h
kube-system helm-install-traefik-j5tm8 0/1 Completed 1 25h
kube-system local-path-provisioner-774c6665dc-pt44v 1/1 Running 0 25h
kube-system metrics-server-6f4c6675d5-6j47v 1/1 Running 0 25h
kube-system svclb-traefik-a74de106-kzddc 2/2 Running 0 25h
kube-system traefik-c98fdf6fb-gc2f5 1/1 Running 0 25h
✅ Conclusion
You’ve just built K3s from source in a Linux VM, transferred the custom Docker image to your macOS host, and used it to spin up a Kubernetes cluster via k3d. This setup gives you full control over the version and build of K3s you’re using — great for testing new features, debugging, or contributing upstream.
With K3s now running in a Kubernetes cluster on your macOS host, you are ready to:
• Experiment with lightweight Kubernetes for development or testing environments.
• Deploy containerized workloads and explore Kubernetes features.
• Build further expertise with Kubernetes, multi-cloud setups, or edge computing.
If you encounter any issues, refer to the official K3s Build Guide or the k3d Documentation.
Top comments (0)