This document provides a high-level introduction to the Kubernetes codebase located at https://github.com/kubernetes/kubernetes. It describes the fundamental architecture, major subsystems, and how they interact to form a complete container orchestration system.
This overview focuses on the runtime components and their organization within the monorepo. For detailed information on specific subsystems:
The Kubernetes repository is a monorepo containing all components needed to build, test, and run a Kubernetes cluster. The codebase is organized into several key directories:
| Directory | Purpose |
|---|---|
cmd/ | Main entry points for cluster binaries (kube-apiserver, kubelet, kube-proxy, kube-scheduler, kube-controller-manager, kubectl). |
pkg/ | Core implementation logic and internal APIs. |
staging/src/k8s.io/ | Published sub-modules (API types, client-go, apimachinery) that are symlinked/vendored back into the main repository go.mod85-116 |
test/ | End-to-end (E2E) and integration tests. |
api/ | Generated OpenAPI specifications and documentation api/openapi-spec/swagger.json1-10 |
vendor/ | External dependencies managed via Go modules vendor/modules.txt1-20 |
Sources: go.mod7-126 vendor/modules.txt1-100 api/openapi-spec/swagger.json1-50
Kubernetes consists of a control plane that manages cluster state and worker nodes that run application containers. The control plane components coordinate through the API server, which persists state in etcd. Worker node components (kubelet and kube-proxy) watch the API server for changes and reconcile local state accordingly.
Sources: pkg/features/kube_features.go17-41 staging/src/k8s.io/api/core/v1/types.go35-150 pkg/apis/core/validation/validation.go126-150
The API server is the central hub of Kubernetes. It exposes the Kubernetes API, validates and processes requests, and persists state to etcd.
Key Code Entities:
staging/src/k8s.io/api/core/v1/types.go staging/src/k8s.io/api/core/v1/types.go36 and internal versions in pkg/apis/core/types.go pkg/apis/core/types.go45pkg/apis/core/validation/validation.go pkg/apis/core/validation/validation.go17pkg/generated/openapi/zz_generated.openapi.go pkg/generated/openapi/zz_generated.openapi.go129Sources: staging/src/k8s.io/api/core/v1/types.go1-50 api/openapi-spec/swagger.json1-100 pkg/apis/core/validation/validation.go126-174
The kubelet runs on each worker node and manages pod lifecycle. It ensures containers defined in PodSpecs are running and healthy.
Key Code Entities:
AllowDNSOnlyNodeCSR pkg/features/kube_features.go46 and ContainerCheckpoint pkg/features/kube_features.go165CPUCFSQuotaPeriod pkg/features/kube_features.go83Sources: pkg/features/kube_features.go41-165 pkg/apis/core/validation/validation.go58-72
The kube-proxy implements Kubernetes service networking by translating Service and EndpointSlice objects into network rules. It supports multiple backends including iptables, IPVS, and nftables (via sigs.k8s.io/knftables go.mod121).
Sources: pkg/features/kube_features.go65 go.mod40-121
All Kubernetes resources are defined as strongly-typed Go structs with validation rules and feature gate integration.
The API object model is defined in the staging/ directory and published as separate modules:
| Package | Purpose | Key Type Examples |
|---|---|---|
k8s.io/api/core/v1 | Core resource types | Pod, Volume, Service staging/src/k8s.io/api/core/v1/types.go36 |
k8s.io/apimachinery | API infrastructure | ObjectMeta, TypeMeta, ResourceList staging/src/k8s.io/api/core/v1/types.go20-22 |
Sources: staging/src/k8s.io/api/core/v1/types.go19-45 pkg/apis/core/types.go45-54
Validation ensures data integrity before persistence.
Key Functions:
ValidateDNS1123Label: Validates names against RFC 1123 pkg/apis/core/validation/validation.go166ValidateQualifiedName: Ensures names follow Kubernetes "qualified name" rules pkg/apis/core/validation/validation.go175ValidateAnnotations: Checks annotation size and format pkg/apis/core/validation/validation.go149Sources: pkg/apis/core/validation/validation.go133-176
Feature gates provide evolutionary control over Kubernetes functionality, allowing features to progress through maturity stages: Alpha → Beta → GA → Deprecated.
All feature gates are defined in pkg/features/kube_features.go:
Lifecycle Tracking: The file test/compatibility_lifecycle/reference/versioned_feature_list.yaml tracks the versioned progression of every gate. For example, ClusterTrustBundle reaches GA in version 1.37 test/compatibility_lifecycle/reference/versioned_feature_list.yaml169
Sources: pkg/features/kube_features.go41-174 test/compatibility_lifecycle/reference/versioned_feature_list.yaml1-200
The Kubernetes codebase is a large monorepo organized around several core components:
go.mod go.mod7 and vendor/modules.txt vendor/modules.txt1Sources: go.mod7-124 vendor/modules.txt1-100 pkg/features/kube_features.go17-41