K3d is an open-source wrapper around the Rancher/SUSE K3s Kubernetes distribution that lets you run the control plane inside Docker. The entire stack runs in Docker, giving you a fully containerized cluster that’s lightweight and easy to set up.

Whereas K3s is designed for a broad range of workflows, K3d focuses more specifically on development situations where you’re already using Docker. It lets you spin up a Kubernetes cluster on your existing Docker host without running a virtual machine or any other system services.

This article will show you how to get up and running with a simple K3d cluster. You’ll need both Kubectl and Docker v20.10.5 or newer already installed on your system before you begin. K3d works on Linux, Mac (including via Homebrew), and Windows (via Chocolatey). This guide focuses on use with Linux; k3d CLI installation instructions for other platforms are available in the documentation.

Installing the K3d CLI

The k3d CLI provides management commands for creating and managing your clusters. You can find the latest CLI on GitHub or run the installation script to automatically get the correct download for your system.

$ curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

The script deposits the k3d binary into your /usr/local/bin directory. Try running the k3d version command to check your installation’s succeeded:

$ k3d version
k3d version v5.4.6
k3s version v1.24.4-k3s1 (default)

Creating a Cluster

The K3d CLI provides a cluster create command to automatically create and start a new cluster:

$ k3d cluster create
INFO[0000] Prep: Network                                
INFO[0000] Created network 'k3d-k3s-default'            
INFO[0000] Created image volume k3d-k3s-default-images  
INFO[0000] Starting new tools node...                   
INFO[0001] Creating node 'k3d-k3s-default-server-0'     
INFO[0001] Pulling image 'ghcr.io/k3d-io/k3d-tools:5.4.6' 
INFO[0002] Pulling image 'docker.io/rancher/k3s:v1.24.4-k3s1' 
INFO[0002] Starting Node 'k3d-k3s-default-tools'        
INFO[0008] Creating LoadBalancer 'k3d-k3s-default-serverlb' 
INFO[0009] Pulling image 'ghcr.io/k3d-io/k3d-proxy:5.4.6' 
INFO[0012] Using the k3d-tools node to gather environment information 
INFO[0012] HostIP: using network gateway 172.25.0.1 address 
INFO[0012] Starting cluster 'k3s-default'               
INFO[0012] Starting servers...                          
INFO[0012] Starting Node 'k3d-k3s-default-server-0'     
INFO[0016] All agents already running.                  
INFO[0016] Starting helpers...                          
INFO[0016] Starting Node 'k3d-k3s-default-serverlb'     
INFO[0022] Injecting records for hostAliases (incl. host.k3d.internal) and for 2 network members into CoreDNS configmap... 
INFO[0025] Cluster 'k3s-default' created successfully!  
INFO[0025] You can now use it like this:                
kubectl cluster-info

The cluster will be named k3s-default when you run the command without any arguments. Set your own name by including it as the command’s first argument:

$ k3d cluster create demo
...

K3d automatically modifies your Kubernetes config file (.kube/config) to include a connection to your new cluster. It marks the connection as the default so kubectl commands will now target your K3d environment.

$ kubectl cluster-info
Kubernetes control plane is running at https://0.0.0.0:42879
CoreDNS is running at https://0.0.0.0:42879/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Metrics-server is running at https://0.0.0.0:42879/api/v1/namespaces/kube-system/services/https:metrics-server:https/proxy

Running docker ps will show two containers have been started, one for K3s and another for K3d’s proxy that forwards traffic into your cluster:

$ docker ps
CONTAINER ID   IMAGE                              COMMAND                  CREATED         STATUS         PORTS                             NAMES
9b6b610ad312   ghcr.io/k3d-io/k3d-proxy:5.4.6     "/bin/sh -c nginx-pr..."   3 minutes ago   Up 3 minutes   80/tcp, 0.0.0.0:42879->6443/tcp   k3d-k3s-default-serverlb
842cc90b78bf   rancher/k3s:v1.24.4-k3s1           "/bin/k3s server --t..."   3 minutes ago   Up 3 minutes                                     k3d-k3s-default-server-0

Using Your Cluster

Use familiar Kubectl commands to interact with your cluster and deploy your Pods:

$ kubectl run nginx --image nginx:latest
pod/nginx created

$ kubectl expose pod/nginx --port 80 --type NodePort
service/nginx exposed

To access your NGINX server, first find the IP address assigned to your Kubernetes Node:

$ kubectl get nodes -o wide
NAME                       STATUS   ROLES                  AGE    VERSION        INTERNAL-IP   EXTERNAL-IP   OS-IMAGE   KERNEL-VERSION      CONTAINER-RUNTIME
k3d-k3s-default-server-0   Ready    control-plane,master   102s   v1.24.4+k3s1   172.27.0.2    <none>        K3s dev    5.4.0-125-generic   containerd://1.6.6-k3s1

The correct IP to use is 172.27.0.2.

Next find the NodePort assigned to your nginx service:

$ kubectl get services
NAME         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
kubernetes   ClusterIP   10.43.0.1       <none>        443/TCP        5m49s
nginx        NodePort    10.43.235.233   <none>        80:31214/TCP   1s

The exposed port number is 31214. Making a request to 172.17.0.2:31214 should issue the default NGINX welcome page:

$ curl http://172.17.0.2:31214
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
...

You can get more guidance on exposing services and setting up Ingress networking within the K3d documentation.

Enabling K3s Flags

The cluster create command wraps the standard K3s cluster creation process. You can pass arguments through to K3s by supplying --k3s-arg flags. The value of the flag should be an argument that will be included when K3d calls the K3s binary.

$ k3s cluster create --k3s-arg "--disable=traefik"

This example instructs K3s to disable its built-in Traefik component.

Accessing Services Running on Your Host

Some workloads you run in K3d might need to access services already running on your Docker host. K3d provides a hostname called host.k3d.internal within its default DNS configuration. This will automatically resolve to your host machine. You can reference this special hostname within your Pods to access existing databases, file shares, and other APIs running outside of Kubernetes.

Using Local Docker Images

Your K3d/K3s cluster can’t access your local Docker images. The cluster and all its components is running inside Docker. Trying to use a private image that only exists on the host will fail and report an error.

There are two ways of resolving this: either push your image to a registry, or use K3d’s image import feature to copy a local image into your cluster. The first method is generally preferred as it centralizes your image storage and lets you access images from any environment. However, when quickly testing local changes you might want to directly import an image you’ve just built:

$ k3d image import demo-image:latest

This command will make demo-image:latest available inside your cluster.

K3d can also create and expose an image registry for you. Registries are best created alongside your cluster as K3d can then automatically configure the cluster’s access:

$ k3d cluster create --registry-create demo-registry

This starts a new cluster with a registry called demo-registry. The registry will run in its own Docker container. You can discover the port number that the registry is exposed on by running docker ps -f name=<cluster-name>-registry, where <cluster-name> is the name of your cluster. Pushing images to this registry will make them accessible to Pods in your cluster.

$ docker tag demo-image:latest k3d-demo-registry.localhost:12345/demo-image:latest
$ docker push k3d-demo-registry.localhost:12345/demo-image:latest

You can also create registries on-demand but you’ll need to manually reconfigure your cluster to supply connection details.

Stopping Your Cluster

Your K3d cluster will run continually until you stop it yourself. The cluster stop command stops running Docker containers while preserving your cluster’s data:

$ k3d cluster stop k3s-default

Restart your cluster in the future using the cluster start command:

$ k3d cluster start k3s-default

Deleting Your Cluster

You can delete a cluster at any time by running the cluster delete command and supplying its name. This will remove all trace of the cluster, deleting the Docker containers and volumes that provided it. Deleting all your clusters will take your host back to a clean slate with only the K3d CLI installed.

$ k3d cluster delete k3s-default
INFO[0000] Deleting cluster 'k3s-default'               
INFO[0001] Deleting cluster network 'k3d-k3s-default'   
INFO[0001] Deleting 2 attached volumes...               
INFO[0001] Removing cluster details from default kubeconfig... 
INFO[0001] Removing standalone kubeconfig file (if there is one)... 
INFO[0001] Successfully deleted cluster k3s-default!

The deletion process automatically removes references to the cluster from your Kubeconfig.

Summary

K3d lets you run a containerized Kubernetes cluster. It provides a complete K3s environment wherever Docker is available. K3d supports multiple nodes, has integrated support for image registries, and can be used to create highly available clusters with multiple control planes.

Developers already running Docker can use K3d to quickly add Kubernetes to their working environment. K3d is lightweight, easy to manage, and adds no other system services to your machine. This makes it a great choice for local use but its reliance on Docker means it may not be suitable for production hosts where you don’t want to add another dependency. Other Kubernetes distributions such as Minikube, Microk8s, and plain K3s are all viable alternatives.