The Kubernetes API Server

Analogy categoryAnalogies

kube-apiserver is the single front door of a Kubernetes cluster: every kubectl command, controller reconciliation, and kubelet status update passes through its RESTful HTTP interface as a request against a resource under an API group and version. It is stateless and horizontally scalable—any number of replicas can run behind a load balancer because the only state that matters lives in etcd—which is why the API server can be restarted or scaled without losing cluster data.

🏏

Cricket analogy: Every appeal in a match, from a run-out to an LBW, must go through the third umpire's review station before a decision is official, just as every Kubernetes action funnels through kube-apiserver regardless of which component initiated it.

The Request Lifecycle: Authentication, Authorization, Admission

Every request runs through a fixed pipeline: authentication identifies who is making the request (client certificates, bearer tokens, or OIDC), authorization decides whether that identity may perform the requested verb on the resource (almost universally RBAC in modern clusters), and admission control runs a chain of mutating and then validating webhooks that can modify or reject the object before it is persisted. Only after all three stages pass does the object get written to etcd and the request return success to the caller.

🏏

Cricket analogy: Entering an IPL stadium requires showing a ticket to prove identity, then having security check whether that ticket permits access to the VIP section, and finally a bag check before entry—mirroring authentication, authorization, and admission control.

API Groups, Versions, and the OpenAPI Schema

Resources are organized into API groups such as apps/v1 for Deployments or batch/v1 for Jobs, with the core group left unnamed for legacy objects like Pods and Services, and each group can expose multiple versions simultaneously to support safe rolling upgrades of the schema. The API server publishes an OpenAPI v3 schema for every resource that kubectl and client libraries use for validation and code generation, and conversion webhooks let a Custom Resource Definition support multiple versions by converting between them on the fly.

🏏

Cricket analogy: Cricket has different formats—Test, ODI, T20—each with its own rulebook version, just as Kubernetes has API groups like apps/v1 and batch/v1 each governing different resource types with their own schemas.

yaml

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: require-resource-limits
webhooks:
- name: limits.policy.example.com
  clientConfig:
    service:
      name: policy-webhook
      namespace: policy-system
      path: "/validate-pods"
    caBundle: <base64-ca-cert>
  rules:
  - apiGroups: [""]
    apiVersions: ["v1"]
    operations: ["CREATE", "UPDATE"]
    resources: ["pods"]
  admissionReviewVersions: ["v1"]
  sideEffects: None
  failurePolicy: Fail
  timeoutSeconds: 5

kubectl explain deployment.spec.strategy reads directly from the OpenAPI schema kube-apiserver publishes for that resource and API version — it's the same schema client-go and kubectl use to validate objects before ever sending a request, which is why explain output always matches what the server will actually accept.

Extending the API: Aggregation and Admission Webhooks

The aggregation layer lets you register additional APIServices that proxy requests for a given group-version to a separate extension API server, which is how metrics-server exposes metrics.k8s.io without living inside the core binary. Admission webhooks—both MutatingWebhookConfiguration and ValidatingWebhookConfiguration—let you inject sidecars, enforce policy, or set defaults on any resource by having the API server call out to an external HTTPS service during the admission phase, though a slow or unavailable webhook can block all matching requests if failurePolicy is set to Fail.

🏏

Cricket analogy: The DRS ball-tracking vendor is a third-party system the on-field umpires call out to for a ruling before finalizing a decision, just as the API server calls out to an admission webhook before persisting an object.

Setting failurePolicy: Fail on a webhook that matches a broad resource like Pods across all namespaces means an outage or slow response from that webhook's backend can block pod creation cluster-wide — scope webhooks narrowly with objectSelector/namespaceSelector and keep timeoutSeconds low to limit blast radius.

kube-apiserver is the sole entry point for all reads and writes to cluster state.
Every request passes through authentication, authorization, and admission control in that order.
RBAC is the dominant authorization mode in modern clusters.
Resources are organized into API groups and can serve multiple versions concurrently.
The aggregation layer lets extension API servers handle requests for specific API groups.
Mutating webhooks run before validating webhooks in the admission chain.
A misconfigured webhook with failurePolicy Fail can block matching requests cluster-wide.