Kubernetes API Aggregation Layer: Extending the API Server

Why it exists

Kubernetes needed a way to add significant, non-core API functionality without bloating the main kube-apiserver. It allows new features, like metrics or service brokers, to be developed and deployed independently while still being accessible through the standard Kubernetes API machinery and kubectl.

The mental model

Think of the main kube-apiserver as a reverse proxy with a default backend (itself) and configurable routes. The Aggregation Layer lets you add new routing rules. When a request comes in for /apis/myextension.example.com/v1/..., the API server checks its registrations, sees your custom server owns that path, and proxies the request to it. To the client, it's a seamless part of the Kubernetes API.

How it works

You create a Kubernetes APIService object. This object tells the main API server about your custom API, including its group and version (like metrics.k8s.io/v1beta1), and how to connect to the Service that runs your custom API server pod. The kube-apiserver then proxies requests matching that group/version to your service. Your custom API server must implement the Kubernetes API conventions to integrate properly.

When to use it

Use it when you need to add new API functionality that goes beyond simple data storage. This is the right choice if you need to implement custom verbs (beyond CRUD), have validation logic that is too complex for a CRD validation webhook, or need to connect to a separate backing storage system. The official metrics-server is the classic example.

When not to use it

Do not use the aggregation layer if all you need is to define a new resource type with standard create, read, update, and delete (CRUD) operations. A Custom Resource Definition (CRD) is a much simpler, more robust, and more common solution for that use case. CRDs are managed directly by the kube-apiserver, avoiding the operational overhead of running your own API server.

One canonical example

The Metrics Server. It registers the metrics.k8s.io API group. When you run kubectl top pods, kubectl sends a request to the main API server for a resource under that API group. The API server, via the aggregation layer, proxies this request to the Metrics Server pods. The Metrics Server collects data from kubelets and returns the resource usage, which kubectl then displays. The core API server knows nothing about metrics itself.