Introduction — Kubernetes API Server
The Kubernetes API server (kube-apiserver) is the central control-plane component and the primary gateway for all interactions with a cluster. It exposes Kubernetes as a RESTful API, validates and processes requests, and persists cluster state to etcd. Every client — kubectl, controllers (including the scheduler), kubelets, custom controllers, and external tools — talks to the cluster through the API server.
Key responsibilities
Expose the Kubernetes API (groups, versions, and resources such as Pods, Deployments, Services).
Authenticate and authorize incoming requests (TLS, client certs, tokens, RBAC, ABAC, etc.).
Validate and mutate objects via admission controllers (builtin and custom).
Persist desired state to etcd and serve reads from that store (with caching and watch mechanisms).
Provide watch/event streams so controllers can react to changes efficiently.
Support extension and aggregation (API aggregation layer, CustomResourceDefinitions, aggregated API servers).
Important concepts
REST endpoints: resources are namespaced or cluster-scoped (e.g., GET /api/v1/namespaces/default/pods or /apis/apps/v1/deployments).
Versioning and stability: APIs are grouped and versioned (v1, v1beta1, etc.); deprecation policies guide migration.
Security: TLS by default, RBAC for permissions, audit logging for request visibility.
Scalability & HA: The API server is stateless — you can run multiple replicas behind a load balancer for high availability; persistent state lives in etcd.
Extensibility: CRDs and aggregated API servers let you add new resource types and custom APIs that behave like native Kubernetes objects.
Request handling features: caching, watches, and advanced request management (priority and fairness, rate limiting) to ensure cluster responsiveness.
Example mapping (user command to API call)
- kubectl get pods maps to a GET request like: GET /api/v1/namespaces//pods (often proxied via kubectl or authenticated with a bearer token)
Why it matters Understanding the API server is essential for operating, extending, or building on Kubernetes. It’s the single source of truth and the contract through which all cluster behavior is expressed and controlled.