kind Documentation

File: README.md Copy Chapter

Please see [Our Documentation](https://kind.sigs.k8s.io/docs/user/quick-start/) for more in-depth installation etc.

kind is a tool for running local Kubernetes clusters using Docker container "nodes".
kind was primarily designed for testing Kubernetes itself, but may be used for local development or CI.

If you have go and docker, podman or nerdctl installed go install sigs.k8s.io/[email protected] && kind create cluster is all you need!

kind consists of:

• Go packages implementing cluster creation, image build, etc.
• A command line interface (kind) built on these packages.
• Docker image(s) written to run systemd, Kubernetes, etc.
• kubetest integration also built on these packages (WIP)

kind bootstraps each "node" with kubeadm. For more details see the design documentation.

NOTE: kind is still a work in progress, see the 1.0 roadmap.

Installation and usage Copy Chapter

For a complete install guide see the documentation here.

You can install kind with go install sigs.k8s.io/[email protected].

NOTE: please use the latest go to do this. KIND is developed with the latest stable go, see .go-version for the exact version we're using.

This will put kind in $(go env GOPATH)/bin. If you encounter the error
kind: command not found after installation then you may need to either add that directory to your $PATH as
shown here or do a manual installation by cloning the repo and run
make build from the repository.

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 this
into your $PATH:

On Linux:

# For AMD64 / x86_64
[ $(uname -m) = x86_64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.33.0/kind-$(uname)-amd64
# For ARM64
[ $(uname -m) = aarch64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.33.0/kind-$(uname)-arm64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

On macOS via Homebrew:

brew install kind

On macOS via MacPorts:

sudo port selfupdate && sudo port install kind

On macOS via Bash:

# For Intel Macs
[ $(uname -m) = x86_64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.33.0/kind-darwin-amd64
# For M1 / ARM Macs
[ $(uname -m) = arm64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.33.0/kind-darwin-arm64
chmod +x ./kind
mv ./kind /some-dir-in-your-PATH/kind

On Windows:

curl.exe -Lo kind-windows-amd64.exe https://kind.sigs.k8s.io/dl/v0.33.0/kind-windows-amd64
Move-Item .\kind-windows-amd64.exe c:\some-dir-in-your-PATH\kind.exe

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

To use kind, you will need to install docker.
Once you have docker running you can create a cluster with:

kind create cluster

To delete your cluster use:

kind delete cluster

To create a cluster from Kubernetes source:

• ensure that Kubernetes is cloned in $(go env GOPATH)/src/k8s.io/kubernetes
• build a node image and create a cluster with:

kind build node-image
kind create cluster --image kindest/node:latest

Multi-node clusters and other advanced features may be configured with a config
file, for more usage see the docs or run kind [command] --help

Community Copy Chapter

Please reach out for bugs, feature requests, and other issues!
The maintainers of this project are reachable via:

• Kubernetes Slack in the #kind channel
• filing an issue against this repo
• The Kubernetes SIG-Testing Mailing List

Current maintainers are @aojea, @BenTheElder, and @stmcginnis - feel free to
reach out if you have any questions!

Pull Requests are very welcome!
If you're planning a new feature, please file an issue to discuss first.

Check the issue tracker for help wanted issues if you're unsure where to
start, or feel free to reach out to discuss. 🙂

See also: our own contributor guide and the Kubernetes community page.

Why kind? Copy Chapter

• kind supports multi-node (including HA) clusters
• kind supports building Kubernetes release builds from source
  • support for make / bash or docker, in addition to pre-published builds
• kind supports Linux, macOS and Windows
• kind is a CNCF certified conformant Kubernetes installer

Code of conduct Copy Section

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.

File: code-of-conduct.md Copy Chapter

Kubernetes Community Code of Conduct

Please refer to our Kubernetes Community Code of Conduct

File: CONTRIBUTING.md Copy Chapter

Contributing Guidelines

Welcome to Kubernetes. We are excited about the prospect of you joining our community! The Kubernetes community abides by the CNCF code of conduct. Here is an excerpt:

As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

Getting Started Copy Chapter

We have full documentation on how to get started contributing here: https://kind.sigs.k8s.io/docs/contributing/getting-started/, please read this!
A lot of work went into this guide 🙃

Mentorship Copy Chapter

• Mentoring Initiatives - Kubernetes has a diverse set of mentorship programs available that are always looking for volunteers!

File: RELEASE.md Copy Chapter

kind Release Process

This document describes the steps to cut a new kind release. It is intended for
maintainers who have push access to the upstream repository and the staging
image registry.

Prerequisites Copy Chapter

• GNU sed (macOS: brew install gnu-sed)
• Docker with buildx support
• crane installed (for image promotion to Docker Hub)
• Push access to github.com/kubernetes-sigs/kind
• Push access to gcr.io/k8s-staging-kind
• Push access to kindest on Docker Hub

Phase 1 - Publish Node Images Copy Chapter

Node images must be built, tested, and promoted to Docker Hub before the
kind release so their digest hashes are known and can be embedded in the
release binary.

1.1 Build and push to staging Copy Section

Use hack/release/push-node.sh for Kubernetes v1.31 and later:

./hack/release/push-node.sh v1.35.0

This builds amd64 and arm64 node images and pushes them to
gcr.io/k8s-staging-kind/node:v1.35.0, then creates a multi-arch manifest
list.

You can override the registry or add architectures:

REGISTRY=gcr.io/k8s-staging-kind ARCHES="amd64 arm64" ./hack/release/push-node.sh v1.35.0

1.2 Test with the staging image Copy Section

Update the default image in pkg/apis/config/defaults/image.go to point to the
staging image with its digest, then run CI to validate:

const Image = "gcr.io/k8s-staging-kind/node:v1.35.0@sha256:<digest-from-push>"

Get the digest from the push output, or by inspecting the manifest:

crane digest gcr.io/k8s-staging-kind/node:v1.35.0

1.3 Promote the image to Docker Hub Copy Section

Once testing passes, copy the image from staging to kindest/node on Docker Hub:

crane cp \
  gcr.io/k8s-staging-kind/node:v1.35.0@sha256:<staging-digest> \
  kindest/node:v1.35.0

After promotion, retrieve the Docker Hub digest (it may differ from the staging
digest):

crane digest kindest/node:v1.35.0

1.4 Update the default image to the promoted version Copy Section

Update pkg/apis/config/defaults/image.go with the promoted kindest/node
reference and its digest, then open a PR:

const Image = "kindest/node:v1.35.0@sha256:<dockerhub-digest>"

Phase 2 - Cut the kind Release Copy Chapter

2.1 Ensure the tree is ready Copy Section

• The default node image (pkg/apis/config/defaults/image.go) should reference
  a promoted kindest/node image, not a staging image.
• All CI is green on main.
• The current alpha version in pkg/cmd/kind/version/version.go matches the
  version you are about to release (e.g., versionCore = "0.31.0" with
  versionPreRelease = "alpha").

2.2 Run the release script Copy Section

./hack/release/create.sh 0.31.0 0.32.0

The two arguments are:

• 0.31.0 - the version being released
• 0.32.0 - the next version (the script will create a 0.32.0-alpha pre-release)

The script will:

1. Set versionCore = "0.31.0" and versionPreRelease = "" in
   pkg/cmd/kind/version/version.go
2. Commit with message version v0.31.0 and tag v0.31.0
3. Build cross-platform release binaries into bin/:
   • kind-linux-amd64, kind-linux-arm64
   • kind-darwin-amd64, kind-darwin-arm64
   • kind-windows-amd64
   • .sha256sum file for each binary
4. Set versionCore = "0.32.0" and versionPreRelease = "alpha"
5. Commit with message version v0.32.0-alpha and tag v0.32.0-alpha

At the end the script prints follow-up instructions. Continue with the steps
below.

2.3 Push the commits as a PR Copy Section

git push origin HEAD

Open a PR with the two version commits against main and wait for it to merge.

2.4 Push the tags to upstream Copy Section

After the PR is merged, push both tags to the upstream repository:

git push https://github.com/kubernetes-sigs/kind.git v0.31.0
git push https://github.com/kubernetes-sigs/kind.git v0.32.0-alpha

2.5 Generate the contributor list Copy Section

While the PR is merging or shortly after, generate the list of contributors since
the previous release to include in the GitHub release notes:

LAST_VERSION_TAG=v0.30.0 GITHUB_OAUTH_TOKEN=<token> ./hack/release/get-contributors.sh

The token is optional but avoids GitHub API rate limits. The output is a
markdown-formatted bulleted list of GitHub usernames.

2.6 Create the GitHub release Copy Section

Go to https://github.com/kubernetes-sigs/kind/releases/new and:

1. Select the tag v0.31.0.
2. Set the title to v0.31.0.
3. Write release notes summarizing changes since the previous release. Include
   the contributor list generated above.
4. Upload the binaries from bin/ as release assets:
   • kind-linux-amd64 + kind-linux-amd64.sha256sum
   • kind-linux-arm64 + kind-linux-arm64.sha256sum
   • kind-darwin-amd64 + kind-darwin-amd64.sha256sum
   • kind-darwin-arm64 + kind-darwin-arm64.sha256sum
   • kind-windows-amd64 + kind-windows-amd64.sha256sum
5. Publish the release.

Phase 3 - Update Documentation Copy Chapter

After the GitHub release is published, update the documentation to reference
the new stable version. This is typically done as a separate PR immediately
after the release.

3.1 Update README.md Copy Section

Replace all occurrences of the old version string (e.g., v0.30.0) with the
new one (v0.31.0). The README contains several hardcoded download URLs and
go install commands that need updating.

3.2 Update site/config.toml Copy Section

Update the stable parameter:

[params]
stable = "v0.31.0"

This value is used by the {{< stableVersion >}} shortcode throughout the
website documentation, so this single change updates all version references on
the site.

3.3 Open a PR Copy Section

Commit both files and open a PR. The commit message convention is:

bump docs to 0.31.0

Summary Checklist Copy Chapter

Node images (before kind release) Copy Section

• Build and push node image(s) to staging: ./hack/release/push-node.sh vX.Y.Z
• Test with staging image in pkg/apis/config/defaults/image.go
• Promote to Docker Hub: crane cp gcr.io/k8s-staging-kind/node:vX.Y.Z@sha256:... kindest/node:vX.Y.Z
• Update pkg/apis/config/defaults/image.go to promoted kindest/node reference + merge PR

kind release Copy Section

• Confirm main is green and default image is the promoted kindest/node image
• Run ./hack/release/create.sh <version> <next-version>
• Open PR with the two version commits, wait for merge
• Push tags: git push upstream v<version> and git push upstream v<next-version>-alpha
• Generate contributor list: LAST_VERSION_TAG=v ./hack/release/get-contributors.sh
• Create GitHub release from v<version> tag, upload binaries from bin/

Documentation Copy Section

• Update README.md - replace all old version references
• Update site/config.toml - set stable = "v<version>"
• Open docs PR and merge

File: hack/boilerplate/boilerplate.Dockerfile.txt Copy Chapter

Copyright The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

File: hack/boilerplate/boilerplate.go.txt Copy Chapter

/*
Copyright The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

File: hack/boilerplate/boilerplate.sh.txt Copy Chapter

Copyright The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

File: hack/ci/README.md Copy Chapter

This directory contains glue used to test the kind repo in CI.

We don't recommend reusing anything from these scripts, and intend to replace
them at some point.

File: hack/ci/push-latest-cli/README.md Copy Chapter

This tooling is used for our automated builds.

These are meant to be consumed only by The Kubernetes Project's CI for
testing Kubernetes.

These builds are currently not supported for other purposes.

See github.com/kubernetes/test-infra for the automation that invokes these.

File: hack/ci/push-latest-cli/cloudbuild.yaml Copy Chapter

See https://cloud.google.com/cloud-build/docs/build-config

options:
substitution_option: ALLOW_LOOSE
steps:

• name: gcr.io/k8s-staging-test-infra/krte:latest-master
  env:
  • PULL_BASE_SHA=$_PULL_BASE_SHA
    entrypoint: hack/ci/push-latest-cli/push-latest-cli.sh
    substitutions:
    _GIT_TAG: '12345'
    _PULL_BASE_SHA: 'oops'

File: hack/make-rules/update/README.md Copy Chapter

This directory contains tools used to update dependencies, generated files, etc.

File: hack/make-rules/verify/README.md Copy Chapter

This directory contains tools to verify the state and quality of the repo.

File: hack/third_party/gimme/README.md Copy Chapter

gimme

This is an unmodified copy of gimme, so we don't have to download it
from the internet.

File: hack/tools/README.md Copy Chapter

This directory contains a stub go module used to track version of development
tools like the Kubernetes code generators.

File: hack/tools/.golangci.yml Copy Chapter

version: "2"

run:
timeout: 3m

linters:
default: none

enable:
- errcheck
- govet
- ineffassign
- staticcheck
- gochecknoinits
- revive # replaces golint for now
- misspell
- unparam

settings:
staticcheck:
checks:
- all
revive:
rules:
- name: var-naming
arguments:
- []
- []
- - skip-package-name-checks: true

exclusions:
presets:
- std-error-handling
- common-false-positives
rules:
# this requires renaming all unused parameters, we'd rather leave a preferred
# placeholder name in place when implementing an interface etc.
# we can revisit this later, right now it's generating a lot of new warnings
# after upgrading golangci-lint
- linters:
- revive
text: "^unused-parameter: .*"
# Not all package docstrings add value, so we do not want to enforce it
- linters:
- revive
text: "package-comments: should have a package comment"
- linters:
- staticcheck
text: "ST1000: at least one file in a package should have a package comment"
- linters:
- staticcheck
path: pkg/cmd
text: "ST1005: error strings should not be capitalized"
- linters:
- staticcheck
path: images/kindnetd/cmd
text: "ST1005: error strings should not be capitalized"

formatters:
enable:
- gofmt

File: images/base/README.md Copy Chapter

images/base

This directory contains sources for building the kind base "node" image.

The image can be built with make quick.

Maintenance Copy Chapter

This image needs to do a number of unusual things to support running systemd,
nested containers, and Kubernetes. All of what we do and why we do it
is documented inline in the Dockerfile.

If you make any changes to this image, please continue to document exactly
why we do what we do, citing upstream documentation where possible.

See also pkg/cluster for logic that interacts with this image.

Alternate Sources Copy Chapter

Kind frequently picks up new releases of dependent projects including
containerd, runc, cni, and crictl. If you choose to use the provided Dockerfile
but use build arguments to specify a different base image or application version
for dependencies, be aware that you may possibly encounter bugs and undesired
behavior.

Design Copy Chapter

See base-image for more design details.

File: images/base/cloudbuild.yaml Copy Chapter

See https://cloud.google.com/cloud-build/docs/build-config

options:
substitution_option: ALLOW_LOOSE
machineType: E2_HIGHCPU_32
steps:

• name: gcr.io/k8s-staging-test-infra/gcb-docker-gcloud:latest
  entrypoint: make
  args: ['-C', 'images/base', 'push']

File: images/base/files/etc/crictl.yaml Copy Chapter

runtime-endpoint: unix:///run/containerd/containerd.sock

File: images/base/files/kind/README.txt Copy Chapter

This directory is reserved for KIND ^1 internal purposes.

Modifying or depending on the contents of this directory is NOT supported.

Here be dragons.

File: images/base/files/LICENSES/README.txt Copy Chapter

This directory contains license files and notices from binaries built for this
image and the dependencies of those binaries,
as collected by https://github.com/google/go-licenses.

File: images/base/scripts/third_party/gimme/README.md Copy Chapter

gimme

This is an unmodified copy of gimme, so we don't have to download it
from the internet.