Kubernetes APIService 详解：基于 kube-aggregator 注册与聚合自定义 API 的完整指南

• 教程
• 云原生
• 容器编排

在 Kubernetes 的 API 扩展体系里，APIService是apiregistration.k8s.io组中的核心资源对象，它负责将一个外部（聚合）API server 提供的特定GroupVersion注册进集群，使该 API 能与内置 API 一样被kubectl、认证授权体系和 HPA 等组件统一使用。本文以本仓库 concepts/apiservice.md 为主线，结合 concepts/aggregated-api-server.md 的架构说明与 manifests/HPA/custom-metrics.yaml 的实战清单，完整讲解 APIService 的字段语义、创建与验证流程、集群查询方法，以及它在自定义指标 HPA 场景中的落地方式。读完本文，你将能够读懂任何聚合 API 的注册清单，并独立完成一个自定义 API 从注册到可用的全流程。

APIService 是什么：聚合 API server 的"注册表"

Kubernetes 原生 API server 是一个巨石（monolithic）应用。为了把这块巨石拆开、让用户在不修改 Kubernetes 官方源码的前提下集成自己的 API server，Kubernetes 引入了 Aggregated（聚合的）API server 机制（详见 concepts/aggregated-api-server.md）。

聚合机制的核心组件是kube-aggregator，它负责三件事：

• 提供用于注册 API server 的 API——即apiregistration.k8s.io组，用户通过创建APIService资源对象完成注册；
• 汇总所有 API server 的信息——维护集群中全部已注册 API 的GroupVersion清单；
• 代理所有客户端到 API server 的请求——kubectl、API server 及其他客户端对聚合 API 的请求，统一由它转发到对应的后端服务。

kube-aggregator有两种启用方式：一种是test mode / single-user mode，作为独立进程运行；另一种是gateway mode，kube-apiserver嵌入到kube-aggregator组件中，作为集群的 gateway 聚合所有 apiserver。kube-aggregator的二进制文件已经包含在 Kubernetes release 中。

在 1.7+ 版本中，apiregistration.k8s.io/v1beta1API 已内置在集群中，因此可以直接通过 YAML 定义APIService来注册聚合 API——这正是本文主角APIService的用武之地。

APIService 的结构定义

APIService用来表示一个特定的GroupVersion中的 server。其结构定义位于 Kubernetes 代码仓库的staging/src/k8s.io/kube-aggregator/pkg/apis/apiregistration/types.go中（即apiregistration内部 API 类型定义所在位置），这从侧面说明APIService属于kube-aggregator项目内部核心 API 的一部分。

一个典型的 APIService 示例配置如下（与 manifests/HPA/custom-metrics.yaml 中注册自定义指标 API 的清单一致）：

apiVersion: apiregistration.k8s.io/v1beta1 kind: APIService metadata: name: v1alpha1.custom-metrics.metrics.k8s.io spec: insecureSkipTLSVerify: true group: custom-metrics.metrics.k8s.io groupPriorityMinimum: 1000 versionPriority: 5 service: name: api namespace: custom-metrics version: v1alpha1

APIService 字段详解

使用apiregistration.k8s.io/v1beta1版本的 APIService，在metadata.name中定义该 API 的名字。命名约定为<version>.<group>，例如上面的v1alpha1.custom-metrics.metrics.k8s.io，表示注册custom-metrics.metrics.k8s.io组的v1alpha1版本。

各spec字段的含义如下：

创建与验证 APIService

将上面的 YAML 保存为文件后，使用kubectl create即可创建对应的 APIService：

kubectl create -f apiservice.yaml

创建完成后，可以用kubectl get查看我们创建的 APIService 的完整对象：

kubectl get apiservice v1alpha1.custom-metrics.metrics.k8s.io -o yaml

输出示例：

apiVersion: apiregistration.k8s.io/v1beta1 kind: APIService metadata: creationTimestamp: 2017-12-14T08:27:35Z name: v1alpha1.custom-metrics.metrics.k8s.io resourceVersion: "35194598" selfLink: /apis/apiregistration.k8s.io/v1beta1/apiservices/v1alpha1.custom-metrics.metrics.k8s.io uid: a31a3412-e0a8-11e7-9fa4-f4e9d49f8ed0 spec: caBundle: null group: custom-metrics.metrics.k8s.io groupPriorityMinimum: 1000 insecureSkipTLSVerify: true service: name: api namespace: custom-metrics version: v1alpha1 versionPriority: 5 status: conditions: - lastTransitionTime: 2017-12-14T08:27:38Z message: all checks passed reason: Passed status: "True" type: Available

注意status.conditions中的Available条件：status: "True"、reason: Passed、message: all checks passed表示该 APIService 已通过聚合层对后端 Service 的连通性与 TLS 校验，可以正常提供服务。若后端 Service 不可达、镜像拉取失败或证书校验失败，Available会变为False，此时应优先检查spec.service指向的 Service 是否存在、其selector是否命中后端 Pod。

查看集群支持的 APIService 与 API 版本

作为 Kubernetes 中的一种资源对象，APIService 可以直接用kubectl get apiservice查看。例如查看集群中所有的 APIService：

$ kubectl get apiservice NAME AGE v1. 2d v1.authentication.k8s.io 2d v1.authorization.k8s.io 2d v1.autoscaling 2d v1.batch 2d v1.monitoring.coreos.com 1d v1.networking.k8s.io 2d v1.rbac.authorization.k8s.io 2d v1.storage.k8s.io 2d v1alpha1.custom-metrics.metrics.k8s.io 2h v1beta1.apiextensions.k8s.io 2d v1beta1.apps 2d v1beta1.authentication.k8s.io 2d v1beta1.authorization.k8s.io 2d v1beta1.batch 2d v1beta1.certificates.k8s.io 2d v1beta1.extensions 2d v1beta1.policy 2d v1beta1.rbac.authorization.k8s.io 2d v1beta1.storage.k8s.io 2d v1beta2.apps 2d v2beta1.autoscaling 2d

从输出可以看到：v1.这类只有组名没有子组名的条目表示核心 API 组；v1alpha1.custom-metrics.metrics.k8s.io就是通过 APIService 注册进来的聚合 API——它的AGE为 2h，明显晚于其他内置 API，正是我们刚刚创建的那个对象。

另外，查看当前 Kubernetes 集群支持的所有 API 版本，还可以使用kubectl api-versions：

$ kubectl api-versions apiextensions.k8s.io/v1beta1 apiregistration.k8s.io/v1beta1 apps/v1beta1 apps/v1beta2 authentication.k8s.io/v1 authentication.k8s.io/v1beta1 authorization.k8s.io/v1 authorization.k8s.io/v1beta1 autoscaling/v1 autoscaling/v2beta1 batch/v1 batch/v1beta1 certificates.k8s.io/v1beta1 custom-metrics.metrics.k8s.io/v1alpha1 extensions/v1beta1 monitoring.coreos.com/v1 networking.k8s.io/v1 policy/v1beta1 rbac.authorization.k8s.io/v1 rbac.authorization.k8s.io/v1beta1 storage.k8s.io/v1 storage.k8s.io/v1beta1 v1

注意其中出现的custom-metrics.metrics.k8s.io/v1alpha1——它与kubectl get apiservice中新增的v1alpha1.custom-metrics.metrics.k8s.io一一对应，这正是 APIService 注册生效的直接证据：聚合 API 一旦注册成功，就会自动出现在kubectl api-versions的列表中，可供其他控制器与客户端发现和使用。

实战：用 APIService 注册自定义指标 API，驱动 HPA 扩缩容

APIService 最常见的落地场景之一，是注册自定义指标 API（custom.metrics.k8s.io）以驱动基于自定义指标的 HPA，例如根据 QPS、http_requests等业务指标自动扩缩容。本仓库 concepts/custom-metrics-hpa.md 记录了完整的部署思路，核心步骤包括：

1. 确认版本并配置 kube-apiserver 的聚合参数

Kubernetes 1.7+ 版本中，需要修改 kube-apiserver 的启动配置（本仓库对应的环境配置文件为 etc/kubernetes/apiserver，通过 systemd/kube-apiserver.service 中的$KUBE_API_ARGS传入），增加以下参数以启用 request header 认证（聚合层与 API server 之间传递用户身份信息的基础）：

--requestheader-client-ca-file=/etc/kubernetes/ssl/ca.pem \ --requestheader-allowed-names=aggregator \ --requestheader-extra-headers-prefix=X-Remote-Extra- \ --requestheader-group-headers=X-Remote-Group \ --requestheader-username-headers=X-Remote-User \ --proxy-client-cert-file=/etc/kubernetes/ssl/kubernetes.pem \ --proxy-client-key-file=/etc/kubernetes/ssl/kubernetes-key.pem

这些参数用于配置 aggregator 的 CA 证书与代理客户端证书，是 APIService 后端（如自定义指标 API server）能正确通过认证的必要条件。

2. 部署自定义指标 API server

本仓库的 manifests/HPA/custom-metrics.yaml 是完整的一体化清单，它按顺序包含：

• Namespace: custom-metrics与ServiceAccount: custom-metrics-apiserver；
• 两个 RBAC 绑定：custom-metrics:system:auth-delegator（ClusterRoleBinding，将认证委托给核心 API server）和custom-metrics-auth-reader（RoleBinding，读取kube-system中extension-apiserver-authentication-reader的认证配置）；
• Deployment: custom-metrics-apiserver，运行k8s-prometheus-adapter镜像（仓库示例中镜像地址为harbor-001.jimmysong.io/library/k8s-prometheus-adapter，实际部署时应替换为你自己的镜像仓库地址），并通过--prometheus-url=http://sample-metrics-prom.default.svc:9090指向 Prometheus；
• Service: api（namespace 为custom-metrics，端口 443），即 APIService 的spec.service所指的后端；
• APIService 资源：即上文反复出现的v1alpha1.custom-metrics.metrics.k8s.io注册清单；
• 两个授权 HPA 控制器访问自定义指标 API 的 RBAC 对象（custom-metrics-server-resourcesClusterRole 及其绑定）。

部署完成后，自定义 API 即可通过浏览器访问http://<api-server-address>:8080/apis/custom-metrics.metrics.k8s.io/v1alpha1，也可以使用kubectl get --raw直接查询：

$ kubectl get --raw=apis/custom-metrics.metrics.k8s.io/v1alpha1 {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom-metrics.metrics.k8s.io/v1alpha1","resources":[{"name":"jobs.batch/http_requests","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"namespaces/http_requests","singularName":"","namespaced":false,"kind":"MetricValueList","verbs":["get"]},...]}

返回的APIResourceList中列出了 Prometheus 暴露的各类指标资源（如pods/http_requests、services/up、namespaces/scrape_duration_seconds等），这些就是 HPA 可以直接引用的指标名。

3. 编写基于自定义指标的 HPA

manifests/HPA/hpa.yaml 给出了引用http_requests指标的 HPA 示例：

kind: HorizontalPodAutoscaler apiVersion: autoscaling/v2beta1 metadata: name: sample-metrics-app-hpa spec: scaleTargetRef: kind: Deployment name: sample-metrics-app minReplicas: 2 maxReplicas: 10 metrics: - type: Object object: target: kind: Service name: sample-metrics-app metricName: http_requests targetValue: 100

spec.metrics中通过type: Object引用名为sample-metrics-app的 Service，并以http_requests为指标名、targetValue: 100为目标值。HPA 控制器会通过kube-controller-manager的--horizontal-pod-autoscaler-use-rest-clients=true参数走 REST 客户端，向 APIService 注册的custom-metrics.metrics.k8s.io/v1alpha1查询指标数据，从而将"Prometheus 采集的业务指标 → 聚合 API → APIService → HPA"整条链路打通。

小结

APIService是 Kubernetes API 聚合机制的"注册入口"：通过metadata.name声明GroupVersion，通过spec.service声明后端服务，通过groupPriorityMinimum与versionPriority控制 API 的发现与访问优先级，并通过status.conditions反馈注册后的可用状态。它让第三方 API server 可以无缝接入集群，被kubectl、RBAC 和 HPA 等组件统一管理——这正是 Kubernetes 从巨石 API server 走向可插拔扩展生态的关键一环。

• 教程
• 云原生
• 容器编排