Dependencies

go.mod and vendor/ are the source of truth. This page summarises what's there and how to change it.

Module structure

• One top-level module: k8s.io/kubernetes (go.mod at repo root).
• 35 nested staging modules: staging/src/k8s.io/<module>/go.mod. These are mirrored to standalone repos at release time.

Cross-module imports are constrained — see packages/staging-modules.

Vendor

Every external dependency is vendored under vendor/. The vendor tree is committed and updated via:

hack/pin-dependency.sh github.com/foo/bar v1.2.3   # bump go.mod
hack/update-vendor.sh                               # refresh vendor/

hack/lint-dependencies.sh enforces a deny-list (hack/unwanted-dependencies.json) and a stale-import check.

Notable third-party dependencies

The most important ones, from go.mod:

Module	Used for
github.com/spf13/cobra	CLI framework for every binary
github.com/spf13/pflag	POSIX-style flag parsing
github.com/golang/protobuf, google.golang.org/protobuf	Protobuf serialization
google.golang.org/grpc	CRI, CSI, KMS gRPC clients/servers
go.etcd.io/etcd/client/v3	etcd v3 client
github.com/prometheus/client_golang	Prometheus metrics
github.com/prometheus/common	Shared Prometheus types
github.com/google/cel-go	CEL evaluation (admission policy, DRA)
github.com/onsi/ginkgo/v2, github.com/onsi/gomega	E2E test framework
github.com/stretchr/testify	Unit-test assertions
github.com/coredns/corefile-migration	kubeadm CoreDNS upgrades
sigs.k8s.io/knftables	nftables backend
sigs.k8s.io/structured-merge-diff/v6	Server-side apply merge
sigs.k8s.io/yaml	YAML ↔ JSON, used everywhere config is loaded
github.com/blang/semver/v4	Version parsing
github.com/Microsoft/go-winio, github.com/Microsoft/hnslib	Windows runtime support
bitbucket.org/bertimus9/systemstat	Linux system stats (kubelet)
github.com/coreos/go-systemd/v22	Systemd integration
github.com/cyphar/filepath-securejoin	Container filesystem path safety
golang.org/x/{sys,net,crypto,oauth2,...}	Standard "x" packages
k8s.io/utils	Small utility helpers shared across the project
github.com/distribution/reference	OCI image reference parsing
github.com/cpuguy83/go-md2man/v2	Markdown → man page in genman

The full transitive list runs to several hundred packages.

Major version policies

• etcd — pinned to a tested minor. Upgrading involves running the apiserver's storage compatibility tests.
• gRPC — pinned and pinned again; gRPC's API has churned. Upgrades are coordinated with CRI / CSI / KMS plugin maintainers.
• Cobra / pflag — usually upgrade quickly.
• Prometheus — coordinated; Prometheus deprecates types occasionally.
• CEL — upgrades are gated on admission-policy regression tests.

How to add a dependency

1. Run hack/pin-dependency.sh github.com/foo/bar v1.2.3.
2. Run hack/update-vendor.sh.
3. Run hack/lint-dependencies.sh. If the new package or any of its transitive deps is on the deny-list, the script fails.
4. Run make verify for the full check (module-graph, license headers, etc.).
5. If the new module ships under an unusual license, update LICENSES/ and staging/publishing/ to allow it.

How to remove a dependency

1. Delete usages from the source.
2. Run hack/update-vendor.sh. Go modules will see the unused dep and drop it.

Inspecting the dependency graph

go mod graph                              # full graph
go mod why -m github.com/foo/bar           # why is this here?
hack/module-graph.sh                       # check staging module isolation

Generated dependency manifest

vendor/modules.txt is the canonical Go-modules vendor manifest. LICENSES/vendor/ has per-dep license files; the boilerplate verifier checks that every vendored module has the right license file.