k3d — Run K3s Kubernetes Clusters Inside Docker

What it is

k3d is a lightweight wrapper around Rancher's K3s distribution that runs entire Kubernetes clusters inside Docker containers. Instead of provisioning VMs or paying for cloud clusters, you get a multi-node K8s environment on your laptop in under 30 seconds.

It targets developers who need fast, disposable clusters for testing Helm charts, validating manifests, running integration tests in CI, or experimenting with GitOps workflows without touching production infrastructure.

How it saves time or tokens

Traditional local Kubernetes options like minikube or kind require heavier setup and slower startup. k3d leverages K3s (a stripped-down Kubernetes binary under 100MB) and Docker's container runtime to eliminate VM overhead entirely. Cluster creation takes seconds, not minutes. Tearing down and recreating is instant, which means your CI pipelines run faster and your local dev loop stays tight.

How to use

1. Install k3d via the official install script or your package manager (brew install k3d, curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash).
2. Create a cluster with k3d cluster create mycluster --agents 2 to get a 3-node cluster (1 server + 2 agents).
3. Your kubeconfig is automatically merged. Run kubectl get nodes to verify all nodes are ready.

Example

# Create a cluster with a local registry and port mapping
k3d cluster create dev \
  --agents 3 \
  --port '8080:80@loadbalancer' \
  --registry-create dev-registry:5000

# Deploy an app
kubectl apply -f deployment.yaml

# Test locally via localhost:8080
curl http://localhost:8080

# Tear down when done
k3d cluster delete dev

Related on TokRepo

• DevOps tools on TokRepo — More infrastructure automation and deployment tools
• Self-hosted tools — Run your own services without cloud lock-in

Common pitfalls

• Docker Desktop resource limits can starve multi-node clusters. Allocate at least 4GB RAM and 2 CPUs to Docker before creating clusters with 3+ nodes.
• Port conflicts occur when multiple clusters map the same host port. Use unique port mappings per cluster or delete old clusters first.
• k3d clusters are ephemeral by default. Persistent volumes are lost on cluster deletion unless you mount host directories with --volume.