Architecture: The API Proxy

How the Aggregation Layer Works

The Kubernetes API Server (kube-apiserver) is the single entry point for all cluster operations. Every kubectl command, every controller, every webhook — they all talk to this one server. The Aggregation Layer extends this server without modifying it, by teaching it to delegate certain URL paths to other servers.

Here is the flow step by step:

1. A user runs kubectl get widgets.example.com.
2. kubectl sends a GET request to the API server at /apis/example.com/v1/widgets.
3. The API server checks its routing table. It finds an APIService object that claims ownership of the example.com/v1 group-version.
4. The API server proxies the request — it opens a TLS connection to the backend Service (a Pod running in the cluster) and forwards the request.
5. The backend Pod processes the request (queries a database, computes a value, calls an external API) and returns a JSON response.
6. The API server relays that response back to kubectl.

From the user's perspective, this is completely transparent. kubectl get widgets works exactly like kubectl get pods. The response is valid Kubernetes API JSON. Tab completion, --watch, -o yaml — all of it works because the aggregated API speaks the same API conventions as the core Kubernetes API.

Key architectural properties:

• The Extension API Server is just a Pod. It can be scaled, updated, and restarted independently of the main API server.
• The Extension API Server must implement the Kubernetes API conventions (correct JSON structure, status subresource, etc.) or clients will break.
• The main API server handles TLS termination for the client side. The extension server only needs to handle the server-to-server TLS connection from the API server.

Failure mode to understand: If the Extension API Server Pod crashes or becomes unreachable, the APIService transitions to Available: False. Any kubectl command targeting that API group will return a 503 Service Unavailable error. This is different from a missing CRD, which returns a 404. Monitoring APIService availability is a critical platform engineering concern.