Please Note: main is now v3.0.0 and the code for v1.x can be found in the main-v1 branch!

k3s in docker

k3s is the lightweight Kubernetes distribution by Rancher: rancher/k3s

k3d creates containerized k3s clusters. This means, that you can spin up a multi-node k3s cluster on a single machine using docker.

Learning

• Website with documentation: k3d.io
• 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

Note: In May 2020 we upgraded from v1.7.x to v3.0.0 after a complete rewrite of k3d!

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

Get

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=v3.0.0 bash
  • curl: curl -s https://raw.githubusercontent.com/rancher/k3d/main/install.sh | TAG=v3.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)

or...

Build

1. Clone this repo, e.g. via git clone git@github.com:rancher/k3d.git or go get github.com/rancher/k3d/v3@main
2. Inside the repo run
   • 'make install-tools' to make sure required go packages are installed
3. Inside the repo run one of the following commands
   • make build to build for your current system
   • go install to install it to your GOPATH (Note: this will give you unreleased/bleeding-edge changes)
   • make build-cross to build for all systems

Usage

Check out what you can do via k3d help or check the docs @ k3d.io

Example Workflow: Create a new cluster and use it with kubectl

1. k3d cluster create CLUSTER_NAME to create a new single-node cluster (= 1 container running k3s + 1 loadbalancer container)
2. k3d kubeconfig merge CLUSTER_NAME --switch-context to update your default kubeconfig and switch the current-context to the new one
3. execute some commands like kubectl get pods --all-namespaces
4. k3d cluster delete CLUSTER_NAME to delete the default cluster

Connect

1. Join the Rancher community on slack via slack.rancher.io
2. Go to rancher-users.slack.com and join our channel #k3d
3. Start chatting

History

This repository is based on @zeerorg's zeerorg/k3s-in-docker, reimplemented in Go by @iwilltry42 in iwilltry42/k3d, which got adopted by Rancher inrancher/k3d.

Related Projects

• k3x: a graphics interface (for Linux) to k3d.