3. 创建第一个CRD：使用kubectl apply创建自定义资源定义，验证CRD注册成功

在理解了CRD的结构与核心字段之后，我们进入实战环节：通过 kubectl apply 将一个自定义资源定义提交到Kubernetes API Server，完成CRD的注册。这是扩展Kubernetes API的第一步，也是后续编写控制器的基石。

3.1 编写第一个CRD YAML清单

我们以一个管理“数据库实例”的场景为例，定义一个名为 Database 的自定义资源。该CRD属于 example.com API组，版本为 v1，作用域为集群级别（Cluster-scoped），包含两个核心字段：engine（数据库引擎类型）和 version（版本号）。

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.example.com
spec:
  group: example.com
  names:
    kind: Database
    listKind: DatabaseList
    plural: databases
    singular: database
    shortNames:
      - db
  scope: Cluster
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                engine:
                  type: string
                  enum:
                    - mysql
                    - postgres
                    - mongodb
                version:
                  type: string
                  pattern: '^\d+\.\d+\.\d+$'
              required:
                - engine
                - version

3.2 提交CRD到集群

使用 kubectl apply 将YAML提交到Kubernetes集群。该命令会向API Server发送POST请求，触发CRD的注册流程。

# 提交CRD
kubectl apply -f database-crd.yaml

# 预期输出
customresourcedefinition.apiextensions.k8s.io/databases.example.com created

提交后，API Server会执行以下步骤：

1. 验证CRD元数据：检查 metadata.name 格式、group 与 names 字段的合法性。
2. 编译OpenAPI Schema：将 openAPIV3Schema 注册到集群的OpenAPI规范中，用于后续的字段校验。
3. 创建REST端点：在API Server内部动态生成 /apis/example.com/v1/databases 路由。
4. 启动CRD控制器：Kube-Controller-Manager中的CRD控制器开始监听该CRD，并为其创建对应的CRD资源实例的存储结构。

3.3 验证CRD注册成功

CRD提交后，可以通过以下三种方式验证注册状态：

方式一：查询CRD列表

kubectl get crd

# 输出示例
NAME                     CREATED AT
databases.example.com    2025-01-15T10:30:00Z

方式二：查看CRD详细信息

kubectl describe crd databases.example.com

# 关键输出片段
Name:         databases.example.com
Group:        example.com
Names:
  Kind:       Database
  List Kind:  DatabaseList
  Plural:     databases
  Singular:   database
  Short Names:
    db
Scope:        Cluster
Version Names:
  v1          SERVED, STORAGE

方式三：直接访问API端点

# 通过kubectl代理访问
kubectl proxy --port=8080 &
curl http://localhost:8080/apis/example.com/v1/databases

# 预期返回（空列表）
{
  "apiVersion": "example.com/v1",
  "kind": "DatabaseList",
  "items": []
}

3.4 CRD注册流程架构图

下图展示了从YAML提交到CRD注册完成的完整流程，以及各组件之间的交互关系：

3.5 创建第一个自定义资源实例

CRD注册成功后，即可创建该类型的自定义资源实例。以下示例创建一个名为 my-production-db 的Database资源：

# database-instance.yaml
apiVersion: example.com/v1
kind: Database
metadata:
  name: my-production-db
spec:
  engine: postgres
  version: "14.5.0"

# 提交资源实例
kubectl apply -f database-instance.yaml

# 预期输出
database.example.com/my-production-db created

# 查询资源实例
kubectl get databases

# 输出示例
NAME                ENGINE    VERSION   AGE
my-production-db    postgres  14.5.0    10s

# 使用短名称查询
kubectl get db

# 输出示例
NAME                ENGINE    VERSION   AGE
my-production-db    postgres  14.5.0    10s

3.6 注册状态检查清单