4、CRD 设计规范：自定义资源定义的结构、版本与校验
在 Operator 开发中，自定义资源定义（CRD）是声明式 API 的核心载体。CRD 的 YAML 结构、版本管理策略以及校验规则直接决定了 Operator 的扩展性、兼容性与生产就绪度。本章从这三个维度展开，帮助你在流水线集成中建立自动化的 CRD 合规验证能力。
4.1 CRD YAML 结构规范
一个标准的 CRD 由顶层元数据、Spec 与状态子结构组成。以下是一个典型的 CRD YAML 骨架：
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: myresources.example.io
spec:
group: example.io
names:
kind: MyResource
plural: myresources
singular: myresource
shortNames:
- mr
scope: Namespaced
versions:
- name: v1alpha1
served: true
storage: false
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
properties:
replicas:
type: integer
minimum: 1
maximum: 100
image:
type: string
status:
type: object
properties:
availableReplicas:
type: integer
conversion:
strategy: Webhook
webhook:
conversionReviewVersions: ["v1", "v1beta1"]
结构要点：
- group/names：定义 API 组与资源名称，必须符合 DNS 子域名规范。
- scope：选择 Namespaced 或 Cluster，影响资源隔离范围。
- versions：核心数组，每个版本独立定义 schema、服务状态与存储标志。
- conversion：多版本共存时，必须配置转换策略（None 或 Webhook）。
4.2 版本管理策略：从 v1alpha1 到 v1
Kubernetes 社区推荐的版本演进路径分为三个阶段，每个阶段对应不同的稳定性承诺与变更自由度：
| 版本 | 稳定性 | 变更自由度 | 生产推荐 | 存储标志 |
|---|---|---|---|---|
| v1alpha1 | 实验性 | 可任意变更，不保证向后兼容 | 仅开发/测试环境 | 通常不设为 storage |
| v1beta1 | Beta 级 | 可少量非破坏性变更，需保留字段兼容 | 预生产/小规模生产 | 可选 storage |
| v1 | 稳定 GA | 仅允许新增可选字段，禁止删除或重命名 | 生产环境 | 必须设为 storage |
版本共存原则： 在同一个 CRD 中，可以同时声明多个 served: true 的版本。但 storage: true 只能有一个版本，用于持久化存储。其他版本通过转换 Webhook 实现读写兼容。
以下 SVG 展示了 CRD 版本从开发到生产的标准演进路径：
4.3 校验规则：OpenAPI v3 Schema
CRD 的校验规则通过 openAPIV3Schema 字段定义，支持类型约束、值范围、枚举、必填字段、嵌套对象校验等。以下是最常用的校验模式：
| 校验类型 | 关键字 | 示例 | 说明 |
|---|---|---|---|
| 类型约束 | type | type: integer |
支持 string / integer / number / boolean / array / object |
| 数值范围 | minimum / maximum | minimum: 1, maximum: 100 |
仅对 integer / number 生效 |
| 字符串模式 | pattern | pattern: '^[a-z0-9-]+$' |
正则表达式校验 |
| 枚举值 | enum | enum: [dev, staging, prod] |
限定可选值列表 |
| 必填字段 | required | required: [name, image] |
在对象级别声明必填属性 |
| 数组长度 | minItems / maxItems | minItems: 1, maxItems: 10 |
限制数组元素个数 |
| 嵌套对象 | properties | properties: { spec: { type: object, ... } } |
支持多层嵌套与递归校验 |
常见陷阱：
- additionalProperties：默认允许未知字段，建议显式设置为 false 以严格校验。
- nullable：对于可选字段，明确设置 nullable: true 避免空值报错。
- default：CRD 不支持 default 关键字，默认值需在 Operator 控制器中处理。
以下 SVG 展示了 OpenAPI v3 Schema 在 CRD 中的校验层级结构：
4.4 流水线中的 CRD 合规验证
在 CI/CD 流水线中，自动化验证 CRD 合规性通常包含以下步骤：
- YAML 语法检查：使用
kubectl apply --dry-run=server --validate=true或kubeconform工具。 - Schema 结构校验：对比 CRD YAML 与 OpenAPI v3 Schema 模板，确保字段类型、范围、枚举值一致。
- 版本兼容性检查：验证新版本是否包含所有旧版本字段（仅允许新增可选字段）。
- 存储版本唯一性：确保只有一个版本设置
storage: true。 - 转换 Webhook 配置：如果存在多个 served 版本，检查 conversion 策略是否配置正确。
自动化工具推荐：
- kubeconform：离线 CRD 校验，支持自定义 Schema 目录。
- datree：策略引擎，可编写 CRD 合规规则。
- kubectl-neat：清理 CRD 输出，便于对比版本差异。
- openapi-diff：对比两个 OpenAPI Schema 的破坏性变更。
通过以上规范与工具的结合，你可以在流水线中自动拦截不合规的 CRD 变更，确保 Operator 发布始终符合 Kubernetes 生态的最佳实践。