CRD Operator控制器开发与状态调试 - 第2节

2.1 自定义资源定义（CRD）详解

自定义资源定义（Custom Resource Definition，CRD）是 Kubernetes 扩展机制的核心，它允许你在集群中定义全新的资源类型，就像内置的 Pod、Service 一样。CRD 本身是一个 API 资源，通过声明式配置告诉 Kubernetes API Server 新的资源结构。

2.1.1 CRD 的核心结构

一个标准的 CRD 定义包含以下关键字段：

2.1.2 CRD 版本管理机制

Kubernetes 1.16+ 支持 CRD 的多版本管理，允许同时维护多个 API 版本，并通过转换机制实现数据兼容。版本管理涉及三个核心概念：

• 存储版本（storage version）：集群中实际持久化存储的版本，每个 CRD 只能指定一个存储版本。
• 服务版本（served version）：API Server 对外提供访问的版本，可以同时启用多个。
• 版本转换（conversion）：不同版本之间的数据转换策略，支持 Webhook 转换或 None（字段名完全一致）。

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.example.com
spec:
  group: example.com
  names:
    kind: Database
    plural: databases
    singular: database
    shortNames:
    - db
  scope: Namespaced
  versions:
  - name: v1alpha1
    served: true
    storage: false
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              engine:
                type: string
              version:
                type: string
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              engine:
                type: string
              version:
                type: string
              replicas:
                type: integer
    subresources:
      status: {}

2.2 自定义资源（CR）实例

自定义资源（Custom Resource，CR）是 CRD 的具体实例化对象，类似于 Pod 是 PodTemplate 的实例。CR 遵循标准的 Kubernetes 资源格式，包含 apiVersion、kind、metadata 和 spec 等核心字段。

2.2.1 CR 实例的结构与创建

以下是一个基于上述 CRD 的 CR 实例：

apiVersion: example.com/v1
kind: Database
metadata:
  name: my-production-db
  namespace: default
spec:
  engine: postgresql
  version: "14.5"
  replicas: 3

创建 CR 实例后，Kubernetes API Server 会执行以下流程：

1. 验证 CR 的 apiVersion 和 kind 是否匹配已注册的 CRD。
2. 根据 CRD 中定义的 OpenAPI Schema 校验 CR 的字段结构。
3. 将 CR 对象持久化到 etcd 中。
4. 触发对应的 Watch 事件，通知正在监听的 Controller。

2.2.2 CR 与内置资源的差异

2.3 CRD 版本管理实战

2.3.1 版本转换策略

当 CRD 存在多个服务版本时，API Server 需要在不同版本之间转换数据。Kubernetes 提供两种转换策略：

• None 转换：要求所有版本的字段结构完全一致，API Server 直接复制数据，无需额外转换逻辑。
• Webhook 转换：通过自定义转换 Webhook 实现复杂的字段映射和逻辑转换，适用于版本间数据结构差异较大的场景。

2.3.2 版本迁移与数据一致性

版本迁移是 CRD 版本管理中最容易出问题的环节。以下是一个典型的版本迁移流程：

1. 在 CRD 中添加新版本，设置 storage: false，保留旧版本为存储版本。
2. 逐步更新所有 CR 实例的 apiVersion 字段，使其指向新版本。
3. 验证所有 CR 实例在新版本下读写正常。
4. 修改 CRD，将新版本设为 storage: true，旧版本设为 storage: false。
5. 触发存储版本迁移（通过更新 CR 实例或使用存储版本迁移工具）。
6. 确认 etcd 中所有数据已迁移到新版本后，移除旧版本。

2.4 CRD 调试常用命令

在 Operator 开发过程中，掌握以下调试命令可以快速定位 CRD 相关问题：