kube-apiserver

The kube-apiserver is the only component that talks to etcd. Every other component reads and writes cluster state by going through it. It validates, defaults, authenticates, authorizes, admits, persists, and serves watches. Conceptually it is one HTTP/2 server with many handlers; mechanically it is the composition of three apiserver "levels" (extensions, kube, aggregator) and a forest of REST registries.

Directory layout

cmd/kube-apiserver/
├── apiserver.go              # main(), 5 lines; calls app.NewAPIServerCommand
└── app/
    ├── server.go             # Cobra command, flag parsing, run loop
    ├── options/              # Strongly typed flag groups (auth, audit, etcd, encryption, etc.)
    ├── config.go             # Build the runtime Config from Options
    ├── aggregator.go         # Configure the kube-aggregator chain
    └── ...

pkg/controlplane/             # Boot-time wiring: what resources are served, what reconcilers run
├── instance.go               # The "kube-apiserver" instance assembly
├── controller/               # Lease-driven endpoint reconciler, kube-system bootstrap
└── apiserver/

pkg/kubeapiserver/            # Pieces specific to the kube-apiserver flavor of generic-apiserver
├── admission/                # Admission-plugin selection
├── authenticator/            # Authentication chain composition
├── authorizer/               # Authorization chain composition
├── default_storage_factory_builder.go
└── options/                  # Apiserver-specific flag groups

pkg/registry/                 # One subdirectory per API group, then per resource:
├── core/{pod,node,service,...}/{rest,storage,strategy.go}
├── apps/{deployment,replicaset,statefulset,...}
├── batch/{job,cronjob}
├── networking/{ingress,networkpolicy,...}
├── rbac/...
├── apiserverinternal/...
└── ...

Boot sequence

1. main() in cmd/kube-apiserver/apiserver.go calls app.NewAPIServerCommand().
2. Flag parsing by Cobra. Options come from cmd/kube-apiserver/app/options (kube-apiserver flavored) and from the embedded generic-apiserver options in staging/src/k8s.io/apiserver/pkg/server/options.
3. Validation of the assembled *Options value.
4. Config assembly in cmd/kube-apiserver/app/config.go. This is the slow step: build the storage factory, pick the authentication chain, compose authorization, build admission, set up the audit pipeline, configure egress selector / KMS, configure flowcontrol, and wire in the leader-election lease.
5. Run apiserver.Complete() then apiserver.Run(ctx). The aggregator wraps the kube-apiserver, which wraps the apiextensions-apiserver. The chain is aggregator → kube → apiextensions → not-found.
6. Post-start hooks kick off bootstrap controllers: cluster authentication, RBAC bootstrap, default storage version, namespace existence, and a few apiserver-internal repair loops. See pkg/controlplane/controller/.

How it serves requests

graph LR
    Client -->|HTTP/2| Mux[generic-apiserver<br/>net/http mux]
    Mux --> Filters[Filter chain]
    Filters -->|authentication| AuthN
    Filters -->|authorization| AuthZ
    Filters -->|admission| Admit
    Filters --> Handler[REST handler<br/>pkg/registry/...]
    Handler --> Storage[generic registry<br/>etcd3 + watch cache]
    Storage --> etcd[(etcd)]

The filter chain is built once at startup. Each filter is a http.Handler that runs in a fixed order:

1. WithPanicRecovery
2. WithRequestInfo (parses the URL into kind, version, verb, subresource)
3. WithCacheControl
4. WithAuthentication
5. WithAudit
6. WithImpersonation
7. WithMaxInFlightLimit / WithPriorityAndFairness
8. WithAuthorization
9. Per-handler chain ending in the strategy + storage call

See staging/src/k8s.io/apiserver/pkg/server/genericapiserver.go for the canonical chain.

Storage layer

Each REST handler delegates to a Storage implementation built on staging/src/k8s.io/apiserver/pkg/registry/generic/registry/store.go. This generic store knows how to:

• Translate REST verbs into etcd operations (Create, Update, Get, List, Delete, Watch).
• Run the strategy hooks (validation, defaulting, status preservation).
• Maintain a watch cache (staging/src/k8s.io/apiserver/pkg/storage/cacher/) so most reads and watches don't hit etcd.
• Serve consistent reads via either etcd revision or cache snapshot, depending on feature gates.
• Apply server-side apply patches.

Resource-specific knobs live in pkg/registry/<group>/<resource>/strategy.go (validation, status fields, drop-disabled-fields helpers) and pkg/registry/<group>/<resource>/storage/storage.go (which subresources exist, what the etcd key prefix is).

Aggregation

kube-aggregator (in staging/src/k8s.io/kube-aggregator) is layered above kube-apiserver. It serves APIService objects, validates extension API server certificates, and proxies requests for non-built-in groups to those extension servers. CRDs go through apiextensions-apiserver (in staging/src/k8s.io/apiextensions-apiserver), which is itself an aggregated API server.

Subsystem deep dives

• REST registry layer — how a REST endpoint becomes wired up
• Authentication, authorization, and admission chain

Key source files

File	Purpose
cmd/kube-apiserver/apiserver.go	main entry point
cmd/kube-apiserver/app/server.go	Cobra command, run loop
cmd/kube-apiserver/app/options/options.go	Top-level flag aggregator
cmd/kube-apiserver/app/aggregator.go	Configure the kube-aggregator
pkg/controlplane/instance.go	Assemble the kube-apiserver instance
pkg/controlplane/import_known_versions.go	Register every built-in API group
pkg/kubeapiserver/admission/config.go	Build the admission chain
pkg/kubeapiserver/authenticator/config.go	Build the authentication chain
pkg/kubeapiserver/authorizer/config.go	Build the authorization chain
pkg/kubeapiserver/default_storage_factory_builder.go	Decide where each resource is stored, with what encoding, with which encryption

Integration points

• etcd — the only persistent store, accessed via staging/src/k8s.io/apiserver/pkg/storage/etcd3.
• CRDs — handled by apiextensions-apiserver in staging/src/k8s.io/apiextensions-apiserver.
• Aggregated APIs — proxied through kube-aggregator (staging/src/k8s.io/kube-aggregator).
• Webhooks — admission and authentication/authorization webhooks live in staging/src/k8s.io/apiserver/pkg/admission/plugin/webhook and staging/src/k8s.io/apiserver/pkg/authentication/request/webhook.
• KMS — encryption-at-rest providers in staging/src/k8s.io/kms.
• Service accounts — minted via pkg/serviceaccount/ and the controller in pkg/controller/serviceaccount.

Entry points for modification

• Adding a new built-in API resource: define types in staging/src/k8s.io/api/<group>/<version>/types.go, add validation/defaulting under pkg/apis/<group>/, add a registry under pkg/registry/<group>/<resource>/, and register the storage factory in pkg/controlplane/instance.go.
• Adding a new admission plugin: implement admission.MutationInterface and/or admission.ValidationInterface, drop into plugin/pkg/admission/<name>/, and register in pkg/kubeapiserver/admission/config.go.
• Changing the authentication chain: edit pkg/kubeapiserver/authenticator/config.go. The flag groups are in cmd/kube-apiserver/app/options.