Kubernetes

Kubernetes (often abbreviated "K8s") is an open-source platform for orchestrating containerized workloads across a cluster of machines. This repository, kubernetes/kubernetes, holds the source code for the core Kubernetes control plane and node components: the API server, controller manager, scheduler, kubelet, kube-proxy, kubectl, and kubeadm.

What this repo contains

The repository is a Go monorepo. The most important top-level directories:

Directory	Purpose
cmd/	Entry points (main packages) for every binary the project ships, including kube-apiserver, kube-controller-manager, kube-scheduler, kubelet, kube-proxy, kubectl, kubeadm, kubectl-convert, and several internal gen* doc tools.
pkg/	The bulk of in-tree implementation logic: registry storage, kubelet, scheduler, controllers, proxy modes, volume plugins, RBAC, and admission.
staging/src/k8s.io/	Libraries that are mirrored as their own Go modules at k8s.io/<name> (for example k8s.io/api, k8s.io/apimachinery, k8s.io/client-go, k8s.io/apiserver, k8s.io/kubelet). Code is developed here and published outward.
plugin/	In-tree admission plugins.
test/	Unit, integration, end-to-end (test/e2e), node e2e (test/e2e_node), conformance, and fuzz suites.
cluster/	Legacy cluster-bring-up scripts and configurations used by local-up-cluster.sh and the kube-up/kube-down flow.
hack/	Build, codegen, lint, vendor management, and CI helper scripts.
build/	Release tooling, container build assets, and the canonical Makefile (symlinked from the root Makefile).
api/	Generated OpenAPI specs (api/openapi-spec/) and API rules.
vendor/	Vendored external Go dependencies.

Who uses this code

• Cluster operators and distributions consume the binaries (kube-apiserver, kubelet, etc.) directly or via distributions such as kubeadm-built clusters, managed services, and packaged distributions.
• Kubernetes contributors read and modify code under pkg/, cmd/, and staging/. SIGs (Special Interest Groups) own different subtrees through the OWNERS files.
• Library users depend on the published staging modules (e.g. k8s.io/client-go, k8s.io/api, k8s.io/apimachinery). The README explicitly states that using k8s.io/kubernetes/... packages directly as a library is not supported.

Quick links

• Architecture overview — how the components fit together
• Getting started — build, run, and test the project locally
• Glossary — the terms used throughout the codebase
• How to contribute — the contributor workflow
• Components (apps) — per-binary deep dives
• Internal systems — shared subsystems (auth, registry, scheduling framework, volume plugins…)
• Staging packages — the published k8s.io/* libraries
• Primitives — Pod, Node, Service, and the other core objects

Tech stack at a glance

• Language: Go (go.mod pins to Go 1.26.x; .go-version records the toolchain)
• Build: GNU Make wrapping a substantial set of shell scripts under hack/ and build/
• Storage: etcd (consumed as a library and as a runtime dependency)
• Container runtime interface: CRI (gRPC, defined in staging/src/k8s.io/cri-api)
• Container Storage Interface: CSI (gRPC, integrated in pkg/volume/csi)
• Container Network Interface: CNI (consumed by kubelet and via kubernetes-network-policies)
• APIs: OpenAPI v2 and v3, gRPC for CRI, plus a custom REST + watch protocol on top of HTTP/2
• Test frameworks: standard go test, Ginkgo for e2e suites, Gomega assertions

The code base spans ~3.57 million lines of Go across ~12,600 non-vendor .go files, of which roughly 3,000 are _test.go files. See by-the-numbers for the full breakdown.