Architecture

A Kubernetes cluster is split into a control plane (the brain) and a set of nodes (worker machines). The control-plane components decide what should run; the node components make it happen.

The big picture

graph TD
    subgraph Clients
        kubectl[kubectl / client-go]
        users[Users / Operators]
    end

    subgraph ControlPlane[Control plane]
        apiserver[kube-apiserver<br/>cmd/kube-apiserver]
        etcd[(etcd)]
        controllers[kube-controller-manager<br/>cmd/kube-controller-manager]
        scheduler[kube-scheduler<br/>cmd/kube-scheduler]
        ccm[cloud-controller-manager<br/>cmd/cloud-controller-manager]
    end

    subgraph Node[Worker node]
        kubelet[kubelet<br/>cmd/kubelet]
        proxy[kube-proxy<br/>cmd/kube-proxy]
        runtime[CRI runtime<br/>containerd / CRI-O]
    end

    users -->|REST + watch| kubectl
    kubectl -->|HTTPS| apiserver
    apiserver <-->|read/write| etcd
    controllers -->|watch + reconcile| apiserver
    scheduler -->|watch unscheduled pods<br/>write Pod.Spec.NodeName| apiserver
    ccm -->|cloud SDKs| apiserver
    kubelet -->|register, heartbeat,<br/>read PodSpec| apiserver
    kubelet -->|gRPC CRI| runtime
    proxy -->|watch Service+EndpointSlice| apiserver
    proxy -->|program iptables/nftables/ipvs| Node

Components in this repo

Every box on the diagram is built from this repository:

Component	Entry point	Responsibility
kube-apiserver	cmd/kube-apiserver/apiserver.go → cmd/kube-apiserver/app/server.go	Front door for all cluster state. Validates, defaults, authenticates, authorizes, admits, persists to etcd, and serves watch streams.
kube-controller-manager	cmd/kube-controller-manager/controller-manager.go → cmd/kube-controller-manager/app/controllermanager.go	Hosts the in-tree controllers: Deployment, ReplicaSet, Job, CronJob, Node lifecycle, Endpoints, Garbage collector, and many more. See pkg/controller/.
kube-scheduler	cmd/kube-scheduler/scheduler.go → pkg/scheduler/scheduler.go	Watches unscheduled pods and binds them to nodes using the scheduling framework (pkg/scheduler/framework).
kubelet	cmd/kubelet/kubelet.go → pkg/kubelet/kubelet.go	Per-node agent. Pulls images, talks CRI to the runtime, manages volumes, reports node and pod status.
kube-proxy	cmd/kube-proxy/ → pkg/proxy/	Per-node service network proxy. Programs iptables, nftables, IPVS, or Windows kernel rules to implement Service VIPs.
kubectl	cmd/kubectl/ → staging/src/k8s.io/kubectl/	The official command-line client.
kubeadm	cmd/kubeadm/	Bootstraps and upgrades minimal viable conformant clusters.
cloud-controller-manager	cmd/cloud-controller-manager/ (sample) plus staging/src/k8s.io/cloud-provider	Decouples cloud-vendor logic from core controllers. The in-repo binary is a sample; vendors ship their own using the same library.

The staging/ tree provides the library code that all of these components consume, and that external projects (CSI drivers, custom controllers, operators) consume too.

Request lifecycle

A typical write — kubectl apply -f deploy.yaml — flows like this:

sequenceDiagram
    participant kubectl
    participant API as kube-apiserver
    participant etcd
    participant Ctrl as controller-manager
    participant Sched as scheduler
    participant Kubelet
    participant Runtime as CRI runtime

    kubectl->>API: PATCH /apis/apps/v1/.../deployments
    API->>API: authn (oidc / x509 / sa token)
    API->>API: authz (RBAC / Node / ABAC)
    API->>API: admission (mutating + validating)
    API->>etcd: persist Deployment object
    API-->>kubectl: 200 OK
    Ctrl->>API: watch Deployments
    Ctrl->>API: create ReplicaSet, then Pods
    Sched->>API: watch unscheduled Pods
    Sched->>API: PATCH Pod.Spec.NodeName=nodeX
    Kubelet->>API: watch Pods on nodeX
    Kubelet->>Runtime: PullImage / RunPodSandbox / CreateContainer
    Runtime-->>Kubelet: container running
    Kubelet->>API: PATCH Pod.Status (running, ready)

Data plane: how API objects move

All cluster state is modeled as REST resources with an OpenAPI schema. Reads use HTTP GET; writes use POST/PUT/PATCH/DELETE. Long-lived watches use a streaming ?watch=true query that yields a sequence of Added / Modified / Deleted / Bookmark events.

Inside the API server, every resource is wired up through the registry pattern. Each resource has a "strategy" (validation, defaulting, transformation between versions) and a "storage" (RESTful endpoints backed by etcd). The wiring lives in pkg/registry/<group>/<resource>/.

Clients use informers (in staging/src/k8s.io/client-go/informers) to maintain a local cache populated by a list-and-then-watch loop. Controllers and the scheduler are built on top of informers; they react to cache updates and call the API server to drive state toward the spec.

Authentication, authorization, and admission

Every API request runs the same pipeline:

1. Authentication — turn a request into a user.Info. Implementations include client certificates, bearer tokens, service account tokens, OIDC, webhook, and bootstrap tokens. See staging/src/k8s.io/apiserver/pkg/authentication/ plus token controllers in pkg/controller/serviceaccount/.
2. Authorization — decide whether the user can do the requested verb on the resource. Modes are RBAC (pkg/registry/rbac, plus staging/src/k8s.io/apiserver/pkg/authorization/), ABAC (legacy), Node authorizer (plugin/pkg/auth/authorizer/node/), and webhook.
3. Admission — mutate and then validate. Built-in plugins live under plugin/pkg/admission/ (e.g. noderestriction, serviceaccount, podsecurity) and dynamic admission webhooks live in staging/src/k8s.io/apiserver/pkg/admission/plugin/webhook/.

See systems/auth-and-admission.md for the deep dive.

Cross-cutting concerns

• Feature gates — every alpha and beta feature is gated behind a named flag declared in pkg/features/kube_features.go. The same registration pattern is used by every component.
• Component-base — shared startup, logging, metrics, leader election, and config-loading code lives in staging/src/k8s.io/component-base. Every binary in cmd/ boots through it.
• CLI — staging/src/k8s.io/component-base/cli wraps Cobra for a uniform --help, version, and signal-handling experience.
• Codegen — generators in staging/src/k8s.io/code-generator (deepcopy, clientset, informers, listers, conversion, defaulter, openapi) are run by the hack/update-codegen.sh script. Hundreds of zz_generated_*.go files are produced automatically and committed.

Where to read next

• The components section drills into each of the seven binaries.
• The systems section covers shared subsystems (registry, scheduling framework, controller framework, auth, volume plugins, networking).
• The primitives section describes the core API objects (Pod, Node, Service, Deployment, etc.) and how they are stored.