Kubernetes API Server Architecture

Kubernetes API Server Architecture is the internal structure of kube-apiserver itself: the ordered chain of handling stages a request passes through inside a single API server process, and the mechanisms by which multiple API server replicas coordinate to present a single, consistent API despite each handling requests independently. Where the API's object model describes what the API looks like from the outside, API server architecture describes how one specific component implements that surface internally and scales it across replicas.

The Internal Request-Handling Chain

Ordered Stages Within a Single Process

Every request entering a kube-apiserver process passes through a fixed internal sequence: TLS termination and authentication, authorization, mutating admission, schema validation and conversion, validating admission, and finally a read or write against the backing store, with each stage formally unable to be skipped or reordered.

Multiple Authenticators, One Decision

An API server is configured with a chain of authenticator plugins, client certificate, bearer token, OIDC, evaluated in order; the first to positively identify the request determines its resolved identity, and if none succeed, the request is rejected before authorization is ever evaluated.

kube-apiserver \
  --client-ca-file=/etc/kubernetes/pki/ca.crt \
  --oidc-issuer-url=https://idp.codartium.example \
  --authorization-mode=Node,RBAC

Storage Interface to etcd

The API Server as etcd's Sole Client

Architecturally, the API server is formally the only component permitted to communicate directly with etcd; every other control plane and node component reaches etcd's data exclusively by going through the API server, a boundary enforced by convention and network policy rather than by etcd itself.

Watch Cache

To avoid every client watch translating into a direct, repeated etcd watch, the API server maintains an in-memory watch cache per resource type, serving list and watch requests from this cache where possible and reducing load on etcd as the number of concurrent clients grows.

API Aggregation Layer

Extending the Served API Surface

Beyond its own built-in resources, the API server includes an aggregation layer capable of proxying requests for registered API groups to separate, independently running API server processes, making an aggregated API server's resources appear as a seamless part of the single API surface a client interacts with.

apiVersion: apiregistration.k8s.io/v1
kind: APIService
metadata:
  name: v1beta1.metrics.k8s.io
spec:
  service:
    name: metrics-server
    namespace: kube-system
  group: metrics.k8s.io
  version: v1beta1

Admission Webhook Dispatch

As part of its internal admission stage, the API server dispatches outbound HTTPS calls to registered mutating and validating webhooks, formally treating them as an extension of its own admission chain despite them running as entirely separate processes, often outside the control plane's own node set.

Statelessness and Horizontal Replication

No Inter-Replica Coordination Required

Because an API server instance holds no authoritative state of its own, beyond ephemeral in-memory caches, multiple replicas can run simultaneously with no coordination protocol between them; any replica can serve any request, with etcd alone providing the consistency guarantee across all of them.

kubectl get --raw /healthz
kubectl get --raw /readyz?verbose

Load Balancing Across Replicas

A load balancer, external or, in some topologies, a client-side mechanism, distributes requests across available API server replicas; because each replica independently authenticates, authorizes, and admits every request it receives, this distribution requires no session affinity or shared request state.

Audit and Observability Hooks

The Audit Pipeline

Internally, the API server runs every processed request through a configurable audit pipeline, recording a structured log entry at each of several defined stages, RequestReceived, ResponseStarted, ResponseComplete, Panic, allowing fine-grained control over how much detail is captured for different categories of request.

apiVersion: audit.k8s.io/v1
kind: Policy
rules:
  - level: RequestResponse
    resources:
      - group: ""
        resources: ["secrets"]

kube-apiserver --audit-log-path=/var/log/kubernetes/audit.log --audit-policy-file=/etc/kubernetes/audit-policy.yaml

Why the API Server Is Architected This Way

Structuring the API server as a stateless request-processing pipeline in front of a single, authoritative etcd backing store is what formally makes horizontal scaling of the control plane's request-handling capacity possible without complicating the consistency model: correctness depends entirely on etcd's own guarantees, while throughput and availability depend on how many API server replicas sit in front of it.