CRD 基础：概念、与原生资源的关系、YAML 结构定义

Custom Resource Definition（CRD）是 Kubernetes 扩展机制的核心，它允许你在集群中定义全新的资源类型，而无需修改任何 Kubernetes 源码。CRD 的本质是一个 API 资源描述文件，它告诉 API Server：“我要新增一种资源，它的名字、结构、作用域是什么”。一旦 CRD 被创建，Kubernetes 就会自动生成对应的 RESTful API 端点，你可以像操作 Pod、Service 一样，通过 kubectl 或 API 调用来管理这种自定义资源。

CRD 与原生资源的关系

Kubernetes 原生资源（如 Pod、Deployment、Service）与 CRD 定义的自定义资源在 API 层面遵循完全相同的生命周期和操作模式。下表从多个维度对比两者的异同：

CRD 的 YAML 结构定义

一个标准的 CRD 定义包含三个核心部分：元数据、Spec 结构、版本与作用域。下面是一个完整的 CRD 示例，定义了一种名为 AppDeployment 的自定义资源：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: appdeployments.apps.example.com   # 必须为 {复数名}.{组名}
spec:
  group: apps.example.com                  # API 组
  names:
    plural: appdeployments                 # 复数名，用于 kubectl
    singular: appdeployment                # 单数名
    shortNames:                            # 短名称
      - appdep
    kind: AppDeployment                    # 资源类型名
    listKind: AppDeploymentList            # 列表类型名
  scope: Namespaced                        # 作用域：Namespaced 或 Cluster
  versions:
    - name: v1
      served: true                         # 是否在 API 中提供
      storage: true                        # 是否作为 etcd 存储版本
      schema:
        openAPIV3Schema:
          type: object
          required:
            - spec
          properties:
            spec:
              type: object
              required:
                - replicas
                - image
              properties:
                replicas:
                  type: integer
                  minimum: 1
                  maximum: 100
                image:
                  type: string
                env:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
            status:
              type: object
              properties:
                availableReplicas:
                  type: integer
                conditions:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                      status:
                        type: string
                      lastTransitionTime:
                        type: string
                        format: date-time

CRD 的核心字段速查表

CRD 在 Kubernetes 控制面中的位置

下图展示了 CRD 如何融入 Kubernetes 控制面的核心组件，以及自定义资源的数据流路径：

创建 CRD 后的效果

当 CRD 被成功创建后，你可以立即使用 kubectl 操作自定义资源：

# 查看 CRD 是否注册成功
kubectl get crd

# 创建自定义资源实例
kubectl apply -f appdeployment-instance.yaml

# 查看实例
kubectl get appdeployment
kubectl get appdep  # 使用短名称

# 查看实例详情（包含 status 字段）
kubectl describe appdeployment my-app

# 删除实例
kubectl delete appdeployment my-app

自定义资源实例的 YAML 文件示例如下：

apiVersion: apps.example.com/v1
kind: AppDeployment
metadata:
  name: my-app
  namespace: default
spec:
  replicas: 3
  image: nginx:1.25
  env:
    - name: ENV
      value: production