Extending the Kubernetes API

Beyond CRDs, Kubernetes offers additional mechanisms for extending its API server. The API aggregation layer and webhook servers provide more flexibility when CRDs alone are not enough.

API Aggregation Layer

The aggregation layer lets you register external API servers that handle requests for specific API groups. The main Kubernetes API server proxies requests to your extension server transparently.

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: true
  groupPriorityMinimum: 100
  versionPriority: 100

The Metrics Server is the most common example. When you run kubectl top pods, the API server forwards that request to the metrics-server via the aggregation layer.

# See all registered API services
kubectl get apiservices

# Check a specific API service
kubectl get apiservice v1beta1.metrics.k8s.io -o yaml

Admission Webhooks

Admission webhooks intercept API requests before resources are persisted. There are two types:

• ValidatingWebhookConfiguration -- rejects requests that fail custom validation
• MutatingWebhookConfiguration -- modifies resources before they are stored (for example, injecting sidecar containers)

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: pod-policy
webhooks:
  - name: validate.pods.example.com
    rules:
      - apiGroups: [""]
        resources: ["pods"]
        operations: ["CREATE", "UPDATE"]
    clientConfig:
      service:
        name: pod-validator
        namespace: webhooks
        path: /validate
    admissionReviewVersions: ["v1"]
    sideEffects: None

# List webhook configurations
kubectl get validatingwebhookconfigurations
kubectl get mutatingwebhookconfigurations

When to Use Which

Key Takeaways

• The aggregation layer proxies API requests to external servers
• Admission webhooks validate or mutate resources before they are stored
• CRDs cover most extension needs; aggregation and webhooks handle advanced cases