Quick Start 🔗︎
This guide covers getting started with the
If you are having problems please see the known issues guide.
You can either install kind with
GO111MODULE="on" go get email@example.com or clone this repo
make build from the repository.
NOTE: please use the latest Go to do this, ideally go 1.13 or greater. A version of Go officially supported upstream by the Go project must be used.
This will put
$(go env GOPATH)/bin. You may need to add that directory to your
shown here if you encounter the error
kind: command not found after installation.
Without installing go, kind can be built reproducibly with docker using
Stable binaries are also available on the releases page.
Stable releases are generally recommended for CI usage in particular.
To install, download the binary for your platform from “Assets” and place this
On macOS / Linux:
curl -Lo ./kind https://github.com/kubernetes-sigs/kind/releases/download/v0.5.1/kind-$(uname)-amd64 chmod +x ./kind mv ./kind /some-dir-in-your-PATH/kind
curl.exe -Lo kind-windows-amd64.exe https://github.com/kubernetes-sigs/kind/releases/download/v0.5.1/kind-windows-amd64 Move-Item .\kind-windows-amd64.exe c:\some-dir-in-your-PATH\kind.exe
Creating a Cluster 🔗︎
Creating a Kubernetes cluster is as simple as
kind create cluster.
This will bootstrap a Kubernetes cluster using a pre-built
node image - you can find it on docker hub
If you desire to build the node image yourself see the
building image section.
To specify another image use the
By default, the cluster will be given the name
--name flag to assign the cluster a different context name.
If you want the
create cluster command to block until the control plane
reaches a ready status, you can use the
--wait flag and specify a timeout.
--wait you must specify the units of the time to wait. For example, to
wait for 30 seconds, do
--wait 30s, for 5 minutes do
--wait 5m, etc.
Interacting With Your Cluster 🔗︎
export KUBECONFIG="$(kind get kubeconfig-path)" kubectl cluster-info
kind get kubeconfig-path returns the location of the generated confguration
If you gave a non-default cluster context name to your cluster, then you can
specify the name by using the
To see all the clusters you have created, you can use the
For example, let’s say you create two clusters:
kind create cluster # Default cluster context name is `kind`. ... kind create cluster --name kind-2
When you list your kind clusters, you will see something like the following:
kind get clusters kind kind-2
Both of these clusters will have a kubeconfig file to go along with them:
kind get kubeconfig-path /home/user/.kube/kind-config-kind kind get kubeconfig-path --name kind-2 /home/user/.kube/kind-config-kind-2
Deleting a Cluster 🔗︎
If you created a cluster with
kind create cluster then deleting is equally
kind delete cluster
If the flag
--name is not specified, kind will use the default cluster
kind and delete that cluster.
Loading an Image Into Your Cluster 🔗︎
Docker images can be loaded into your cluster nodes with:
kind load docker-image my-custom-image
Additionally, image archives can be loaded with:
kind load image-archive /my-image-archive.tar
This allows a workflow like:
docker build -t my-custom-image:unique-tag ./my-image-dir kind load docker-image my-custom-image:unique-tag kubectl apply -f my-manifest-using-my-image:unique-tag
Note: The Kubernetes default pull policy is
the image tag is
:latest in which case the default policy is
IfNotPresent causes the Kubelet to skip pulling an image if it already exists.
If you want those images loaded into node to work as expected, please:
- don’t use a
and / or:
imagePullPolicy: Neveron your container(s).
See Kubernetes imagePullPolicy for more information.
See also: Using kind with Private Registries.
Building Images 🔗︎
kind runs a local Kubernetes cluster by using Docker containers as “nodes”.
kind uses the
node-image to run Kubernetes artifacts, such
node-image in turn is built off the
installs all the dependencies needed for Docker and Kubernetes to run in a
See building the base image for more advanced information.
Currently, kind supports two different ways to build a
if you have the Kubernetes source in your host machine
$GOPATH/src/k8s.io/kubernetes), by using
To specify the build type use the flag
Note however that using
--type=bazel on Windows or MacOS will not work
currently due to Kubelet using CGO which requires GCC/glibc for linux.
A workaround may be enabled in the future.
kind will default to using the build type
docker if none is specified.
kind build node-image --type bazel
Similarly as for the base-image command, you can specify the name and tag of
the resulting node image using the flag
If you previously changed the name and tag of the base image, you can use here
--base-image to specify the name and tag you used.
Note: If you are running kind on MacOS or Windows then it is recommended that you have at least 8GB of RAM dedicated to the virtual machine (VM) running the Docker engine otherwise Building Kubernetes may fail.
To change the resource limits for the Docker on Mac, you’ll need to open the
Now, go to the Advanced settings page, and change the
settings there, see changing Docker’s resource limits.
To change the resource limits for the Docker on Windows, you’ll need to right-click the Moby icon on the taskbar, and choose “Settings”. If you see “Switch to Linux Containers”, then you’ll need to do that first before opening “Settings”
Now, go to the Advanced settings page, and change the settings there, see changing Docker’s resource limits.
You may also try removing any unused data left by the Docker engine - e.g.,
docker system prune.
Building The Base Image 🔗︎
To build the
base-image we use the
kind build base-image
If you want to specify the path to the base image source files you can use the
--source is not specified, kind will attempt to automatically locate
images/base base source directory.
By default, the base image will be tagged as
If you want to change this, you can use the
kind build base-image --image base:v0.1.0
Configuring Your kind Cluster 🔗︎
When creating your kind cluster, via
create cluster, you can use a
configuration file to run specific commands before or after systemd or kubeadm
For a sample kind configuration file see kind-example-config.
To specify a configuration file when creating a cluster, use the
kind create cluster --config kind-example-config.yaml
Multi-node clusters 🔗︎
In particular, many users may be interested in multi-node clusters. A simple configuration for this can be achieved with the following config file contents:
# three node (two workers) cluster config kind: Cluster apiVersion: kind.sigs.k8s.io/v1alpha3 nodes: - role: control-plane - role: worker - role: worker
Control-plane HA 🔗︎
You can also have a cluster with multiple control-plane nodes:
# a cluster with 3 control-plane nodes and 3 workers kind: Cluster apiVersion: kind.sigs.k8s.io/v1alpha3 nodes: - role: control-plane - role: control-plane - role: control-plane - role: worker - role: worker - role: worker
Mapping ports to the host machine 🔗︎
You can map extra ports from the nodes to the host machine with
kind: Cluster apiVersion: kind.sigs.k8s.io/v1alpha3 nodes: - role: control-plane - role: worker extraPortMappings: - containerPort: 80 hostPort: 80 listenAddress: "0.0.0.0" # Optional, defaults to "0.0.0.0" protocol: udp # Optional, defaults to tcp
This can be useful if using
NodePort services or daemonsets exposing host ports.
Note: binding the
127.0.0.1 may affect your ability to access the service.
Enable Feature Gates in Your Cluster 🔗︎
Feature gates are a set of key=value pairs that describe alpha or experimental features. In order to enable a gate you have to customize your kubeadm configuration, and it will depend on what gate and component you want to enable. An example kind config can be:
# this config file contains all config fields with comments kind: Cluster apiVersion: kind.sigs.k8s.io/v1alpha3 # patch the generated kubeadm config with some extra settings kubeadmConfigPatches: - | apiVersion: kubeadm.k8s.io/v1beta2 kind: ClusterConfiguration metadata: name: config apiServer: extraArgs: "feature-gates": "FeatureGateName=true" scheduler: extraArgs: "feature-gates": "FeatureGateName=true" controllerManager: extraArgs: "feature-gates": "FeatureGateName=true" - | apiVersion: kubeadm.k8s.io/v1beta2 kind: InitConfiguration metadata: name: config nodeRegistration: kubeletExtraArgs: "feature-gates": "FeatureGateName=true" # 1 control plane node and 3 workers nodes: # the control plane node config - role: control-plane # the three workers - role: worker - role: worker - role: worker
IPv6 clusters 🔗︎
You can run ipv6 only clusters using
kind, but first you need to enable ipv6 in your docker daemon by editing
/etc/docker/daemon.json as described here.
systemctl restart docker to pick up the changes.
# an ipv6 cluster kind: Cluster apiVersion: kind.sigs.k8s.io/v1alpha3 networking: ipFamily: ipv6 nodes: # the control plane node - role: control-plane - role: worker - role: worker
Configure kind to use a proxy 🔗︎
If you are running kind in an environment that requires a proxy, you may need to configure kind to use it.
You can configure kind to use a proxy using one or more of the following environment variables (uppercase takes precedence):
- HTTP_PROXY or http_proxy
- HTTPS_PROXY or https_proxy
- NO_PROXY or no_proxy
Note: If you set a proxy it would be used for all the connection requests.
It’s important that you define what addresses doesn’t need to be proxied with the NO_PROXY variable, typically you should avoid to proxy your docker network range
Exporting Cluster Logs 🔗︎
kind has the ability to export all kind related logs for you to explore.
To export all logs from the default cluster (context name
kind export logs Exported logs to: /tmp/396758314
Like all other commands, if you want to perform the action on a cluster with a
different context name use the
As you can see, kind placed all the logs for the cluster
kind in a
temporary directory. If you want to specify a location then simply add the path
to the directory after the command:
kind export logs ./somedir Exported logs to: ./somedir
The structure of the logs will look more or less like this:
. ├── docker-info.txt └── kind-control-plane/ ├── containers ├── docker.log ├── inspect.json ├── journal.log ├── kubelet.log ├── kubernetes-version.txt └── pods/
The logs contain information about the Docker host, the containers running kind, the Kubernetes cluster itself, etc.