CRD 定义文件结构深度解析

自定义资源定义（CRD）是 Kubernetes 扩展机制的核心，它通过声明式 YAML 文件告诉 API Server 一种新的资源类型及其验证规则。理解 CRD YAML 的每一层结构，是编写可靠 Operator 的基础。本章将逐层拆解 CRD 定义文件的 apiVersion、kind、metadata、spec 四大核心字段，并深入 OpenAPI v3 Schema 验证规则。

CRD YAML 顶层结构概览

一个标准的 CRD 定义文件遵循 Kubernetes 资源模型，其顶层字段构成如下：

apiVersion 与 kind：资源身份声明

apiVersion 决定了 CRD 资源本身的 API 组和版本。当前稳定版必须使用：

apiVersion: apiextensions.k8s.io/v1

kind 固定为 CustomResourceDefinition，这是 Kubernetes 内置的资源类型，用于注册新的自定义资源。

metadata.name：DNS 子域名规范

metadata.name 是 CRD 的唯一标识符，必须遵循 DNS 子域名规范（RFC 1123）。命名规则为：

• 格式： <plural>.<group>
• 示例： 如果定义 group: example.com，names.plural: myresources，则 name 必须为 myresources.example.com
• 长度限制： 最多 253 个字符
• 字符集： 仅允许小写字母、数字、连字符（-）和点（.）

metadata:
  name: myresources.example.com

spec 字段详解：CRD 的核心定义

spec 是 CRD 定义中最复杂的部分，它决定了自定义资源的行为和结构。下表列出了 spec 中的关键字段：

names 对象：资源命名体系

names 字段定义了自定义资源在集群中的各种名称形式：

versions 数组：多版本管理

每个版本包含三个关键属性：

• name： 版本名称，如 v1、v1beta1
• served： 布尔值，表示该版本是否可通过 API 提供服务
• storage： 布尔值，表示该版本是否用于持久化存储（每个 CRD 只能有一个 storage: true 的版本）
• schema： OpenAPI v3 Schema 定义，描述资源字段结构

OpenAPI v3 Schema 验证规则

OpenAPI v3 Schema 是 CRD 定义中最关键的部分，它决定了自定义资源实例的字段结构、类型和验证规则。Schema 定义在 spec.versions[*].schema.openAPIV3Schema 下。

核心验证关键字

完整 CRD 示例

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myresources.stable.example.com
spec:
  group: stable.example.com
  names:
    plural: myresources
    singular: myresource
    shortNames:
    - mr
    kind: MyResource
    listKind: MyResourceList
  scope: Namespaced
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              replicas:
                type: integer
                minimum: 1
                maximum: 100
              image:
                type: string
                pattern: '^[a-z0-9]+/[a-z0-9]+:[a-z0-9]+$'
              enabled:
                type: boolean
              tags:
                type: array
                items:
                  type: string
                  maxLength: 20
            required:
            - replicas
            - image
          status:
            type: object
            properties:
              availableReplicas:
                type: integer
              conditions:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    status:
                      type: string
                      enum:
                      - "True"
                      - "False"
                      - "Unknown"
                    lastTransitionTime:
                      type: string
                  required:
                  - type
                  - status

高级 Schema 技巧与避坑

x-kubernetes-* 扩展字段

Kubernetes 在 OpenAPI v3 基础上扩展了若干 x-kubernetes-* 前缀字段，用于实现更精细的控制：

# 使用 x-kubernetes-int-or-string 示例
properties:
  port:
    x-kubernetes-int-or-string: true
    # 允许 port: 8080 或 port: "8080"

Schema 定义最佳实践清单

1. 始终定义 required 字段： 避免 Operator 处理空值导致的 panic
2. 使用 enum 约束状态值： 如 status.phase 限定为 Pending、Running、Failed
3. 为数值字段设置 minimum/maximum： 防止资源滥用
4. 利用 pattern 验证字符串格式： 如镜像名称、DNS 标签
5. 谨慎使用 x-kubernetes-preserve-unknown-fields： 它会绕过 Schema 验证，降低安全性
6. 为 status 子资源单独定义 Schema： 确保 status 字段结构清晰