深入解析Kubernetes中的Custom Resource Definitions (CRD)：扩展API的“乐高积木”

最新推荐文章于 2025-11-23 12:47:13 发布

原创最新推荐文章于 2025-11-23 12:47:13 发布 · 568 阅读

20 ·

CC 4.0 BY-SA版权

文章标签：

#kubernetes #容器 #云原生

云原生技术深度解析专栏收录该内容

62 篇文章

订阅专栏

前言

在 Kubernetes 的世界里，Pod、Service、Deployment 是我们最熟悉的“积木”。但当业务需求超越了这些原生资源的能力边界时，你是否曾感到束手无策？

如何让 Kubernetes 原生管理一个数据库实例的创建、备份、恢复？
如何自动化部署和配置一个消息队列集群（如 Kafka、RabbitMQ）？
如何定义一个机器学习模型服务的生命周期，从训练到上线推理？
如何让运维团队通过 kubectl 直接管理外部云资源（如 AWS S3 Bucket、Azure SQL）？

传统的 ConfigMap、Secret 或脚本化方案已无法优雅地解决这些问题。而修改 Kubernetes 源码？成本高昂且难以维护。

Custom Resource Definitions (CRD) 正是 Kubernetes v1.7+ 引入的“API 扩展机制”。它允许你无需修改 Kubernetes 源码，就能定义全新的资源类型（如 DatabaseInstance、MLModel），并像使用原生资源一样通过 kubectl 管理它们。CRD 是构建 Operator 模式的基石，让你能将复杂的领域知识封装成 Kubernetes 原生的 API 对象。

本文将深入剖析 CRD 的核心结构、定义方法、验证机制与最佳实践，助你掌握 Kubernetes 扩展能力的“终极武器”。

一、什么是CRD？

🎯 定义：CRD 是一种 Kubernetes 资源，用于定义新的自定义资源（Custom Resource, CR），从而扩展 Kubernetes API。

1.1 核心价值

API 自定义：创建符合业务语义的专属资源类型。
声明式管理：通过 YAML 定义复杂应用的完整状态。
生态集成：无缝融入 kubectl、Helm、GitOps 等工具链。
Operator 基石：为自定义控制器（Controller）提供操作对象。

✅ 相当于为 Kubernetes 的“乐高世界”添加了全新的积木块。

二、核心概念：CRD vs Custom Resource

概念	说明	示例
CRD	定义新资源的“蓝图”或“Schema”	`DatabaseInstance` 的结构定义
Custom Resource (CR)	根据 CRD 创建的“实例”	一个名为 `prod-mysql-01` 的数据库实例

# 1. 定义 CRD (蓝图)
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databaseinstances.database.example.com
spec:
  group: database.example.com
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              engine:
                type: string
                enum: [mysql, postgres]
              size:
                type: string
  scope: Namespaced
  names:
    plural: databaseinstances
    singular: databaseinstance
    kind: DatabaseInstance
    shortNames: [dbi]

---
# 2. 创建 CR (实例)
apiVersion: database.example.com/v1
kind: DatabaseInstance
metadata:
  name: prod-mysql-01
spec:
  engine: mysql
  size: "100Gi"

三、CRD核心字段详解

3.1 `spec.group`

含义：API 组名，用于 API 路径和避免命名冲突。
格式：<domain>/<version>，如 database.example.com/v1。
约定：使用公司或项目域名倒序。

3.2 `spec.versions`

含义：支持的 API 版本。
关键字段

：
- name: 版本名（如 v1, v1beta1）。
- served: 是否提供该版本的 API 服务。
- storage: 哪个版本用于持久化存储（有且仅有一个 true）。
- schema: 核心，定义资源的 OpenAPI v3 Schema。

3.3 `spec.scope`

Namespaced: 资源属于某个命名空间（最常见）。
Cluster: 集群级别资源（如 Node、StorageClass）。

3.4 `spec.names`

plural: 复数形式，用于 URL（如 /apis/database.example.com/v1/databaseinstances）。
singular: 单数形式（如 databaseinstance）。
kind: 资源类型（如 DatabaseInstance），首字母大写。
shortNames: 简写（如 kubectl get dbi）。

四、OpenAPI v3 Schema：定义资源结构

4.1 数据类型

schema:
  openAPIV3Schema:
    type: object
    properties:
      spec:
        type: object
        required: [engine, size]  # 必填字段
        properties:
          engine:
            type: string
            enum: [mysql, postgres, mongodb]
          size:
            type: string
            pattern: '^\d+Gi$'  # 正则校验
          replicas:
            type: integer
            minimum: 1
            maximum: 5
          enabled:
            type: boolean
            default: true

✅ 支持 string, integer, number, boolean, array, object 等。

4.2 嵌套对象

properties:
  backup:
    type: object
    properties:
      schedule:
        type: string  # cron 表达式
      retention:
        type: integer
        minimum: 1

五、真实场景与最佳实践

5.1 场景1：数据库即服务 (DBaaS)

# CRD: DatabaseInstance
spec:
  engine: mysql
  size: "100Gi"
  replicas: 3
  backup:
    schedule: "0 2 * * *"
    retention: 7

Operator：监听 DatabaseInstance，调用云 API 创建 RDS 实例。

5.2 场景2：机器学习模型服务

# CRD: MLModel
spec:
  modelPath: s3://models/v1/resnet50.pth
  framework: pytorch
  resources:
    requests:
      cpu: "4"
      memory: "16Gi"
      nvidia.com/gpu: 1
  autoscaler:
    minReplicas: 1
    maxReplicas: 10

Operator：部署推理服务，配置 HPA。

5.3 场景3：外部资源管理

# CRD: S3Bucket
spec:
  bucketName: my-app-logs
  region: us-east-1
  versioning: true
  lifecycleRules:
    - prefix: logs/
      days: 90
      action: expire

Operator：调用 AWS SDK 创建和管理 S3 存储桶。

5.4 场景4：配置即代码

# CRD: FeatureFlag
spec:
  enabled: true
  rolloutStrategy:
    type: percentage
    value: 10
  targeting:
    - attribute: country
      value: "US"

Operator：将配置同步到 Redis、Consul 等配置中心。

六、高级特性

6.1 多版本支持与转换

versions:
- name: v1beta1
  served: true
  storage: false
  schema: ... # 旧版 schema
- name: v1
  served: true
  storage: true
  schema: ... # 新版 schema
conversion:
  strategy: Webhook
  webhook:
    clientConfig:
      service:
        namespace: crd-system
        name: crd-conversion-webhook
    conversionReviewVersions: ["v1"]