k3d

README

Please Note: main is now v5.0.0 and the code for v4.x can be found in the main-v4 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
  • Note: k3d v5.x.x requires at least Docker v20.10.4 to work properly

Releases

• May 2020: v1.7.x -> v3.0.0 (rewrite)
• January 2021: v3.x.x -> v4.0.0 (breaking changes)
• September 2021: v4.4.8 -> v5.0.0 (breaking changes)

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

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=v5.0.0 bash
  • curl: curl -s https://raw.githubusercontent.com/rancher/k3d/main/install.sh | TAG=v5.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 MacPorts: sudo port selfupdate && sudo port install k3d (MacPorts is available for MacOS)

• 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@latest (Note: this will give you unreleased/bleeding-edge changes)

• use Chocolatey: choco install k3d (Chocolatey package manager is available for Windows)

  • package source can be found in erwinkersten/chocolatey-packages

or...

Build

1. Clone this repo, e.g. via git clone git@github.com:rancher/k3d.git or go get github.com/rancher/k3d/v5@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. [Optional, included in cluster create] k3d kubeconfig merge CLUSTER_NAME --kubeconfig-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: GUI (Linux) to k3d
• vscode-k3d: vscode plugin for k3d
• AbsaOSS/k3d-action: fully customizable GitHub Action to run lightweight Kubernetes clusters.
• AutoK3s: a lightweight tool to help run K3s everywhere including k3d provider.
• nolar/setup-k3d-k3s: setup K3d/K3s for GitHub Actions.

Contributing

k3d is a community-driven project and so we welcome contributions of any form, be it code, logic, documentation, examples, requests, bug reports, ideas or anything else that pushes this project forward.

Please read our Contributing Guidelines and the related Code of Conduct.

You can find an overview of the k3d project (e.g. explanations and a repository guide) in the documentation: k3d.io/internals/project

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Thorsten Klein 💻 📖 🤔 🚧	Rishabh Gupta 🤔 💻	Louis Tournayre 📖	Lionel Nicolas 💻	Toon Sevrin 💻	Dennis Hoppe 📖 💡	Jonas Dellinger 🚇
markrexwinkel 📖	Alvaro 💻 🤔 🔌	Nuno do Carmo 🖋 ✅ 💬	Erwin Kersten 📖	Alex Sears 📖	Mateusz Urbanek 💻	Benjamin Blattberg 💻
Simon Baier 💻	Ambrose Chua 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Documentation

Overview

Copyright © 2020-2021 The k3d Author(s)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.