k3d: containerised k3s clusters for local Kubernetes work

The problem k3d solves, and who actually needs it

Running Kubernetes locally usually means either a single-node distribution that hides the control plane, or a virtual machine per node that eats memory before your workload starts. k3d takes a different route: it creates containerised k3s clusters, so a multi-node cluster runs on a single machine using Docker. The README states this directly, and it is the whole pitch. The unit of cost is a container, not a VM, which is why people reach for it when they need to see how something behaves across nodes rather than on one.

The audience is narrow but real. Developers who need to test scheduling, node affinity, DaemonSets or a rolling upgrade without a cloud account. CI pipelines that need a throwaway cluster per job. Anyone reproducing a bug that only appears with more than one node. If your work is a single pod against a single API server, k3d is more machinery than you need, and a plain k3s install or Docker Desktop's built-in Kubernetes will do less work for the same result.

How k3d builds a cluster: containers, a proxy and a kubeconfig

k3d is a Go program. The repository layout shows cmd/ for the CLI, pkg/ for the cluster, node and config logic, and proxy/ for the API-server proxying layer. The go.mod lists docker-related dependencies such as github.com/google/go-containerregistry and github.com/rancher/wharfie, which is what you would expect from a tool that pulls images and reads registry credentials.

Each cluster becomes a set of Docker containers running the k3s image. The README's Makefile shows how the default k3s tag is chosen: the build queries https://update.k3s.io/v1-release/channels/stable and rewrites the tag, replacing + with - because git and Docker Hub spell the tag differently. That detail matters in practice. If you pin a k3s version, you are pinning a Docker image tag, and the two naming schemes are not identical.

The proxy component is the part people miss. A Docker container's ports are not the same as your host's, and a kubeconfig that points at a container IP will not survive a restart. k3d runs a proxy and rewrites the kubeconfig so kubectl talks to a stable host endpoint. That is why creating a cluster gives you a working context rather than a file you have to edit by hand.

Installing k3d and creating a first cluster

The README offers several routes. The install script grabs the latest release, and you can pin a release with the TAG environment variable. On macOS and Linux, Homebrew is the shorter path. Windows users have Chocolatey and Scoop. There is also a Go install, which the README warns gives you unreleased changes, so treat it as a development route rather than a stable one.

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

The script downloads the binary for your platform. After it finishes, k3d version should print a version string. If you prefer a package manager:

brew install k3d

The README notes Homebrew is available for macOS and Linux. On Windows, choco install k3d or scoop install k3d are the documented equivalents. Docker must be present and running before any of this is useful: the README states k3d v5.x.x requires at least Docker v20.10.5 with runc >= v1.0.0-rc93, and links issue #807 for the reason.

With Docker running, the README's framing of a multi-node cluster on a single machine is the point, so decide node count at creation time rather than growing the cluster afterwards. Once the cluster exists, kubectl get nodes should list it and kubectl config current-context should name the new cluster.

Where k3d is the wrong tool

The README is unusually candid about one thing: k3d is a community-driven project and not an official Rancher (SUSE) product. That is a support statement, not a quality judgement, but it changes what you can expect. If your organisation needs a vendor behind the Kubernetes distribution it runs, k3d is not that, and neither is it meant to be.

The harder limit is Docker itself. Every node is a container on one host, sharing that host's kernel, memory and disk. A cluster that looks multi-node is still single-machine, so anything you want to learn about real network partitions, cross-host storage or node failure at the hypervisor level will not reproduce faithfully. The README's stated requirement of Docker v20.10.5 with a recent runc is a floor, not a suggestion; older Docker versions caused real problems, as issue #807 records.

Resource contention is the failure mode you will meet first. Each k3s node carries its own control-plane or agent process, and the default k3s image is not tiny. Spinning up a five-node cluster on a laptop with 8 GB of RAM will not fail loudly. It will get slow, and the symptom will look like a Kubernetes problem rather than a memory problem. Check host memory before blaming the cluster.

k3d versus k3s: the difference is the container boundary

The most common confusion is treating k3d and k3s as alternatives. They are not. k3s is the lightweight Kubernetes distribution by Rancher, and the README links to k3s-io/k3s as its upstream. k3d creates containerised k3s clusters. k3s is the thing running inside; k3d is the thing that puts it in Docker and manages the lifecycle around it.

That distinction has practical consequences. With k3s installed directly on a host, you get a real systemd service, a real network namespace and a node that behaves like a node. With k3d, you get the same Kubernetes API inside a container, plus k3d's own layer for creating, deleting and connecting to clusters. The trade is portability and disposability against fidelity. You can delete a k3d cluster in one command and not worry about what it left behind on the host, which is exactly what you want in CI and exactly what you do not want in production.

If your goal is a persistent cluster on a small server, install k3s. If your goal is a cluster you will destroy this afternoon, k3d is the shorter path.

Maintenance, release cadence and the licence

The last push to the default branch was on 2026-09-14, and the most recent stable release listed is v5.9.0 from 2026-06-02. Before that, v5.9.0-rc.0 landed on 2025-10-01 and v5.8.3 on 2025-02-15. The gap between v5.8.3 and v5.9.0 is over a year, with a release candidate sitting in between for eight months. That is a project that ships deliberately rather than continuously, and you should plan upgrades around releases rather than around the branch.

The README documents three major breaking-change points: v3.0.0 in May 2020, v4.0.0 in January 2021 and v5.0.0 in September 2021. The v5 line has held since then, which means the surface you build on today has been stable for a long time. Upgrading within v5 has not required the kind of migration the earlier jumps did, though the README does not document a rollback procedure, so pin the version you install in CI rather than tracking latest.

The licence is MIT, per the repository's LICENSE file and the badge at the top of the README. MIT is permissive: it allows use, modification and redistribution with the copyright notice retained. It is not a support contract, and it does not change the fact that k3d is community-driven. If you are shipping k3d inside a product or a managed service, have your own legal review the notice requirements; nothing here is legal advice.

Editorial conclusion

Adopt k3d if you need disposable multi-node Kubernetes clusters on a laptop or in a CI job, and you already run Docker v20.10.5 or newer. Do not adopt it as a production control plane or as a substitute for k3s on real hosts; it is a community project, not an official Rancher product. Verify first that your Docker version satisfies the README's floor and that your machine has enough memory for the node count you plan, then create a cluster and confirm the kubeconfig context appears before wiring it into a pipeline.

Frequently asked questions

Official sources

1. k3d-io/k3d on GitHub
2. License: MIT
3. Project website
4. README
5. Releases