Extending the API
CRDs and operators are the common way to extend Kubernetes, but they are not the only one. The API surface itself has several extension points — aggregated API servers, admission webhooks, and authorization webhooks — each suited to a different need.
Most teams only ever need CRDs. This topic maps the full set so you can recognize when a problem calls for something heavier, and avoid reaching for it when it does not.
The Extension Points
Kubernetes is extensible at several layers. CRDs add new object kinds backed by etcd. Aggregated API servers add new kinds backed by your own server and storage. Admission webhooks (Topic 36) intercept and validate or mutate requests. Authorization webhooks delegate access decisions externally. CNI, CSI, and CRI extend networking, storage, and runtime. The art is choosing the lightest mechanism that solves the problem.
CRD vs Aggregated API Server
The key decision is CRD versus aggregated API server. A CRD is simple — declare a schema, and the built-in API server stores the objects in etcd. An aggregated API server is a server you write and run; the main API server proxies a slice of the API path to it. You need one only when a CRD cannot do the job: custom storage (not etcd), complex validation or business logic on read, very high object volume, or specialized operations. It is far more work to build and operate, so the guidance is: use a CRD unless you have a concrete reason you cannot.
| Need | Mechanism |
|---|---|
| A new declarative object kind | CRD |
| Behavior on a custom object | CRD + controller (operator) |
| Custom storage / heavy logic / huge volume | Aggregated API server |
| Validate or mutate requests | Admission webhook |
| Delegate access decisions | Authorization webhook |
Webhooks as Extension
Admission and authorization webhooks extend the API's behavior rather than its schema. Admission webhooks enforce and mutate (covered in Topic 36); authorization webhooks let an external system make allow/deny decisions, useful when access policy lives outside Kubernetes. Both share the same caution: they sit in the request path, so their latency and availability directly affect the API server. A slow or down webhook degrades the cluster.
Choosing the Right Mechanism
The progression in practice: start with a CRD; add a controller if you need behavior; add admission policy for org rules; and only build an aggregated API server if a CRD genuinely cannot meet the requirement. Each step up adds operational weight and a new thing that can fail in the critical path. Over-extending the API — a bespoke API server where a CRD would do — is a common way to create a system only its authors can run.
CRD — declarative kind stored in etcd by the built-in API server. Simple; covers the vast majority of cases.
Aggregated API server — a server you build and run for custom storage, heavy logic, or huge volume. Powerful and far heavier to operate.
- Building an aggregated API server when a CRD would have sufficed.
- Putting slow or fragile webhooks in the request path and degrading the whole API.
- Reaching for the heaviest extension mechanism first instead of the lightest that works.
- Over-extending the API surface so the cluster becomes something only its authors can operate.
- Forgetting that every extension point in the request path is a new availability dependency.
- Default to a CRD; add a controller for behavior and admission policy for rules.
- Build an aggregated API server only for needs a CRD genuinely cannot meet (custom storage, scale, logic).
- Keep webhooks fast and highly available, and scope them narrowly, since they sit in the critical path.
- Choose the lightest mechanism that solves the problem to limit operational weight.
- Treat each extension as an availability dependency and design for its failure.
Knowledge Check
When do you need an aggregated API server instead of a CRD?
- When you need custom storage (not etcd), heavy read logic, or very high object volume a CRD can't handle
- Whenever you register any new object kind through the API, since a CRD can only define a schema and cannot serve real, queryable resources to clients
- To run a controller that watches the custom objects and reconciles them toward their declared desired state on every change
- To enforce admission policy and field-validation rules on every incoming create and update request to the API
What do admission and authorization webhooks extend?
- The API's behavior (validation, mutation, access decisions) rather than its schema
- The cluster's storage backend and the block and file volume drivers that sit behind every persistent claim
- The container runtime on each node that pulls images, unpacks layers, and starts the containers inside a Pod
- The Pod network model and how IP addresses are assigned to each Pod as it is scheduled onto a node
Why prefer the lightest extension mechanism that works?
- Each heavier mechanism adds operational weight and a new failure point in the request path
- Lighter mechanisms are always strictly more capable than the heavier ones and can do everything they do
- CRDs cannot be used in production and are limited to test and development clusters running locally
- Aggregated API servers are not a supported extension point at all and the API rejects them outright
You got correct