k3d Guide: Create a “Lightweight” Kubernetes Cluster on Docker in Just 30 Seconds – ITFROMZERO

Table of Contents

The Nightmare of Local Kubernetes

Have you ever heard your laptop “scream” just because you accidentally started a Kubernetes cluster to test some code? I used to be stuck in that situation: a 16GB RAM machine with fans sounding like a jet engine, while Docker Desktop devoured all system resources. Deploying a simple Hello World app could sometimes take an entire morning just waiting to pull images and initialize nodes.

Most traditional tools like Minikube typically run a full virtual machine (VM). This approach is extremely RAM and CPU intensive. After struggling for a long time, I found k3d. The experience changed completely. Instead of waiting 5-10 minutes, it took me less than 30 seconds to have a cluster ready for work.

Comparison: Why is k3d Superior?

To see the difference clearly, let’s compare k3d with today’s popular competitors:

Minikube: A veteran in the local K8s world, supporting many drivers. However, it’s quite heavy, and networking between the host machine and the VM often encounters minor bugs.
Kind (Kubernetes in Docker): A similar concept to k3d, running K8s in containers. But Kind uses the standard K8s distribution, so it remains significantly heavier.
k3d (k3s in Docker): This is a wrapper for k3s – a lightweight K8s version developed by Rancher. It removes redundant components, bundled into a single binary file.

Below is a comparison table based on real-world performance on a Dell XPS 13 (i7, 16GB RAM):

Criteria	Minikube (Docker driver)	Kind	k3d
Startup Time	~2 minutes	~1 minute	< 25 seconds
RAM Usage (Idle)	~1.5GB – 2GB	~800MB – 1GB	~400MB – 500MB
Multi-node	Complex	Quite good	Extremely flexible

Where Does k3d’s Real Power Lie?

K3d helps you run k3s inside Docker containers seamlessly. K3s is already optimized for IoT or Edge computing devices with extremely low resources. When brought into a dev environment, it runs so fast that you can create or delete clusters repeatedly without any annoyance.

The ability to simulate multi-node setups is my favorite feature. You can easily set up 1 Master and 3 Workers with a single command line. Everything is contained within independent Docker containers. Once you’re done learning, cleaning up the environment takes only seconds.

Prerequisites

Before starting the lab, you need two things installed:

Docker: The core platform for k3d to operate.
kubectl: The command-line tool for controlling Kubernetes.

Installing k3d is very fast. If you’re on MacOS (Homebrew), type:

brew install k3d

For Windows users, Chocolatey is the best choice. For Linux, just execute this script:

wget -qO- https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | TAG=v5.6.0 bash

Hands-on Deployment: From Zero to a Full Cluster

1. Initialize Your First Cluster

Type the following command to create a basic cluster:

k3d cluster create my-lab

K3d will automatically configure the ~/.kube/config file. You can use kubectl to connect immediately. Check node status with the command:

kubectl get nodes

The system will display a single node acting as both master and worker.

2. Setting Up a Multi-node Model (1 Master, 2 Workers)

To test the fault tolerance or distribution of an application, you should use a multi-node model. Try the following command:

k3d cluster create multi-node-cluster --servers 1 --agents 2

At this point, Docker will launch 3 containers corresponding to 3 nodes. You can check this list using the familiar docker ps command.

3. Exposing Ports to the Host Machine

Accessing applications from a browser is the step where many people struggle. Since K8s is inside Docker, you need to map ports from the physical machine to the cluster’s LoadBalancer.

I usually map through Traefik (the default Ingress for k3s):

k3d cluster create web-lab -p "8080:80@loadbalancer" --agents 2

Note: All traffic sent to localhost:8080 will be forwarded directly to port 80 of the cluster.

4. Deploying a Test Nginx Application

Let’s verify the system by running an Nginx server. Save the following content to a file named nginx-deploy.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-test
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  type: LoadBalancer
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80

Deploy the file you just created to the cluster:

kubectl apply -f nginx-deploy.yaml

Now, access localhost:8080 in your browser. If you see the Nginx welcome page, you have successfully set up the Lab!

Tips for Optimizing Your k3d Workflow

Use Local Images: Instead of wasting time pushing images to Docker Hub, you can push images directly from your host machine into the cluster. This is an extremely valuable feature:

k3d image import my-app-image:latest -c my-lab

Pause When Not in Use: If you want to save laptop battery without deleting installed resources, use the stop command. It works similarly to stopping a Docker container:

k3d cluster stop my-lab
k3d cluster start my-lab

This makes the machine run much smoother compared to leaving Minikube running in the background.

Conclusion

K3d isn’t just for learning. It’s truly a powerful assistant that makes the daily application development process more professional. Since switching to k3d, I no longer worry about my machine freezing or running out of RAM when working with Kubernetes.

If you’re looking for a fast, lightweight, and easy-to-manage K8s Lab environment, k3d is the perfect answer right now.