v3.0.0 - FROM scratch

🎉 FROM scratch - Re-Written k3d

We've spent quite some days weeks months on completely re-writing k3d from scratch. New concepts, new architecture, new setup, new syntax, new everything.

Why v3? Because v2 is too mainstream..
The real reason is that v3 is not just the next step in k3d's "evolution", but rather a complete rewrite, including new concepts and structures. At first it was planned to drop a v2.0.0 release in between v1.x and v3.0.0, but due to the changes over time, this is not going to happen anymore.
Also, "k3d v3" just sounds sooo good 😁

🏠 New Home & New Logo

We now have a real homepage up with documentation, examples, etc ... and our very own logo 🥳

https://k3d.io/

💻 Installation

Please checkout the installation instructions here: https://k3d.io/#installation
The page is build from the docs/ directory using mkdocs.

❗ Important Notes & Breaking Changes

New Syntax

By far the largest breaking change for you as a k3d user is the change of the CLI syntax.

• in k3d v1.x (and v3.0.0 up to rc.6), we used to have the VERB NOUN syntax, similar to how kubectl and kind have it
  • e.g. k3d create -n mycluster (v1.x) or k3d create cluster mycluster (v3.0.0-rc.6)
• NEW: Now we decided to follow the route of other major cloud CLIs (like gcloud, awscli, az, etc.) and roll with NOUN VERB syntax, which makes the CLI cleaner and easier to develop
• e.g. k3d cluster create, k3d kubeconfig get, ...
• Please checkout k3d help or the command tree on the website as a reference

Inclusive Terminology

To be as inclusive to the community as possible, we decided to get rid of all occurrences of master and worker in our code. Here is what changed:

• master (node role) -> server (similar to k3s)
  • e.g. k3d cluster create multi-server --servers 3
• worker (node role) -> agent (similar to k3s)
  • e.g. k3d cluster create multi-agent --agents 2
  • Important: Due to this renaming, the short-hand flag k3d cluster create -a now stands for --agents and not anymore for --api-port (which does not have a short-hand flag anymore)
• master (branch) -> main

Cluster Setup

By default, every cluster you create will now spawn at least 2 containers: 1 server node + 1 server load balancer (disable via --no-lb) used as the main access point to the Kubernetes API.

🆕 New Features (Selection)

• creating multi-server clusters (using k3s' embedded datastore): k3d cluster create --servers 3
• updating existing kubeconfigs: k3d kubeconfig merge mycluster --output /my/kubeconfig.yaml
  • IMPORTANT: By default, k3d will now update your default kubeconfig upon cluster creation to use the new cluster/context!
• attaching new clusters to existing networks: k3d create cluster --network this-other-network
• handling nodes independently from clusters: k3d node create/start/stop/delete mynode
• multiarch images for k3d-proxy and k3d-tools containers: linux w/ amd64/arm/arm64
• leaving out --api-port upon cluster creation will randomly assign a port to expose the API on the host
• --wait flag set by default for all important commands where once could want to wait for cluster/node initialization before returning
• proper support to be used as a Go Module: exported functions, constants, etc.
• shell completion
• revamped CI via Drone

Checkout all commands provided by the CLI here: https://k3d.io/usage/commands/

🔜 Missing Features

There are some features of v1.x that haven't made it into this release yet.
Probably the most prominent one is the registries feature (--enable-registry) and related options.
Please checkout the feature comparison page on the website to see what's implemented, what's missing, what has been dropped and what is planned to land in v3.x.

v3.0.0-rc.7 - NEW SYNTAX

🎉 (hopefully last) Release Candidate of v3.0.0

🆕 🆙 Changes since v3.0.0-rc.5 (skipped test release rc.6)

New Syntax

By far the largest breaking change for you as a k3d user is the change of the CLI syntax.

• in k3d v1.x (and v3.0.0 up to rc.6), we used to have the VERB NOUN syntax, similar to how kubectl and kind have it
  • e.g. k3d create -n mycluster (v1.x) or k3d create cluster mycluster (v3.0.0-rc.6)
• NEW: Now we decided to follow the route of other major cloud CLIs (like gcloud, awscli, az, etc.) and roll with NOUN VERB syntax, which makes the CLI cleaner and easier to develop
  • e.g. k3d cluster create, k3d kubeconfig get, ...
  • Please checkout k3d help or the command tree on the website as a reference

Inclusive Terminology

To be as inclusive to the community as possible, we decided to get rid of all occurrences of master and worker in our code. Here is what changed:

• master (node role) -> server (similar to k3s)
  • e.g. k3d cluster create multi-server --servers 3
• worker (node role) -> agent (similar to k3s)
  • e.g. k3d cluster create multi-agent --agents 2
  • Important: Due to this renaming, the short-hand flag k3d cluster create -a now stands for --agents and not anymore for --api-port (which does not have a short-hand flag anymore)
• master (branch) -> main

v3.0.0-syntax.0 - Test-Release for Poll

v3.0.0-syntax.0 - Test-Release for Poll

Related PR: #300

This is a test release to decide on the migration from the current VERB NOUN (e.g. k3d create cluster) syntax to a new NOUN VERB (e.g. k3d cluster create) syntax.
There are some pro's and con's for each of them (pros for the one are usually cons for the other option):

• VERB NOUN
  • Pro: the syntax that current k3d users are used to and also what we've showcased so far for v3.0.0 (blog posts, meetup recording)
  • Pro: "natural"/"speaking" syntax
  • Pro: closest to what kubectl and kind do (and some other tools in the Kubernetes ecosystem
• NOUN VERB
  • Pro: cleaner CLI (hierarchy)
  • Pro: makes it easier to add new nouns (i.e. k3d managed objects)
  • Pro: similar to many other cloud-native CLIs (e.g. gcloud, awscli, azure cli, ...)
  • Pro: easier development experience (k3d internal)

Please reply on Slack or Twitter or on the Pull-Request

Set the environment variable K3D_NEW_SYNTAX=1 to try the new NOUN VERB syntax.

v3.0.0-rc.6

• arm support for k3d-proxy

v3.0.0-rc.5

🎉 Sixth (and hopefully last) Release Candidate of v3.0.0

🆕 🆙 Changes since v3.0.0-rc.3 (skipped test release rc.4)

Features

• ❗ --wait for k3d create cluster is now enabled by default

Maintenance

• ❗ Fixed go module to be v3: go get github.com/rancher/k3d/v3@master
• Fixed kubeconfig API Port for hostNetwork mode cluster (fixes #284)
• Tests now also build new helper images (proxy and tools) to ensure that releases work with respective fresh versions

Misc

• CI: Switched from Travis to Drone (#278 , thanks for the support @luthermonson)
  • ❗ Multiarch builds for rancher/k3d-tools and rancher/k3d-proxy docker images
    • linux/amd64, linux/arm, linux/arm64
    • now have the same tag as the corresponding CLI release
  • automated (pre-)releases

[Test] v3.0.0-rc.4

This is a test release created by Drone CI.

v3.0.0-rc.3

🎉 Fourth Release Candidate of v3.0.0

🆕 🆙 Changes since v3.0.0-rc.2

Features

• ❗ Automatically choosing a random free port used for the API (#279)
  • k3d create cluster one && k3d create cluster two will not result in a port collision on 6443 anymore, but rather each cluster will use a random host port for access to its Kubernetes API
  • --api-port is still an option!

Maintenance

• fix: actually consider contexts when checking for existing contexts in a kubeconfig
• fix: nil pointer dereference when creating a new node but the target cluster does not exist (#277)
• increase proxy_timeout to 10 minutes for the masterlb so e.g. kubectl get logs -f doesn't break after 30s (#276)

README/Docs

• updated CSS (#271, @lvuch)
• Reference to k3x, a frontend/integration for k3d (#274, @inercia)

Misc

• integrated k3d-tools repository as a submodule in main repo (#275)

v3.0.0-rc.2

🎉 Third Release Candidate of v3.0.0

🆕 🆙 Changes since v3.0.0-rc.1

Features

• shell completion via k3d completion [zsh | bash | psh] (#270)

Maintenance

• ❗ Getting rid of the root flag --runtime, as this will probably never happen and was interfering with other things

README/Docs

• updated CSS and favicon (#264, @lvuch)

v3.0.0-rc.1

🎉 Second Release Candidate of v3.0.0

🆕 🆙 Changes since v3.0.0-rc.0

Features

• new flag --token for k3d get clusters: show the cluster token (#257, thanks @RouxAntoine)
• k3d load images can take more than one argument, which can be either image name (e.g. nginx:local) or filename (e.g. nginx_local.tar) to load images from the container runtime or from the local filesystem (e.g. tarballs created with docker save) (#266

Fixes

• ...

Maintenance

• ❗ Update docker dependencies

README/Docs

• add missing pieces on new features
• add section about dqlite known issues to FAQ

Miscellaneous

• Breaking Change: renamed all occurrences of secret as in cluster-secret to token (#257, thanks @RouxAntoine)
  • e.g. the container label k3d.cluster.secret is now k3d.cluster.token
  • all related functions and variables have been renamed in the code

v3.0.0-rc.0

🎉 First Release Candidate of v3.0.0

🆕 🆙 Changes since v3.0.0-beta.2

Features

• New flag: k3d create cluster --switch: update the kubeconfig and directly switch the current-context (#261)
• Now using context.Context in all top-level exported functions (#244)
• update loadbalancer every time when creating/deleting master nodes (#258)
• New flags: --wait and --timeout for command k3d create node (#259)

Fixes

• do not copy --cluster-init flag when creating a second master node
• k3d get clusters and k3d get nodes now allow... (#260)
  • specifying one name: get only one node/cluster
  • specifying multiple names: get multiple nodes/clusters
  • specifying no name: get all nodes/clusters

Maintenance

• move more stuff to constants

README/Docs

• add back section on registries: https://k3d.io/usage/guides/registries/

Miscellaneous

...