Getting started

This page is the fastest path from a fresh clone to a running build, a passing test suite, and a local cluster you can poke at with kubectl.

Prerequisites

• Go matching .go-version (currently 1.26.x). Confirm with go version. The build will reject older toolchains.
• Make (the GNU variant). The repo's Makefile is a symlink to build/root/Makefile.
• etcd for integration and node tests. hack/install-etcd.sh downloads the version the project pins.
• Docker if you want to use the dockerized build (make quick-release) or run e2e against kind/minikube.
• rsync, jq, curl — required by various hack/ scripts.
• Container runtime if you want to run kubelet locally (containerd is the default on local-up-cluster.sh).

The repository's CI runs Linux. macOS and Windows are best-effort for development.

Build

The fastest way to compile every binary:

make

This calls hack/make-rules/build.sh and produces binaries under _output/bin/ (kube-apiserver, kube-controller-manager, kube-scheduler, kubelet, kube-proxy, kubectl, kubeadm, and the gen* doc tools).

Build a single binary:

make WHAT=cmd/kubectl
make WHAT=cmd/kube-apiserver

To produce a release tarball with hashed manifests, container images, and platform-specific archives:

make quick-release   # uses Docker, slower but matches CI
make release-images  # build container images only

The release tooling lives under build/ and is driven by build/release.sh, build/lib/release.sh, and friends.

Run

For a one-shot local cluster on your laptop, the canonical script is:

hack/local-up-cluster.sh

It launches etcd, kube-apiserver, kube-controller-manager, kube-scheduler, kubelet, and kube-proxy on the host, with all components talking to each other over loopback. By default it expects a CRI runtime to be available (containerd is the default; CONTAINER_RUNTIME_ENDPOINT overrides). On exit it tears everything down. Re-run with KUBELET_HOST= and API_HOST= to bind to a different IP.

A second option is kind (Kubernetes IN Docker) for multi-node simulation. Build images with kind build node-image from the repo root.

Test

Unit tests:

make test                    # runs the entire pkg/... and cmd/... unit suite
make test WHAT=./pkg/scheduler/...   # narrow scope

The driver script is hack/test-go.sh. The test suite uses standard go test; make test KUBE_RACE=-race enables the race detector.

Integration tests (require etcd):

make test-integration WHAT=./test/integration/scheduler

End-to-end tests are organized under test/e2e/ (cluster-level) and test/e2e_node/ (single-node kubelet). They are written against Ginkgo and require a running cluster:

hack/ginkgo-e2e.sh --ginkgo.focus="Conformance"
hack/e2e-node-test.sh

The conformance subset is in test/conformance/. Fuzz suites (test/fuzz/) cover API serialization, validation, and conversion code.

Lint and typecheck

hack/verify-all.sh        # one-stop "did I break anything?" runner
make verify               # same, via the Makefile
make verify WHAT=spelling # narrow to a single check

The Go static analysis is golangci-lint driven by hack/golangci.yaml. The linter is wrapped in hack/verify-golangci-lint.sh.

Code generation

A great deal of the source tree is generated. Whenever you change types.go files in pkg/apis/, staging/src/k8s.io/api/, or any CRI/CSI proto, run:

make update                  # the umbrella regenerator
hack/update-codegen.sh        # API codegen (deepcopy/conversion/clientset/informer/lister/openapi)
hack/update-vendor.sh         # refresh vendor/ from go.mod

Generated files are named zz_generated_*.go and are committed to the repo. The pre-submit verify jobs reject PRs that have stale generated output.

Common pitfalls

• Building outside $GOPATH. The build now uses Go modules and works anywhere on disk; older docs that mention $GOPATH/src/k8s.io/kubernetes are out of date.
• Stale generated code. After editing API types, you must rerun codegen. The make verify step catches this in CI.
• etcd not on PATH. hack/install-etcd.sh puts it under third_party/etcd and sets PATH automatically when scripts source hack/lib/.
• CRI runtime missing. local-up-cluster.sh assumes containerd is reachable on the system. On a fresh VM, install it first.
• Leftover state. After local-up-cluster.sh exits, leftover files live under /var/run/kubernetes and /tmp/local-up-cluster.sh.*. Delete them between runs if you change flags.

For the full contributor experience — branching, PR rules, sign-off, review expectations — see how-to-contribute.