Kubernetes API Request Model

Kubernetes API Request Model is the pipeline every request to the API server passes through, from initial connection to final persistence, encompassing authentication, authorization, admission control, validation, and storage as a sequence of distinct stages each request is subjected to regardless of which resource type or client is involved. Understanding this pipeline explains not just how a request succeeds, but precisely where and why it can be rejected, mutated, or delayed at each stage before it ever reaches etcd.

Establishing the Connection

TLS and Client Identification

Every request to the API server arrives over TLS, and the server extracts a client identity from the connection — typically from a client certificate's subject, a bearer token, or another configured authentication method — before any further processing occurs, since nothing downstream can be evaluated without first knowing who is asking.

The Aggregation Layer

For requests targeting a group served by an aggregated API server rather than the core API server itself, the core server acts as a reverse proxy at this stage, forwarding the request onward while still applying its own authentication and authorization decisions first, ensuring aggregated APIs are held to the same access control as built-in ones.

Authentication

Multiple Authenticator Chaining

The API server can be configured with multiple authentication methods simultaneously — client certificates, static tokens, OpenID Connect, webhook-based authentication — evaluated in a defined order, with the first authenticator to successfully identify the request's credentials establishing the request's username and group memberships for every subsequent stage.

Anonymous and Failed Authentication

Requests that no configured authenticator can identify are either rejected outright or, if anonymous access is explicitly enabled, proceed as the system:anonymous user, subject to whatever (typically minimal) authorization that identity is granted, meaning authentication failure does not necessarily halt the pipeline but does sharply constrain what happens next.

Authorization

Evaluating the Request Against Policy

Once identity is established, the API server evaluates whether that identity is permitted to perform the requested verb (get, list, create, update, delete, watch, and so on) against the requested resource, using whichever authorization modules are configured — most commonly RBAC, which evaluates Roles and ClusterRoles bound to the requesting identity.

Deny by Default

Authorization in Kubernetes is deny-by-default: unless some configured authorizer explicitly grants the request, it is rejected, and this default is what makes RBAC policy the primary lever administrators use to constrain what any given user or service account can actually do against the cluster.

Admission Control

Mutating Admission

Requests that pass authorization proceed through a chain of mutating admission plugins and, where configured, mutating admission webhooks, each of which may modify the request object before it proceeds further — injecting default values, sidecar containers, or labels are common examples of mutation performed at this stage.

Validating Admission

After mutation, the request passes through validating admission plugins and validating webhooks, which may reject the request outright based on policy but, unlike mutating admission, must not alter its content; this ordering ensures validation always evaluates the final, fully mutated form of the object.

Schema Validation

Independent of pluggable admission, the API server validates the request body against the target type's OpenAPI schema, rejecting malformed structure, unknown fields (depending on configured strictness), and values that violate declared constraints such as required fields or enumerated value sets.

Persistence and Response

Optimistic Concurrency at Write Time

For update and delete operations, the API server checks the request's resourceVersion (if provided) against the object's current resourceVersion in etcd, rejecting the write with a conflict error if they no longer match, enforcing the optimistic concurrency guarantees the object model depends on.

Writing to etcd and Notifying Watchers

A successful write is persisted to etcd, and the API server then notifies all clients holding an open watch on that resource type of the change, which is the mechanism that propagates the new state to every controller and client interested in it, completing the request's journey from initial connection to cluster-wide visibility.