What is API aggregation in Kubernetes?
Quick Answer
API aggregation lets an entirely separate API server (running as its own component, implementing its own logic) register itself with the main Kubernetes API server and appear as if it were a native part of the Kubernetes API — requests for its registered API group are transparently proxied to the aggregated server. This is a more heavyweight extension mechanism than a CRD, used when you need to implement genuinely custom API behavior (not just a new schema with a standard controller reacting to it) — metrics APIs (like the Metrics API metrics-server implements) are the most common real-world example.
Detailed Answer
How it differs from a CRD
A CRD (see that question) extends the API by adding a new schema that the existing API server itself stores and validates — all the actual request handling still happens inside the one main API server, backed by etcd like everything else. API aggregation is a different, more heavyweight mechanism: it registers a genuinely separate API server process, implementing its own request-handling logic (potentially not backed by etcd at all, and not bound by the standard CRD schema/validation model), and the main API server simply proxies matching requests to it.
apiVersion: apiregistration.k8s.io/v1
kind: APIService
metadata:
name: v1beta1.metrics.k8s.io
spec:
service:
name: metrics-server
namespace: kube-system
group: metrics.k8s.io
version: v1beta1
insecureSkipTLSVerify: false
groupPriorityMinimum: 100
versionPriority: 100
This APIService object tells the main API server: "requests for metrics.k8s.io/v1beta1 should be forwarded to the metrics-server Service" — from a client's perspective (kubectl get --raw /apis/metrics.k8s.io/v1beta1/nodes), this looks and behaves exactly like any other native Kubernetes API endpoint, but the actual logic answering the request lives entirely in the separate metrics-server component, not in the main API server or etcd.
Why metrics-server needs this, rather than being a CRD
Metrics-server's data (current CPU/memory usage) is fundamentally not the kind of thing etcd is designed to store — it's constantly changing, real-time, in-memory data with no need for durable persistence or the versioned-object history semantics etcd/CRDs provide. Implementing this as a CRD would force an awkward fit (constantly writing rapidly-changing snapshot data as etcd-backed objects); API aggregation instead lets metrics-server serve this data from its own purpose-built, in-memory implementation, while still appearing as a normal, integrated part of the Kubernetes API that kubectl and the HPA (see that question) can query uniformly.
When to reach for API aggregation vs. a CRD
| CRD (+ optional controller/Operator) | API aggregation | |
|---|---|---|
| Backing storage | etcd (via the main API server) | Whatever the aggregated API server implements itself |
| Implementation effort | Lower — mostly declaring a schema, optionally a controller | Higher — building and running an entire separate API server |
| Typical use case | Representing a new kind of object with standard CRUD + reconciliation | Custom, non-standard request handling; data that doesn't fit the object-storage model (metrics, specialized queries) |
| Real-world examples | Most Operators (databases, certificate management, service meshes) | metrics-server, custom authorization/authentication extensions |
The overwhelming majority of Kubernetes extensibility needs — representing a new application-specific concept, building automation/reconciliation around it — are well served by a CRD plus a controller/Operator, which is significantly simpler to build and maintain than a full aggregated API server. API aggregation is reserved for the comparatively rare cases where you genuinely need custom request-handling logic that doesn't fit the standard "object stored in etcd, reconciled by a controller" model — metrics-server remains the most commonly cited real-world example precisely because its use case (ephemeral, real-time data) is a poor fit for CRDs but a good fit for aggregation.
Recognizing that API aggregation and CRDs solve different classes of extension problems — and specifically that metrics-server uses aggregation rather than being a CRD, and why — demonstrates a level of Kubernetes internals understanding beyond the more commonly discussed CRD/Operator pattern alone.