## 一、两条路：CRD 还是聚合 APIServer

![ext-1-decision.png](https://developer.qcloudimg.com/http-save/yehe-11479707/24d80cdbffdcc4824f8363740ff4da0f.png)

*图 1：四个问题，决定你走哪条路。*

| | CRD | 聚合 API Server |
| --- | --- | --- |
| 本质 | 往 apiserver 里注册一个新的 REST 资源 | 在 apiserver 前面挂一个你自己实现的 apiserver |
| 存储 | 复用 etcd，apiserver 帮你存 | 你自己实现（可以是任何后端） |
| watch / resourceVersion | 免费获得 | 你要自己实现 |
| 自定义 verb | 不支持 | 支持 |
| protobuf / 流式 | 不支持 | 支持 |
| 可用性风险 | 低（不引入新进程） | 高（apiserver 要转发给它） |
| 典型使用者 | Operator、绝大多数扩展 | metrics-server、自定义指标、多集群 API |

**90% 的场景应该用 CRD。** 聚合层不是"更高级的 CRD"，而是一个完全不同量级的工程：你要自己实现一个 apiserver。

## 二、CRD 的能力边界

`apiextensions.k8s.io/v1` 之后，CRD 有这些硬约束：

- **必须有 structural schema**（1.16 起）。非结构化字段会被静默剪枝，除非显式标 `x-kubernetes-preserve-unknown-fields: true`；
- **只有 `status` 和 `scale` 两个子资源**，没有 `logs`、`exec` 这种；
- **verb 是固定的七个**：get / list / watch / create / update / patch / delete / deletecollection，不能加自定义动作；
- **没有 protobuf**，大对象高频读写会比内置类型慢；
- **默认值、校验、转换都靠 schema 或 webhook**，没有 Go 代码可以写业务逻辑。

所以判断标准很朴素：**能用声明式 schema 表达的，用 CRD；需要自定义行为或协议能力的，才上聚合层。**

一个常见的误判是"我要给资源加一个 `restart` 动作"——这属于自定义 verb，CRD 做不到，要么用 `spec` 里的字段 + 控制器实现（推荐），要么上聚合层。

## 三、CRD 的版本与转换

![ext-2-crd.png](https://developer.qcloudimg.com/http-save/yehe-11479707/47d33c99af0aa4c7919e6bbe4921939b.png)

*图 2：多个版本，只能有一个 storage；转换要么结构等价，要么交给 webhook。*

```yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
spec:
  group: example.com
  names: {kind: Widget, plural: widgets}
  scope: Namespaced
  versions:
  - name: v1
    served: true
    storage: true          # 只有一个
    schema: {openAPIV3Schema: {...}}
  - name: v1beta1
    served: true
    storage: false
  conversion:
    strategy: Webhook      # None（默认）或 Webhook
    webhook:
      conversionReviewVersions: ["v1"]
      clientConfig:
        service: {namespace: system, name: widget-webhook, path: /convert}
```

三个设计要点：

- **`strategy: None` 时，所有版本必须结构等价**，只是 `apiVersion` 不同。所以"先发 v1beta1、后加字段"这种演进，必须切到 webhook；
- **转换 webhook 在读写路径上同步调用**，它挂了，这个 CRD 的读写就一起挂——和准入 webhook 是同一类可用性风险；
- **`storage: true` 只能有一个**。切换存储版本后，老对象仍然以旧版本存在 etcd 里，读的时候实时转换；想把它们真正重写，需要跑 `kube-storage-version-migrator` 这类工具。

> 这一点和第五篇讲的内置类型形成对照：内置类型有内部版本做枢纽，CRD 没有，转换只能两两直连。

## 四、聚合层：把一段 URL 代理给你自己的 apiserver

![ext-3-aggregation.png](https://developer.qcloudimg.com/http-save/yehe-11479707/d59b53ddbfaa25bb383b27cece6a8dd9.png)

*图 3：APIService 注册路由，kube-aggregator 负责转发，身份用 RequestHeader 透传。*

```yaml
apiVersion: apiregistration.k8s.io/v1
kind: APIService
metadata: {name: v1beta1.metrics.k8s.io}
spec:
  group: metrics.k8s.io
  version: v1beta1
  groupPriorityMinimum: 100
  versionPriority: 100
  service: {namespace: kube-system, name: metrics-server, port: 443}
  caBundle: <base64>
```

`kube-aggregator` 会把 `/apis/metrics.k8s.io/v1beta1/*` 代理到你的服务，并且**把认证后的用户身份透传过去**——这就是第二篇里 `RequestHeader` 认证存在的原因。

**为什么身份透传这么重要？**
因为后端 apiserver 也要做鉴权。如果只透传一个 service account，那所有请求在扩展 apiserver 里都是同一个身份，细粒度权限就没了。

## 五、什么时候必须上聚合层

只有四种情况值得：

1. **需要自定义 verb**：比如 `exec`、`logs` 这类动作；
2. **需要 protobuf 或流式**：高频大对象、长连接；
3. **需要自己的存储后端**：数据不在 etcd，或者根本不在 Kubernetes 里；
4. **复用已有的 API 实现**：比如 metrics-server、custom-metrics-apiserver。

其余情况，CRD + 控制器都能覆盖——包括"看起来需要自定义动作"的场景，通常用 `spec` 字段表达意图、控制器执行，反而更符合声明式模型。

## 六、工程化：别手写

- **kubebuilder / operator-sdk**：生成 CRD 的类型、DeepCopy、informer、controller 骨架；
- **controller-runtime**：提供 informer、workqueue、client，省掉大量样板；
- **code-generator**：生成 clientset、listers、informers。

手写的成本不在第一版，而在**加字段、加版本、改转换**的时候——这些恰恰是代码生成最擅长的。

## 七、版本时间线

| 时间 | 版本 | 变化 |
| --- | --- | --- |
| 2016 | 1.2 | Third Party Resource |
| 2017 | 1.7 | CRD 取代 TPR |
| 2018 | 1.8 | CRD 增加 `status` / `scale` 子资源 |
| 2018 | 1.13 | CRD 转换 webhook alpha |
| 2019 | 1.16 | `apiextensions.k8s.io/v1` GA，structural schema 强制 |
| 2020 | 1.18 | `apiregistration.k8s.io/v1` 稳定（聚合层） |
| 2024 | 1.32 | MutatingAdmissionPolicy alpha（策略层的扩展点） |

## 八、排障清单

| 现象 | 先查什么 |
| --- | --- |
| `no matches for kind` | CRD 没装，或该版本 `served: false` |
| 写入成功但字段不见了 | structural schema 剪枝；加 `x-kubernetes-preserve-unknown-fields` |
| `conversion webhook failed` | 转换服务不可达、`caBundle` 过期、`conversionReviewVersions` 不匹配 |
| 切了 storage 版本后读变慢 | 存量对象仍是旧编码，读时实时转换；跑迁移工具 |
| 聚合 API 502 | `APIService` 的 service / port 配错，或后端没起 |
| 聚合 API 401 | 身份透传的 `RequestHeader` 认证没配好 |
| kubectl 看不到新资源 | 检查 `discovery` 缓存，或 CRD 的 `categories` |

## 九、设计追问

**1. 为什么 CRD 不做自定义 verb？**
因为自定义 verb 会打破 API 的声明式模型。`exec` 这种"动作"在 Kubernetes 里是用子资源 + 升级连接表达的，属于协议层能力，不是 schema 能描述的。

**2. 为什么聚合层要单独存在，而不是把 CRD 做得更强？**
因为 CRD 的强项是"复用 apiserver 的全部语义"，聚合层的强项是"完全自定义"。两者是互补，不是替代。把 CRD 做到能自定义存储，就等于在 apiserver 里再实现一个 apiserver。

**3. 为什么转换 webhook 和准入 webhook 一样危险？**
因为它们都在同步路径上。准入在写之前，转换在读写两侧；任何一个不可用，对应的资源就不可用。

**4. 为什么大多数 Operator 不需要聚合层？**
因为 Operator 的核心是"调谐"——观察状态、对比期望、执行动作。这些都能用 CRD + 控制器表达，不需要新的协议能力。

---

**一句话收尾**：CRD 拿走 90% 的扩展场景，聚合层留给那 10% 真正需要自定义协议的。选型的本质不是"哪个更强"，而是"你愿不愿意为那 10% 的能力，承担一个 apiserver 的运维成本"。

---

## 参考资料

1. Kubernetes 文档：[Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)、[Extending the Kubernetes API with the aggregation layer](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)
2. Kubernetes 源码（v1.34.0）：`staging/src/k8s.io/apiextensions-apiserver/`、`staging/src/k8s.io/kube-aggregator/`
3. Kubernetes 文档：[Custom Resource Definitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)

> 本文为原创内容，基于 Kubernetes v1.34.0 源码整理；版本号以对应 release note 为准。

90% 的场景应该用 CRD。 聚合层不是"更高级的 CRD"，而是一个完全不同量级的工程：你要自己实现一个 apiserver。

kubernetes 进阶知识-API 扩展：CRD 与聚合层之间的一条线

Kubernetes 的 API 不是封闭的。你可以在不改核心代码的前提下，让 apiserver 认识一种全新的资源。
但"扩展"有两条路，能力、代价、适用场景完全不同。选错的成本，往往在半年后才显现：要么被 CRD 的表达能力卡死，要么为了一个字段维护一个 apiserver。源码引用基于 v1.34.0。

运维开发工程师

运维

CRD与聚合APIServer选型指南：CRD覆盖90%扩展场景，适合声明式schema表达的Operator开发；聚合层仅用于自定义verb、protobuf流式、独立存储等特殊需求。CRD有schema剪枝、固定verb等硬约束，版本转换需webhook。聚合层将URL代理至自建apiserver并透传身份，可用性风险更高。多数场景推荐CRD+控制器实现。

代码解释

Kubernetes

路由

让每一个 Agent，都跑在云上

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

CRD与聚合APIServer选型指南：CRD覆盖90%扩展场景，适合声明式schema表达的Operator开发；聚合层仅用于自定义verb、protobuf流式、独立存储等特殊需求。CRD有schema剪枝、固定verb等硬约束，版本转换需webhook。聚合层将URL代理至自建apiserver并透传身份，可用性...

kubernetes 进阶知识-API 扩展：CRD 与聚合层之间的一条线-腾讯云开发者社区-腾讯云

kubernetes 进阶知识-API 扩展：CRD 与聚合层之间的一条线

kubernetes 进阶知识-API 扩展：CRD 与聚合层之间的一条线

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐