k3d — Run K3s Kubernetes Clusters Inside Docker

Introduction

k3d was created to bridge the gap between running a real Kubernetes API server locally and the overhead of full VM-based distributions. Docker Desktop''s built-in cluster is a single node and hard to reset; minikube boots a VM. k3d instead runs K3s — a certified, slimmed-down Kubernetes built for the edge — inside Docker containers, so creating, rebuilding, or running five isolated clusters takes seconds and costs almost no RAM per cluster.

What k3d Does

• Creates single- or multi-node K3s clusters as groups of Docker containers.
• Manages an attached Traefik ingress or custom load balancer with host-port mapping.
• Bootstraps an integrated container registry or wires clusters into an existing one.
• Imports local Docker images into all cluster nodes without a registry round-trip.
• Provides lifecycle commands — start, stop, snapshot with volumes — for fast reset cycles.

Architecture Overview

Each k3d cluster is a set of Docker containers: a server container running the K3s binary (which bundles the API server, scheduler, controller-manager, and a lightweight etcd alternative called Kine), zero or more agent containers, and an nginx-based load balancer that fronts the API and ingress. Persistent state lives in Docker volumes. Because everything is just Docker, k3d integrates with host networking, Docker''s built-in DNS, and host-mounted directories for workspace code — making inner-loop dev extremely fast.

Self-Hosting & Configuration

• One-line install via shell script, Homebrew, or Chocolatey; also a single Go binary.
• Define clusters declaratively with a YAML config file (k3d cluster create -c config.yaml).
• Use k3d image import during CI to avoid pushing test images to a registry.
• Expose LoadBalancer services to the host via --port mappings or forward them with kubectl.
• Pin the K3s image tag in CI pipelines for reproducible cluster versions.

Key Features

• Ephemeral clusters spin up in 10-20 seconds and use < 1 GB RAM idle.
• Multi-cluster on the same workstation with isolated kubeconfigs and contexts.
• Registry cache via the bundled k3d-registry for offline dev and faster image pulls.
• Volume and port declarations in YAML keep local setups reproducible and shareable.
• First-class support for K3s flags — --k3s-arg passes straight through to the distro.

Comparison with Similar Tools

• kind — Also uses Docker nodes but runs upstream Kubernetes; k3d is lighter because K3s is stripped down.
• minikube — Historically VM-based (HyperKit, KVM, Hyper-V); heavier and slower than k3d.
• Docker Desktop Kubernetes — Single-node, single-version, restart-to-reset; fine for beginners.
• microk8s — Snap-based on Linux; multi-node and production-ish but tied to Snap/Ubuntu patterns.
• k0s — Production-oriented K8s distro; k3d is for dev-loop clusters, not edge or prod.

Key Flags

• --registry-create creates an attached registry; --registry-use hooks into an existing one.
• --k3s-arg="--disable=traefik"@server:* swaps the default ingress.
• --volume host:container@loadbalancer mounts host paths into the LB container.

FAQ

Q: Is k3d production-ready? A: It''s optimized for dev and CI. K3s itself runs in production, but the k3d wrapper targets ephemeral clusters.

Q: Does it support Windows/macOS? A: Yes — anywhere Docker runs. On Apple Silicon it uses the native arm64 K3s image.

Q: How do I reach a Service from my host? A: Declare a --port mapping at cluster create, or kubectl port-forward for ad-hoc debugging.

Q: Can I simulate HA? A: Yes — use --servers 3 to run three server nodes with embedded etcd for a true HA control plane.

Sources

• https://github.com/k3d-io/k3d
• https://k3d.io/