Add your own resource types without forking Kubernetes.

A CRD stores new object types in etcd and the API server serves them. An aggregated API proxies to a separate server and stores nothing in etcd.

CustomResourceDefinition

stored in etcd

Registered with a schema; kubectl get works like a built-in.
Served natively by kube-apiserver.
Durable, declarative objects: the foundation of operators.
Example: Certificate (cert-manager), Application (Argo CD).

Aggregated API (APIService)

separate server

Requests are proxied to an independent API server.
Data lives wherever that server keeps it, often not in etcd.
Fits live, transient data, not durable intent.
Example: metrics-server behind kubectl top and the HPA.

see both on a cluster

$ kubectl get crd | head -3            # native, etcd-backed
certificates.cert-manager.io    2026-01-12T09:02:11Z
$ kubectl get apiservices | grep -v Local   # aggregated
v1beta1.metrics.k8s.io   kube-system/metrics-server   True

Reach for a CRD plus a controller when you want a new declarative resource; reach for an aggregated API only for data that must not live in etcd.

CRDs and aggregated APIs extend the API in two different ways

The Kubernetes API is extensible, and understanding the two mechanisms precisely clears up a common confusion. A CustomResourceDefinition registers a new resource type with a schema. After that, the main kube-apiserver serves it natively and stores instances in etcd, so they behave like built-in objects: you can kubectl get them, apply them, watch them, and protect them with RBAC. Pair a CRD with a controller and you have an operator, the pattern behind cert-manager, Argo CD, Prometheus Operator and most platform tooling.

An aggregated API server is a completely separate process registered through an APIService object. The main API server proxies requests for that API group to it. The data does not have to live in etcd at all. The canonical example is metrics-server: live CPU and memory figures change constantly and have no value as durable state, so storing them in etcd (optimised for consistency of low-volume configuration) would be a mismatch. kubectl top and the Horizontal Pod Autoscaler query it through this aggregation layer.

Rule of thumb: if you want users to declare desired state, build a CRD and a controller. If you need to expose transient data or specialised semantics, consider an aggregated API, which is more work to build and operate.

Gotcha: CRDs share the cluster's etcd. A badly written operator creating hundreds of thousands of custom objects can bloat etcd and slow the whole control plane, so treat CRD cardinality as a capacity concern.