Kubernetes CRD 101：从概念到实践的完整指南

在Kubernetes生态中，CRD（Custom Resource Definition，自定义资源定义）和CR（Custom Resource，自定义资源）是开发者扩展集群能力的核心工具。它们允许用户定义新的资源类型（如MyResource），并通过Kubernetes API进行管理，就像原生资源（如Pod、Deployment）一样。本文将通过概念解析、应用场景、代码示例和最佳实践，帮助开发者彻底掌握CRD与CR的核心机制。

一、为什么需要CRD与CR？

Kubernetes原生资源（如Pod、Service、Deployment）覆盖了容器编排的基础需求，但在复杂业务场景中，用户往往需要管理领域特定资源。例如：

• 云原生数据库需要定义DatabaseCluster资源，包含分片配置、备份策略等；
• 机器学习平台需要定义TrainingJob资源，包含模型参数、数据集路径等；
• 网络功能需要定义NetworkPolicyExtension资源，扩展原生网络规则。

若没有CRD，开发者需通过以下方式实现类似功能：

1. 独立服务：部署单独的API服务管理资源，但无法利用Kubernetes的声明式API、RBAC、监控等生态能力；
2. ConfigMap/Secret：将配置存储为键值对，但缺乏结构化验证和生命周期管理；
3. Operator模式：虽然Operator依赖CRD，但直接理解CRD是掌握Operator的前提。

CRD的出现，使得用户能以Kubernetes原生方式定义和管理自定义资源，同时复用控制器（Controller）机制实现资源状态与期望状态的同步。

二、CRD与CR的核心概念

1. CRD：资源的“元数据定义”

CRD是Kubernetes API的扩展点，用于声明自定义资源的结构、验证规则和作用范围。其核心功能包括：

• Schema定义：通过OpenAPI v3校验资源字段的合法性（如字符串长度、枚举值）；
• 多版本支持：允许资源同时存在v1alpha1、v1beta1等版本，逐步迭代API；
• 作用域控制：定义资源是集群级（Namespaced: false）还是命名空间级（Namespaced: true）；
• 子资源支持：为资源添加/status或/scale子端点，简化状态管理。

示例：定义一个简单的CronTab CRD

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com
spec:
  group: stable.example.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                cronSpec:
                  type: string
                image:
                  type: string
                replicas:
                  type: integer
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab
    shortNames:
      - ct

此CRD定义了一个名为CronTab的资源，属于stable.example.com组，包含cronSpec、image和replicas字段，且为命名空间级资源。

2. CR：资源的“具体实例”

CR是CRD定义的资源类型的具体实例，用户通过创建CR来声明期望状态。例如，基于上述CRD，可创建一个CronTab实例：

apiVersion: stable.example.com/v1
kind: CronTab
metadata:
  name: my-new-cron-object
spec:
  cronSpec: "* * * * */5"
  image: my-awesome-cron-image
  replicas: 3

此CR指定了一个每5分钟运行的定时任务，使用指定镜像并启动3个副本。

三、CRD与CR的深度解析

1. CRD的版本管理

Kubernetes推荐通过版本迭代逐步完善API。例如：

• v1alpha1：实验性版本，可能包含破坏性变更；
• v1beta1：功能稳定，但可能调整字段命名；
• v1：正式版本，承诺向后兼容。

在CRD中，可通过versions字段定义多个版本，并通过storage: true标记存储版本。控制器需处理版本转换逻辑。

2. CR的验证与默认值

CRD可通过OpenAPI v3 Schema实现字段验证：

schema:
  openAPIV3Schema:
    type: object
    properties:
      spec:
        type: object
        properties:
          replicas:
            type: integer
            minimum: 1
            maximum: 10
          image:
            type: string
            pattern: '^[^/]+/[^/]+:[^@]+$'

同时，可通过x-kubernetes-validations规则实现跨字段验证（Kubernetes 1.25+）：

x-kubernetes-validations:
  - rule: "self.spec.replicas <= self.status.availableReplicas"
    message: "Replicas cannot exceed available replicas"

3. 结构化日志与事件

控制器处理CR时，需通过结构化日志和事件记录操作状态。例如：

import (
  "k8s.io/apimachinery/pkg/runtime"
  "k8s.io/client-go/tools/record"
  ctrl "sigs.k8s.io/controller-runtime"
)
type MyReconciler struct {
  client  client.Client
  scheme  *runtime.Scheme
  recorder record.EventRecorder
}
func (r *MyReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
  // 记录事件
  r.recorder.Eventf(&myCrontab, "Normal", "Synced", "Successfully synced")
  // 结构化日志
  ctrl.LoggerFrom(ctx).Info("Processing CronTab", "name", req.Name)
  // ...
}

四、从CRD到Operator：完整工作流

1. 定义CRD：通过YAML或Go代码（使用controller-gen工具）生成CRD清单；
2. 注册CRD：将CRD应用到集群（kubectl apply -f crd.yaml）；
3. 创建CR：声明资源实例（kubectl apply -f cr.yaml）；
4. 编写控制器：监听CR事件，调用外部API或管理原生资源；
5. 部署控制器：使用Deployment或Job运行控制器。

示例控制器逻辑：

func (r *CronTabReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
  cr := &cronv1.CronTab{}
  if err := r.Get(ctx, req.NamespacedName, cr); err != nil {
    return ctrl.Result{}, client.IgnoreNotFound(err)
  }
  // 根据cr.Spec.cronSpec创建定时任务
  if cr.Spec.CronSpec != "" {
    if err := r.createJob(ctx, cr); err != nil {
      return ctrl.Result{}, err
    }
  }
  return ctrl.Result{}, nil
}

五、最佳实践与常见问题

1. 命名规范

• 组名：使用DNS子域名（如stable.example.com），避免与原生组冲突；
• 资源名：采用大驼峰式（如CronTab），复数形式用于API端点（如crontabs）；
• 版本前缀：开发阶段使用v1alpha，稳定后升级到v1。

2. 性能优化

• Watch优化：控制器应精确监听所需资源，避免全量扫描；
• 缓存使用：通过client-go的Informer缓存减少API调用；
• 并发控制：使用workqueue限制并发Reconcile数量。

3. 调试技巧

• 查看CRD状态：kubectl get crd <name> -o yaml；
• 描述CR事件：kubectl describe crontab <name>；
• 控制器日志：kubectl logs -f <controller-pod>。

六、总结与行动建议

CRD与CR是Kubernetes扩展性的基石，掌握它们意味着能将任何业务逻辑转化为Kubernetes原生资源。对于开发者，建议：

1. 从简单CRD开始：先定义无状态的资源，逐步添加验证和子资源；
2. 使用Operator框架：如Kubebuilder或Metacontroller，加速控制器开发；
3. 参考开源项目：如Prometheus Operator、Istio的CRD设计，学习最佳实践。

通过CRD与CR，开发者不仅能提升资源管理的效率，更能深度融入云原生生态，构建可扩展、可维护的分布式系统。