Sign in
Log inSign up
The Kubernetes API architecture

The Kubernetes API architecture

Daniele Polencic's photo
Daniele Polencic
·Jun 8, 2022·

4 min read

The Kubernetes API server handles all of the requests to your Kubernetes cluster.

But how does it actually work?


When you type kubectl apply -f my.yaml, your YAML is sent to the API and stored in etcd.

But what is the API server doing?

High-level overview of the Kubernetes API


The API has a single block in the diagram, but the reality is that several components are involved in processing your request in sequence.

The first module is the HTTP handler.

This is nothing more than a regular web server.

The Kubernetes API is modular. The first component is the HTTP handler.


Once the API receives the requests, it has to make sure that:

  • You have access to the cluster (authentication).
  • You can create, delete, list, etc. resources (authorization).

This is the part where the RBAC rules are evaluated.

In the Kubernetes API server, requests are authenticated and authorized.


So you're authenticated, and you can create Pods; what's next?

The API passes the request to the Mutation Admission Controller.

This component is in charge of looking at your YAML and modifying it.

What YAML can you change with it, though?

The Kubernetes API server uses the mutation admission controller to add extra fields to your resources.


Does your Pod have an image pull policy?

If not, the admission controller will add "Always" for you.

Is the resource a Pod?

  1. It sets the default Service Account (if none is set).
  2. Adds a volume with the token.

And more!

The Mutation Admission controller comes with a set of default controllers.


After all modifications, does the Pod still look like a Pod?

The API makes a quick check to ensure that the resource is valid against the internal schema.

You don't want malformed YAML to be stored in the cluster.

The Kubernetes API server verifies that the spec for your object definition is valid.


If you try to deploy a Pod in a namespace that doesn't exist, is there anyone stopping you?

The Validation Admission Controller does.

Are you trying to deploy more resources than your quota?

The controller will prevent that too.

The validation admission webhook inspects YAML definitions and checks their validity.


The Validation and the Mutation Admission controller are also customizable.

You can register your scripts and design your checks to decide if a resource should be rejected from reaching etcd.

You can extend the Mutation and Validation admission controller with a webhook.


Two excellent examples of custom Admission controllers:

  • Istio automatically injects an extra container to all Pods (mutation).
  • Gatekeeper (Open Policy Agent) checks your resources against policies and reports violations (validation).

Istio and OPA Gatekeeper use the admission controller to augment and validate Kubernetes resources


If you managed to pass the Validation Admission Controller, your resource is safely stored in etcd.

  1. The request is deserialized.
  2. A runtime object is created in memory.
  3. Finally, the new representation is persisted in etcd.

In the last step in the Kubernetes API, resources are stored in etcd.


It's worth noting that Pods have versions when you define them in YAML.

However, the same Pod does not have a version when stored in the database.

It is stored with an internal representation that can be later deserialized to a version.


And to conclude this thread, the Kubernetes API is also extensible!

You can add your own APIs and register them with Kubernetes.

An excellent example of that is the metrics API server.

The Kubernetes API is extensible


The metrics API server registers itself with the API and exposes extra API endpoints.

It's worth noting that you can integrate with the rest of the API and use the existing authentication and authorization modules from the API server.

The Metrics Server is an example of extending the Kubernetes API.


And finally, if you've enjoyed this thread, you might also like the Kubernetes workshops that we run at Learnk8s learnk8s.io/training or this collection of past Twitter threads twitter.com/danielepolencic/status/1298543….

Until next time!