v3.0.2

v3.0.2

Enhancements/Features

• add fish completions (#345, @mtatheonly)
• basic plugin system, subgoal callables (#333)
  • call executables in your PATH as k3d my-plugin (file must be called k3d-my_plugin)
• new --no-rollback flag for k3d cluster create to prevent automatic rollbacks (e.g. for debugging purposes)

Misc

• e2e-tests:
  • enable skipping multiple tests
    • make e2e -e E2E_SKIP="test_full_lifecycle test_multi_master"
  • improved logs
  • test multiple k3s versions
    • make e2e -e E2E_EXTRA=1

v3.0.1

v3.0.1

Enhancements

• handle leading / in docker container names (#322, @kshelton)
• introduce new node status (#328)
  • can be seen in output of cluster list (node columns now: running/total) and node list (additional column)

Fixes

• fixed inconsistent behavior of cluster create --update-default-kubeconfig/--switch-context
• fixed impossible config when mapping port ranges on the loadbalancer (e.g. cluster create -p 1000-2000@loadbalancer) (#317)
• fixed hanging forever when trying to start a cluster that's already running (#335)

Misc

• install script: check for binary in more bashy way (#313, @vandot)

Docs

• clarify kubeconfig get/print/show and kubeconfig merge/write

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)