k3d

Create a cluster

$ k3d cluster create [cluster_name]

$ k3d cluster delete [cluster_name]

$ k3d node create [node_name]

$ k3d image import [image_name] --cluster [cluster_name]

$ k3d registry create [registry_name]

k3d [command] [options]

k3d cluster [subcommand]
k3d image [subcommand]
k3d registry [subcommand]
k3d node [subcommand]
k3d completion
k3d help
k3d version

The most common usage pattern is: k3d cluster create [cluster_name] [flags]

--debug
    Enable debug messages for enhanced verbosity.

--verbose
    Enable verbose messages.

--trace
    Enable trace messages.

-h, --help
    Show help message for a command or subcommand.

--version
    Show the k3d version.

cluster create
-c, --config string
    Path to a k3d cluster configuration file.

cluster create
-n, --name string
    Specify the name of the new cluster (default is 'k3d-k3s-default').

cluster create
--api-port string
    Specify the host port for the Kubernetes API server (default is random).

cluster create
--image string
    Specify the Docker image to use for the k3s nodes (e.g., 'rancher/k3s:v1.27.5-k3s1').

cluster create
--servers int
    Number of server nodes to create for the cluster (default is 1).

cluster create
--agents int
    Number of agent (worker) nodes to create for the cluster (default is 0).

cluster create
--port string
    Map ports from the cluster's load balancer to the host, e.g., '8080:80@loadbalancer'.

cluster create
--k3s-arg strings
    Pass additional arguments directly to the k3s binary on nodes.

cluster create
--no-lb
    Disable the creation of a load balancer container (useful for single-server clusters).

cluster create
--registry-use string
    Connect the cluster to a k3d-managed image registry.

cluster create
--wait
    Wait for the cluster to be ready before exiting the command.

cluster delete
[cluster_name]
    Delete a specified k3d cluster.

cluster list
    List all existing k3d clusters.

image import
<image_path> [cluster_name]
    Import local Docker images into a k3d cluster's image cache.

k3d is a powerful and lightweight tool designed for running k3s Kubernetes clusters in Docker.

Built upon Rancher Labs' highly available and certified k3s distribution, k3d simplifies the process of setting up local Kubernetes environments for rapid development and testing. It allows users to quickly create, delete, and manage multiple isolated k3s clusters, with each cluster operating within its own set of Docker containers.

This makes k3d an excellent choice for developers who need to test applications against a real Kubernetes environment without the significant resource overhead of a full-blown minikube or kind setup. k3d supports single-node, multi-node clusters, and advanced features like image import, integrated registries, and load balancing, all leveraging Docker's robust capabilities.

• Docker Dependency: k3d relies entirely on Docker. The Docker daemon must be installed and running on your system.
• Ephemeral Nature: By default, k3d clusters are ephemeral. All cluster state and data within containers are lost when a cluster is deleted, unless specific volume mounts are configured.
• Resource Consumption: Each node in a k3d cluster is a Docker container. While lightweight, multi-node clusters can consume significant CPU and RAM resources.
• Development Focus: k3d is primarily designed for local development and testing environments, not for production deployments.
• Networking Complexity: Advanced networking scenarios or custom host network interactions may require careful configuration due to Docker's container networking model.

Upon cluster creation, k3d automatically generates and merges the cluster's kubeconfig entry into your default ~/.kube/config file. This seamless integration allows you to immediately interact with your new k3d cluster using the standard kubectl command-line tool, without manual configuration steps.

k3d leverages standard Docker images for its nodes. You can specify a custom k3s image version or even import local Docker images directly into your k3d cluster's image cache. Furthermore, k3d provides built-in capabilities to create and manage local Docker registries, which can be connected to your k3d clusters, streamlining the process of testing applications with private images.

For multi-node clusters, k3d automatically provisions a dedicated Docker container acting as a load balancer (based on haproxy) to expose the Kubernetes API server and other services. It also sets up a dedicated Docker network for each cluster, ensuring proper isolation and communication between nodes and the load balancer, simplifying network configuration for local testing.

k3d was created by Rancher Labs (now part of SUSE) as a complementary tool to k3s. k3s itself was designed to be a lightweight, single-binary Kubernetes distribution tailored for IoT and Edge environments.

k3d extends this philosophy by providing an exceptionally easy and fast way to run k3s clusters inside Docker containers, making it highly portable and reproducible for local development workflows. Its development aimed to offer a faster and lighter alternative to existing local Kubernetes solutions like minikube or kind, especially for scenarios where rapid cluster provisioning and teardown are crucial. It quickly gained popularity for its speed, low resource footprint, and seamless integration with Docker.

k3s(1), docker(1), kubectl(1), minikube(1), kind(1)