Kubernetes is a powerful container management platform that allows you to run multiple containers on the same machine. You can use Kubernetes to manage your applications, data, and services. You can also use Kubernetes to create and manage your clusters of containers. To run a Kubernetes cluster in Docker, you first need to install the Kubernetes toolchain and its dependencies. Then, you can create a new Dockerfile that describes how you want to build your cluster. Finally, you can build and deploy your cluster using the docker-compose command. To build your cluster in Docker, first create a new project called “kubernetes” in your project root directory. Then, add the following lines to your docker-compose file: Kubernetes = “1” kubelet = “1” k3d = “1” pkg = “kubernetes-linux-amd64” env = { KUBELET_VERSION : “2”, KUBELET_CMDLINE_LINUX : “-s $pkg -o $env .kubeconfig” } The first line sets up the environment for building our cluster. The second line sets up the kernel and container versions for our target system (Linux). The third line sets up our k3d image which will be used as the backend for our containers. The fourth line sets up an environment variable called KUBELET_CMDLINE_LINUX which tells Kubernetes where to find our linux kernel commandline options ( -s ). Finally, we set up an environment variable called KUBELET_VERSION which tells Kubernetes how old we want our current version of the kernel to be (2). This will ensure that when we upgrade or change kernels in future releases of Kubernetes, we don’t have to update all of our containers!
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.
The script deposits the k3d binary into your /usr/local/bin directory. Try running the k3d version command to check your installation’s succeeded:
Creating a Cluster
The K3d CLI provides a cluster create command to automatically create and start a new cluster:
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 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.
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:
Using Your Cluster
Use familiar Kubectl commands to interact with your cluster and deploy your Pods:
To access your NGINX server, first find the IP address assigned to your Kubernetes Node:
The correct IP to use is 172.27.0.2.
Next find the NodePort assigned to your nginx service:
The exposed port number is 31214. Making a request to 172.17.0.2:31214 should issue the default NGINX welcome page:
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.
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:
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:
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=
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:
Restart your cluster in the future using the cluster start command:
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.
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.
