Little helper to run CNCF's k3s in Docker
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
iwilltry42 4590ac57e2
tests/e2e: allow overriding helper image tag for e2e tests to avoid building
4 years ago
.github fix commit user name for aur release 4 years ago
cmd unify the registry type 4 years ago
docs [Feature] Registry for v4 & Restructure Cluster Creation (#334) 4 years ago
pkg unify the registry type 4 years ago
proxy [Feature] Registry for v4 & Restructure Cluster Creation (#334) 4 years ago
tests tests/e2e: allow overriding helper image tag for e2e tests to avoid building 4 years ago
tools go v1.15 4 years ago
vendor update docker dependency to fix cross-compilation issues 4 years ago
version [FEATURE] Config File (#351) 4 years ago
.all-contributorsrc docs: add nunix as a contributor (#419) 4 years ago
.dockerignore add .dockerignore to ignore submodules when building k3d 4 years ago
.drone.yml allow overriding GIT_TAG for make build target to fix publishing docker images 4 years ago
.gitignore integrate k3d-tools repo as Go submodule 4 years ago
CHANGELOG.md add Changelog.md 4 years ago
CODE_OF_CONDUCT.md misc: add contributing guide, CoC and all-contributors 4 years ago
CONTRIBUTING.md update Contributing.md 4 years ago
Dockerfile allow overriding GIT_TAG for make build target to fix publishing docker images 4 years ago
LICENSE cleanup and prepare for push to rancher/k3d 5 years ago
Makefile tests/e2e: allow overriding helper image tag for e2e tests to avoid building 4 years ago
README.md [Feature] Registry for v4 & Restructure Cluster Creation (#334) 4 years ago
deploy-aur.sh [Enhancement] CI/CD: AUR Deploy Script (#391, thanks @JohnnyCrazy) 4 years ago
go.mod update docker dependency to fix cross-compilation issues 4 years ago
go.sum update docker dependency to fix cross-compilation issues 4 years ago
install.sh Fix install.sh script if curl is not present (#414) 4 years ago
main.go v3 -> v4 4 years ago
mkdocs.yml resolve favicon issue and move css 4 years ago
thoughts.md use server/agent instead of master/worker 4 years ago

README.md

k3d

Build Status License Downloads

Go Module Go version Go Report Card

All Contributors

Contributor Covenant

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.

asciicast

Learning

Requirements

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 release (latest by date) GitHub Release Date
GitHub Releases latest GitHub release (latest by date including pre-releases) GitHub (Pre-)Release Date
Homebrew - 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)

  • 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/v4@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 --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.

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

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.

Contributor Covenant

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

🖋 💬

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