Aggregated API servers

CRD — основной способ расширить Kubernetes API, но не единственный. Есть второй, более тяжёлый и редкий, механизм — aggregated API server. Идея: к kube-apiserver «подключается» отдельный полноценный API server, который обрабатывает запросы к определённой API group. С точки зрения клиента всё прозрачно — он по-прежнему дёргает kubectl get через kube-apiserver, но за scene запрос проксируется на отдельный сервер. Каноничный пример — metrics-server (тот, что отвечает за kubectl top).

Что такое aggregated API server

Aggregated API server (AAS) — это самостоятельный HTTP-сервер, который:

• Реализует Kubernetes API contract: те же verbs (get, list, watch, create, update, patch, delete), тот же AdmissionReview, тот же OpenAPI discovery.
• Регистрируется в kube-apiserver через объект APIService в группе apiregistration.k8s.io/v1.
• Получает прокси-запросы от kube-apiserver: когда приходит запрос на API group, зарегистрированную через APIService, kube-apiserver делает HTTP-запрос на endpoint AAS и проксирует ответ.

AAS сам отвечает за storage, validation, business logic. Он может хранить данные в etcd (своём отдельном или shared с kube-apiserver), в SQL database, в внешнем service, в памяти, где угодно. Это полная свобода — и полная ответственность.

APIService: регистрация AAS

APIService — объект, который регистрирует aggregated API server в kube-apiserver:

apiVersion: apiregistration.k8s.io/v1
kind: APIService
metadata:
  name: v1beta1.metrics.k8s.io        # обязательно <version>.<group>
spec:
  group: metrics.k8s.io               # какую API group обслуживает
  version: v1beta1                     # какую version
  service:
    name: metrics-server               # Service в кластере → AAS Pods
    namespace: kube-system
    port: 443                          # HTTPS endpoint AAS
  insecureSkipTLSVerify: true          # для self-signed cert AAS (production: caBundle)
  caBundle: <base64 CA cert>           # CA, подписавший cert AAS
  groupPriorityMinimum: 100            # для merging conflicting groups (e.g. shadowing built-in)
  versionPriority: 100                 # ordering versions в API discovery

После создания этого объекта kube-apiserver запоминает: «всё, что приходит на /apis/metrics.k8s.io/v1beta1/..., проксировать на https://metrics-server.kube-system.svc:443».

CRD vs Aggregated API: сравнение

Главное различие: CRD — это «расширение хранилища etcd через метаданные»; AAS — это «отдельный сервер, говорящий на K8s API protocol».

Примеры aggregated API server-ов

Канонический use-case AAS — metrics-server: не нужно хранить данные в etcd (они эфемерны), нужно собирать с многих kubelets, нужна низкая latency. CRD не подходит — etcd не дизайнено для high-throughput метрик.

Почему AAS — редкость

В практике 99% extension в Kubernetes — это CRD + Operator. AAS используется в очень узком наборе случаев:

1. Данные с собственным жизненным циклом, отличным от объекта. metrics-server: метрики обновляются каждые 15s, etcd не подходит для таких write rates.
2. Storage backend не etcd. Например, ML model registry с custom DB (объекты огромные, нужна versioning, etcd плохо подходит).
3. Subresources с custom logic. KubeVirt /vnc — это не просто read-write объекта, это live WebSocket session к виртуальной машине.
4. Performance critical. CRD идёт через generic etcd path; AAS может использовать оптимизированный backend.

В большинстве cases CRD + controller покрывают потребность. AAS требует на порядок больше work: реализовать REST API правильно, поддерживать watch streams, реализовать pagination, делать defaulting через webhook, делать version conversion, integrate с RBAC. Это полноценный сервер, а не yaml-объект.

Поток развёртывания metrics-server

Чтобы поставить metrics-server, нужен пакет ресурсов:

# 1. ServiceAccount + RBAC для metrics-server
apiVersion: v1
kind: ServiceAccount
metadata: {name: metrics-server, namespace: kube-system}
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata: {name: system:metrics-server}
rules:
- apiGroups: [""]
  resources: [nodes/metrics, pods]
  verbs: [get, list, watch]
- apiGroups: [""]
  resources: [nodes/stats, nodes/proxy]
  verbs: [get]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata: {name: system:metrics-server}
subjects: [{kind: ServiceAccount, name: metrics-server, namespace: kube-system}]
roleRef: {kind: ClusterRole, name: system:metrics-server, apiGroup: rbac.authorization.k8s.io}
---
# 2. Deployment с metrics-server образом
apiVersion: apps/v1
kind: Deployment
metadata: {name: metrics-server, namespace: kube-system}
spec:
  selector: {matchLabels: {k8s-app: metrics-server}}
  template:
    metadata: {labels: {k8s-app: metrics-server}}
    spec:
      serviceAccountName: metrics-server
      containers:
      - name: metrics-server
        image: registry.k8s.io/metrics-server/metrics-server:v0.7.2
        args:
        - --secure-port=10250
        - --cert-dir=/tmp
        - --kubelet-preferred-address-types=InternalIP
        - --kubelet-insecure-tls               # для kind/minikube; production: проверенный CA
        ports:
        - containerPort: 10250
          name: https
---
# 3. Service exposes Pods на 443
apiVersion: v1
kind: Service
metadata: {name: metrics-server, namespace: kube-system}
spec:
  selector: {k8s-app: metrics-server}
  ports:
  - port: 443
    targetPort: 10250
---
# 4. APIService — регистрирует AAS в kube-apiserver
apiVersion: apiregistration.k8s.io/v1
kind: APIService
metadata: {name: v1beta1.metrics.k8s.io}
spec:
  group: metrics.k8s.io
  version: v1beta1
  service: {name: metrics-server, namespace: kube-system, port: 443}
  insecureSkipTLSVerify: true                  # production: caBundle
  groupPriorityMinimum: 100
  versionPriority: 100

После apply — kubectl top начинает работать через минуту-две (как только metrics-server начнёт scraping и накопит данные).

CKAD scope

CKAD не требует уметь писать AAS. Минимум:

• Знать, что есть такой механизм расширения.
• Понимать, что metrics-server — это AAS, и kubectl top работает через него.
• Различать CRD vs AAS концептуально.
• Уметь troubleshoot: kubectl get apiservice → ищи Available: False.

# Список всех APIServices в кластере
kubectl get apiservice

# Built-in APIServices (всегда Local: True) и aggregated (Local: False, Service: ...)
kubectl get apiservice v1beta1.metrics.k8s.io -o yaml

# Если status.conditions показывает Available=False — AAS Pod упал или RBAC сломан
kubectl describe apiservice v1beta1.metrics.k8s.io

Killer-моменты

• AAS — это полноценный API server рядом с kube-apiserver. Не плагин, не YAML — Go-программа на framework apiserver-runtime.
• APIService — это «route entry» в kube-apiserver. Объект говорит: «всё на этом path проксировать на этот Service».
• AAS управляет своим storage. Это его килer feature и одновременно его сложность. CRD получает etcd «бесплатно», AAS должен выбрать и реализовать.
• metrics-server — единственный AAS, который встречается в каждом production-кластере. Без него HPA + kubectl top не работают.
• Если поставлен APIService и он недоступен (Pod упал), kubectl get на ту group вернёт 503 / timeout. Это легко диагностируется через kubectl get apiservice.