# k3d — Run K3s Kubernetes Clusters Inside Docker

> k3d wraps Rancher's K3s Kubernetes distribution into Docker containers, letting developers spin up ephemeral multi-node clusters in seconds for development, CI, and GitOps experimentation.

## Install

Save in your project root:

# k3d — Run K3s Kubernetes Clusters Inside Docker

## Quick Use
```bash
# Install
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

# Multi-node dev cluster with a local registry and host-port map for ingress
k3d registry create myregistry.localhost --port 5000
k3d cluster create dev 
  --servers 1 --agents 3 
  --registry-use k3d-myregistry.localhost:5000 
  --port "8081:80@loadbalancer" --port "8443:443@loadbalancer"

kubectl cluster-info
kubectl config use-context k3d-dev

# Tear down when done
k3d cluster delete dev
```

## 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/


---
Source: https://tokrepo.com/en/workflows/4e8708b2-3929-11f1-9bc6-00163e2b0d79
Author: AI Open Source