Quick Start

This guide covers getting started with the kind command.

If you are having problems please see the known issues guide.

Installation

You can either install kind with GO111MODULE="on" go get sigs.k8s.io/kind@v0.7.0 or clone this repoand run 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 kind in $(go env GOPATH)/bin. You may need to add that directory to your $PATH asshown here if you encounter the errorkind: command not found after installation.

Without installing go, kind can be built reproducibly with docker using make build.

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 thisinto your $PATH.

On macOS / Linux:

  1. curl -Lo ./kind https://github.com/kubernetes-sigs/kind/releases/download/v0.7.0/kind-$(uname)-amd64
  2. chmod +x ./kind
  3. mv ./kind /some-dir-in-your-PATH/kind

On Mac via Homebrew:

  1. brew install kind

On Windows:

  1. curl.exe -Lo kind-windows-amd64.exe https://github.com/kubernetes-sigs/kind/releases/download/v0.7.0/kind-windows-amd64
  2. Move-Item .\kind-windows-amd64.exe c:\some-dir-in-your-PATH\kind.exe

OR via Chocolatey (https://chocolatey.org/packages/kind)

  1. choco install kind

Creating a Cluster

Creating a Kubernetes cluster is as simple as kind create cluster.

This will bootstrap a Kubernetes cluster using a pre-builtnode image - you can find it on docker hubkindest/node.If you desire to build the node image yourself see thebuilding image section.To specify another image use the —image flag.

By default, the cluster will be given the name kind.Use the —name flag to assign the cluster a different context name.

If you want the create cluster command to block until the control planereaches a ready status, you can use the —wait flag and specify a timeout.To use —wait you must specify the units of the time to wait. For example, towait for 30 seconds, do —wait 30s, for 5 minutes do —wait 5m, etc.

Interacting With Your Cluster

After creating a cluster, you can use kubectlto interact with it by using the configuration file generated by kind.

By default, the cluster access configuration is stored in ${HOME}/.kube/configif $KUBECONFIG environment variable is not set.

If $KUBECONFIG environment variable is set, then it is used as a list of paths(normal path delimiting rules for your system). These paths are merged. When a valueis modified, it is modified in the file that defines the stanza. When a value is created,it is created in the first file that exists. If no files in the chain exist,then it creates the last file in the list.

You can use the —kubeconfig flag when creating the cluster, then only that file is loaded.The flag may only be set once and no merging takes place.

To see all the clusters you have created, you can use the get clusterscommand.

For example, let's say you create two clusters:

  1. kind create cluster # Default cluster context name is `kind`.
  2. ...
  3. kind create cluster --name kind-2

When you list your kind clusters, you will see something like the following:

  1. kind get clusters
  2. kind
  3. kind-2

In order to interact with a specific cluster, you only need to specify thecluster name as a context in kubectl:

  1. kubectl cluster-info --context kind-kind
  2. kubectl cluster-info --context kind-2

Deleting a Cluster

If you created a cluster with kind create cluster then deleting is equallysimple:

  1. kind delete cluster

If the flag —name is not specified, kind will use the default clustercontext name 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

Note: If using a named cluster you will need to specify the name of thecluster you wish to load the image into:kind load docker-image my-custom-image —name kind-2

Additionally, image archives can be loaded with:kind load image-archive /my-image-archive.tar

This allows a workflow like:

  1. docker build -t my-custom-image:unique-tag ./my-image-dir
  2. kind load docker-image my-custom-image:unique-tag
  3. kubectl apply -f my-manifest-using-my-image:unique-tag

Note: The Kubernetes default pull policy is IfNotPresent unlessthe image tag is :latest in which case the default policy is Always.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 :latest tag

and / or:

  • specify imagePullPolicy: IfNotPresent or imagePullPolicy: Never on your container(s).

See Kubernetes imagePullPolicy for more information.

See also: Using kind with Private Registries.

Building Images

Note: If you're using Docker Desktop, be sure to read Settings for Docker Desktop first.

kind runs a local Kubernetes cluster by using Docker containers as “nodes”.kind uses the node-image to run Kubernetes artifacts, suchas kubeadm or kubelet.The node-image in turn is built off the base-image, whichinstalls all the dependencies needed for Docker and Kubernetes to run in acontainer.

See building the base image for more advanced information.

Currently, kind supports two different ways to build a node-imageif you have the Kubernetes source in your host machine($GOPATH/src/k8s.io/kubernetes), by using docker or bazel.To specify the build type use the flag —type.Note however that using —type=bazel on Windows or MacOS will not workcurrently 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.

  1. kind build node-image --type bazel

Similarly as for the base-image command, you can specify the name and tag ofthe resulting node image using the flag —image.

If you previously changed the name and tag of the base image, you can use herethe flag —base-image to specify the name and tag you used.

Settings for Docker Desktop

If you are building Kubernetes (for example - kind build node-image) on MacOS or Windows then you need a minimum of 6GB of RAMdedicated to the virtual machine (VM) running the Docker engine. 8GB is recommended.

To change the resource limits for the Docker on Mac, you'll need to open thePreferences menu.

Quick Start - 图1

Now, go to the Advanced settings page, and change thesettings there, see changing Docker's resource limits.

Setting 8Gb of memory in Docker for Mac

To change the resource limits for the Docker on Windows, you'll need to right-click the Mobyicon on the taskbar, and choose “Settings”. If you see “Switch to Linux Containers”, then you'll needto do that first before opening “Settings”

Quick Start - 图3

Now, go to the Advanced settings page, and change thesettings there, see changing Docker's resource limits.

Setting 8Gb of memory in Docker for Windows

You may also try removing any unused data left by the Docker engine - e.g.,docker system prune.

Advanced

Building The Base Image

To build the base-image we use the build command:

  1. kind build base-image

If you want to specify the path to the base image source files you can use the—source flag.

If —source is not specified, kind will attempt to automatically locatethe images/base base source directory.

By default, the base image will be tagged as kindest/base:latest.If you want to change this, you can use the —image flag.

  1. kind build base-image --image base:v0.1.0

Configuring Your kind Cluster

When creating your kind cluster, via create cluster, you can use aconfiguration file to run specific commands before or after systemd or kubeadmrun.For a sample kind configuration file see kind-example-config.To specify a configuration file when creating a cluster, use the —configflag:

  1. kind create cluster --config kind-example-config.yaml

Multi-node clusters

In particular, many users may be interested in multi-node clusters. A simpleconfiguration for this can be achieved with the following config file contents:

  1. # three node (two workers) cluster config
  2. kind: Cluster
  3. apiVersion: kind.x-k8s.io/v1alpha4
  4. nodes:
  5. - role: control-plane
  6. - role: worker
  7. - role: worker

Control-plane HA

You can also have a cluster with multiple control-plane nodes:

  1. # a cluster with 3 control-plane nodes and 3 workers
  2. kind: Cluster
  3. apiVersion: kind.x-k8s.io/v1alpha4
  4. nodes:
  5. - role: control-plane
  6. - role: control-plane
  7. - role: control-plane
  8. - role: worker
  9. - role: worker
  10. - role: worker

Mapping ports to the host machine

You can map extra ports from the nodes to the host machine with extraPortMappings:

  1. kind: Cluster
  2. apiVersion: kind.x-k8s.io/v1alpha4
  3. nodes:
  4. - role: control-plane
  5.   extraPortMappings:
  6.   - containerPort: 80
  7.     hostPort: 80
  8.     listenAddress: "0.0.0.0" # Optional, defaults to "0.0.0.0"
  9.     protocol: udp # Optional, defaults to tcp

This can be useful if using NodePort services or daemonsets exposing host ports.

Note: binding the listenAddress to 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:

  1. kind: Cluster
  2. apiVersion: kind.x-k8s.io/v1alpha4
  3. # patch the generated kubeadm config with a featuregate
  4. kubeadmConfigPatches:
  5. - |
  6.   kind: ClusterConfiguration
  7.   metadata:
  8.     name: config
  9.   apiServer:
  10.     extraArgs:
  11.       "feature-gates": "FeatureGateName=true"
  12.   scheduler:
  13.     extraArgs:
  14.       "feature-gates": "FeatureGateName=true"
  15.   controllerManager:
  16.     extraArgs:
  17.       "feature-gates": "FeatureGateName=true"
  18. - |
  19.   kind: InitConfiguration
  20.   metadata:
  21.     name: config
  22.   nodeRegistration:
  23.     kubeletExtraArgs:
  24.       "feature-gates": "FeatureGateName=true"
  25. - |
  26.   kind: KubeletConfiguration
  27.   featureGates:
  28.     FeatureGateName: true
  29. - |
  30.   kind: KubeProxyConfiguration
  31.   featureGates:
  32.     FeatureGateName: true

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.Ensure you systemctl restart docker to pick up the changes.

  1. # an ipv6 cluster
  2. kind: Cluster
  3. apiVersion: kind.x-k8s.io/v1alpha4
  4. networking:
  5.   ipFamily: ipv6

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 NO_PROXY=172.17.0.0/16

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):

  1. kind export logs
  2. Exported logs to: /tmp/396758314

Like all other commands, if you want to perform the action on a cluster with adifferent context name use the —name flag.

As you can see, kind placed all the logs for the cluster kind in atemporary directory. If you want to specify a location then simply add the pathto the directory after the command:

  1. kind export logs ./somedir  
  2. Exported logs to: ./somedir

The structure of the logs will look more or less like this:

  1. .
  2. ├── docker-info.txt
  3. └── kind-control-plane/
  4.     ├── containers
  5.     ├── docker.log
  6.     ├── inspect.json
  7.     ├── journal.log
  8.     ├── kubelet.log
  9.     ├── kubernetes-version.txt
  10.     └── pods/

The logs contain information about the Docker host, the containers runningkind, the Kubernetes cluster itself, etc.