2.4 Kubernetes API Server Architecture
The Kubernetes API Server Architecture manages cluster state, exposes REST APIs, and enables communication between users and the control plane.
Kubernetes API Server Architecture is the specific internal structure of the API server as a request-processing pipeline, describing the sequential stages, authentication, authorization, admission, and validation, that every request passes through, along with the internal layering that separates request handling from the underlying storage interaction with etcd.
Request Pipeline Architecture
A Fixed Sequence of Stages
The API server is architected around a fixed pipeline of stages that every incoming request passes through in the same order: authentication to establish identity, authorization to determine permission, admission control to apply further validation and mutation, and finally, persistence to the data store.
Each Stage as a Pluggable Chain
Rather than being a single monolithic check, each stage in this pipeline is architected as a chain of pluggable handlers; authentication can chain multiple authenticator mechanisms, authorization can chain multiple authorizer modules, and admission runs through an ordered chain of mutating and validating plugins.
Storage Layer Architecture
An Abstraction Above etcd
The API server is architected with a storage abstraction layer separating its request-handling logic from the specific data store implementation beneath it; this layer is what allows the API server's resource-handling code to remain independent of etcd's own storage and consensus mechanics.
Watch Cache for Efficient Reads
To avoid burdening etcd with every read request, the API server architecture includes an in-memory watch cache, serving many read and watch requests directly from memory while still relying on etcd as the authoritative source for writes and for the initial population of that cache.
Multi-Version and Group Architecture
Internal Representation vs. External Versions
Internally, the API server architecture converts between multiple external API versions and a single internal representation for each resource type, allowing older and newer clients to interact with the same underlying object using whichever version they understand.
API Groups as an Organizational Layer
Resources are architecturally organized into API groups, each capable of evolving somewhat independently, which is part of what allows the API surface to grow over time, through both built-in additions and custom resource registration, without requiring a single global versioning scheme across the entire API.
Extension Points Within the Architecture
Aggregation as a Structural Extension
The aggregation layer is architected as a mechanism allowing entirely separate API servers to be registered beneath the main server's URL space, extending the overall API surface at a structural level beyond what the core server's own resource-handling code implements.
Webhook Callouts Within the Admission Stage
Within the admission stage specifically, the architecture supports calling out to external webhook services over the network, meaning a portion of the admission chain can be extended by systems running entirely outside the API server process itself.