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.