Skip to content

RELEASE.md

Latest commit

 

History

History
226 lines (158 loc) · 6.7 KB

RELEASE.md

File metadata and controls

226 lines (158 loc) · 6.7 KB

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

  • 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

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

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

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

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

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

2.1 Ensure the tree is ready

  • 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

./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

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

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

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

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

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

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

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

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

bump docs to 0.31.0

Summary Checklist

Node images (before kind release)

  • 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

  • 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<prev-version> ./hack/release/get-contributors.sh
  • Create GitHub release from v<version> tag, upload binaries from bin/

Documentation

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