Overview

This page is targeting k3d v4.0.0 and newer!

k3d is a lightweight wrapper to run k3s (Rancher Lab’s minimal Kubernetes distribution) in docker.

k3d makes it very easy to create single- and multi-node k3s clusters in docker, e.g. for local development on Kubernetes.

View a quick demo

Learning

• Rancher Meetup - May 2020 - Simplifying Your Cloud-Native Development Workflow With K3s, K3c and K3d (YouTube)
• k3d demo repository: iwilltry42/k3d-demo

Requirements

• docker

Releases

Platform	Stage	Version	Release Date
GitHub Releases	stable
GitHub Releases	latest
Homebrew	-		-
Chocolatey	stable		-

Installation

You have several options there:

• use the install script to grab the latest release:
• wget: wget -q -O - https://raw.githubusercontent.com/rancher/k3d/main/install.sh | bash
• curl: curl -s https://raw.githubusercontent.com/rancher/k3d/main/install.sh | bash
• use the install script to grab a specific release (via TAG environment variable):
• wget: wget -q -O - https://raw.githubusercontent.com/rancher/k3d/main/install.sh | TAG=v4.0.0 bash

• curl: curl -s https://raw.githubusercontent.com/rancher/k3d/main/install.sh | TAG=v4.0.0 bash

• use Homebrew: brew install k3d (Homebrew is available for MacOS and Linux)

• Formula can be found in homebrew/homebrew-core and is mirrored to homebrew/linuxbrew-core
• install via AUR package rancher-k3d-bin: yay -S rancher-k3d-bin
• grab a release from the release tab and install it yourself.
• install via go: go install github.com/rancher/k3d (Note: this will give you unreleased/bleeding-edge changes)
• use arkade: arkade get k3d
• use asdf: asdf plugin-add k3d, then asdf install k3d <tag> with <tag> = latest or 3.x.x for a specific version (maintained by spencergilbert/asdf-k3d)
• use Chocolatey: choco install k3d (Chocolatey package manager is available for Windows)
• package source can be found in erwinkersten/chocolatey-packages

Quick Start

Create a cluster named mycluster with just a single server node:

k3d cluster create mycluster

Get the new cluster’s connection details merged into your default kubeconfig (usually specified using the KUBECONFIG environment variable or the default path $HOME/.kube/config) and directly switch to the new context:

k3d kubeconfig merge mycluster --kubeconfig-switch-context

Use the new cluster with kubectl, e.g.:

kubectl get nodes

Related Projects

• k3x: a graphics interface (for Linux) to k3d.
• AbsaOSS/k3d-action: fully customizable GitHub Action to run lightweight Kubernetes clusters.

---

Last update: February 4, 2021