k3d for Local Development
k3d runs k3s clusters inside Docker, perfect for laptops and CI pipelines.
k3d is a small helper that runs k3s inside Docker containers. Each node becomes a container, so you can create and destroy whole clusters in seconds without touching your host system.
Why it is handy
- Spin up multi-node clusters on one laptop.
- Throwaway clusters for testing manifests in CI.
- No leftover services on your host — just delete the containers.
k3d is a separate tool from k3s, but it runs the very same k3s under the hood, so behaviour matches your servers.
Example
# Create a 1-server, 2-agent cluster in Docker
k3d cluster create dev \
--servers 1 --agents 2 --port "8080:80@loadbalancer"
# kubectl is auto-configured to talk to it
kubectl get nodes
# Tear it all down
k3d cluster delete devWhen to use it
- A developer creates a local multi-node k3s cluster with k3d in 10 seconds to replicate a production topology on their MacBook.
- A CI pipeline uses k3d to spin up an isolated k3s cluster per pull request, run integration tests, and delete the cluster on job exit.
- A developer maps a local port to the k3d LoadBalancer so they can test Ingress routing against localhost without any DNS configuration.
More examples
Create a k3d cluster
Creates a k3s cluster named dev with two agent nodes inside Docker and maps host port 8080 to the ingress LoadBalancer.
k3d cluster create dev \
--agents 2 \
--port '8080:80@loadbalancer'
kubectl get nodesLoad a local image into k3d
Builds a local image and imports it into the k3d cluster so pods can use it without pushing to a registry.
docker build -t myapp:local .
k3d image import myapp:local -c dev
kubectl run myapp --image=myapp:local --image-pull-policy=NeverDelete the k3d cluster
Lists clusters, deletes the dev cluster, and verifies all k3d Docker containers have been removed.
k3d cluster list
k3d cluster delete dev
docker ps | grep k3d # should be empty
Discussion