k3d

Create a cluster

$ k3d cluster create [cluster_name]

$ k3d cluster delete [cluster_name]

$ k3d node create [node_name]

$ k3d image import [image_name] [[-c|--cluster]] [cluster_name]

$ k3d registry create [registry_name]

k3d [subcommand] [options] [args]
e.g. k3d cluster create [NAME] [flags]

cluster create [NAME]
    Create a new k3s cluster with optional name and config flags.

--agents num
    Number of agent (worker) nodes (default 1).

--servers num
    Number of server nodes for HA (default 1).

--image rancher/k3s:vX.Y.Z-k3sN
    k3s container image/version to use.

--port 'host:node[@filter]'
    Port mapping for LoadBalancer (default random:80@loadbalancer).

--api-port port
    Host port for Kubernetes API (default 6443).

--registry-create regname
    Create embedded Docker registry container.

--k3s-arg arg[@filter]
    Pass extra arguments to k3s binary on nodes.

--wait
    Wait for nodes to join and cluster to be ready (default true).

--timeout duration
    Timeout for cluster readiness (default 5m).

cluster delete [NAME|all]
    Delete cluster(s).

cluster list
    List all running clusters.

kubeconfig create NAME
    Generate kubeconfig for cluster.

image import image
    Import Docker image into cluster registry.

--verbose
    Enable verbose logging (global).

--version
    Show k3d version (global).

k3d is a fast, lightweight CLI tool that enables running k3s (Rancher's minimal Kubernetes distribution) in Docker containers. It simplifies creating fully functional single-node or multi-node Kubernetes clusters for local development, testing, CI/CD, and demos.

Using k3d, you can launch a cluster with one command, automatically handling Docker container orchestration for server/agent nodes, networking, LoadBalancer port-forwarding, and kubeconfig generation. It supports embedded Docker registries, image preloading, custom k3s arguments, and high-availability setups.

Compared to tools like Minikube (VM-based) or Kind (Docker-based but heavier), k3d offers faster startup (<10s), smaller resource usage, and native k3s features like Traefik ingress, Flux GitOps, and SQLite/etcd storage. Ideal for developers needing quick kubectl access without complex setup.

Once created, interact via kubectl after merging kubeconfig. Clusters are isolated per Docker network, easy to delete/recreate.

For local dev/testing only; not production-ready.
Requires Docker/containerd.
Limited resources/performance vs. bare-metal.
Multi-node HA needs odd server count (≥3).

curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
Or brew install k3d (macOS/Linux).

k3d cluster create myk3s
k3d kubeconfig write myk3s > ~/.kube/myconfig
kubectl get nodes

Created 2020 by @dominikschröder (ivpn/k3d-io). Apache 2.0 license. Rapid adoption by Rancher; v5+ (2023+) aligns with k3s v1.2x, adds CRI support, better HA.

docker(1), kubectl(1), k3s(8), kind(1), minikube(1)