The Kubernetes API architecture
Tags: kubernetes
Published: 2022-06-08 13:59:41

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

_But how does it actually work?_

![](https://res.cloudinary.com/uasabi/image/upload/v1654590156/threads/api-1.png)

---

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](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-2.png)

---

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.](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-3.png)

---

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.](https://learnk8s.io/rbac-kubernetes)

![In the Kubernetes API server, requests are authenticated and authorized.](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-4.png)

---

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

The API passes the request to the [**Mutation Admission Controller.**](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/)

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.](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-5.png)

---

_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.](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-6.png)

---

_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.](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-7.png)

---

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

[**The Validation Admission Controller does.**](https://learnk8s.io/kubernetes-policies)

_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.](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-8.png)

---

**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.](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-9.png)

---

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](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-10.png)

---

If you managed to pass the Validation Admission Controller, [your resource is safely stored in etcd.](https://learnk8s.io/etcd-kubernetes)

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.](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-11.png)

---

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.**](http://jammy.id/kubernetes/kubernetes-resources-have-no-apiversion.html)

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](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-12.png)

---

**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.](https://res.cloudinary.com/uasabi/image/upload/v1654590155/threads/api-13.png)

---

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

Until next time!