颠覆认知！用了Kubernetes这么多年才最终悟透CRD

ArgoCD、KEDA、Crossplane 这些工具并非什么黑魔法，它们的核心都是CRD。一旦你理解了这一点，看待Kubernetes的视角将彻底被改变。

一、你已经用了很多年，却从未真正了解

kubectl 获取 crds

二、让你真正 “悟透” K8s的那个瞬间

三、从零开始创建一个CRD

apiVersion:  apiextensions.k8s.io/v1 kind:  CustomResourceDefinition metadata:   name:  databaseclusters.infra.example.com   # 必须为：<复数>.<组> spec:   group:  infra.example.com         # 您的 API 组（例如 apps、batch、networking.k8s.io）  scope:  Namespaced                # 或者：集群  名称:    复数:  databaseclusters       # kubectl get databaseclusters    单数:  databasecluster      # kubectl get databasecluster my-db     kind:  DatabaseCluster          # 用于 YAML 清单    shortNames:       -  dbc                        # kubectl get dbc   versions:     -  name:  v1alpha1       serving:  true                 # 此版本处于活动状态并接受请求      storage:  true                # 此版本用于 etcd 中的持久化      schema:         openAPIV3Schema:           type:  object           properties:             spec:               type:  object               properties: {}       # 我们将在下一步中填写            status:               type:  object               properties: {}

名称: databaseclusters.infra.example.com

/apis/infra.example.com/v1alpha1/databaseclusters

四、CRD本身不执行任何操作

kubectl get dbc

五、构建生产级 DatabaseCluster CRD

# database-cluster-crd.yaml apiVersion:  apiextensions.k8s.io/v1 kind:  CustomResourceDefinition metadata:   name:  databaseclusters.infra.example.com   annotations:     controller-gen.kubebuilder.io/version:  v0.14.0 spec:   group:  infra.example.com   scope:  Namespaced   names:     plural:  databaseclusters     singular:  databasecluster     kind:  DatabaseCluster     shortNames:       -  dbc   versions:     -  name:  v1alpha1       serve:  true       storage:  true       # 启用状态子资源（对运维人员至关重要）      subresources:         status: {}       # kubectl get dbc 输出中显示的自定义列      additionalPrinterColumns:         -  name:  Replicas           type:  integer           jsonPath:  .spec.replicas         -  name:  Region           type:  string           jsonPath:  .spec.region         -  name:  Phase           type:  string           jsonPath:  .status.phase         -  name:  Age           type:  date           jsonPath:  .metadata.creationTimestamp       schema:         openAPIV3Schema:           type:  object           properties:             spec:               type:  object               required: [ "engine" , "replicas" , "region" ]               properties:                 engine:                   type:  string                   enum: [ "postgres" , "mysql" , "mariadb" ]                   description:  "要使用的数据库引擎"                 replicas:                   type:  integer                   minimum:  1                   maximum:  9                   description:  "数据库副本数"                 region:                   type:  string                   description:  "AWS 区域或数据中心位置"                 storageGB:                   type:  integer                   minimum:  10                   default:  20                   description:  "存储大小（GB）"                 version:                   type:  string                   description:  "数据库引擎版本（例如，PostgreSQL 的 '16.2'）"             status:               type:  object               properties:                 phase:                   type: 字符串                  描述： “当前生命周期阶段：待处理、配置中、就绪、失败”                端点：                  类型： 字符串                  描述： “集群就绪后的连接端点”                条件：                  类型： 数组                  项：                    类型： 对象                    属性：                      类型：                        字符串 状态                      ：                        类型： 字符串                      lastTransitionTime：                        类型： 字符串                        格式： 日期时间                      原因：                        类型： 字符串                      消息：                        类型： 字符串

六、为什么Schema至关重要

kubectl apply -f database-cluster-crd.yaml 
# 验证是否已注册kubectl get crd databaseclusters.infra.example.com 
# 创建于# databaseclusters.infra.example.com 2026-03-31T16:00:00Z

七、创建第一个自定义资源

# my-postgres.yamlapiVersion: infra.example.com/v1alpha1kind: DatabaseClustermetadata:  name: production-postgres  namespace: databasesspec:  engine: postgres  replicas: 3  region: ap-south-1  version: "16.2"

kubectl apply -f my -postgres.yaml 
# 像操作任何原生资源一样操作它kubectl get dbc -n databases 
# NAME REPLICAS REGION PHASE AGE # production-postgres 3 ap-south-1 <none> 10s
 kubectl describe dbc production-postgres -n databases kubectl delete dbc production-postgres -n databases

八、CRD如何融入Kubernetes架构

九、为什么 status 子资源如此重要

subresources:  status: {}

只有操作员才能写入 /status — 用户无法覆盖此设置。patch.status[ 'phase' ] = 'Ready' patch.status[ 'endpoint' ] = f"postgres. {name} .svc.cluster.local:5432"

十、通过Python与CRD交互

# pip install kubernetes from kubernetes import client, config 
 # 加载 kubeconfig（如果运行在 pod 中，则加载集群内配置） config.load_kube_config() 
 # 使用动态客户端访问自定义资源dyn_client = client.ApiClient() custom_api = client.CustomObjectsApi(dyn_client) 
GROUP = "infra.example.com" VERSION = "v1alpha1" PLURAL = "databaseclusters" NAMESPACE = "databases" 
 # 列出所有 DatabaseCluster 资源clusters = custom_api.list_namespaced_custom_object(     group=GROUP,     version=VERSION,     namespace=NAMESPACE,     plural=PLURAL ) 
for cluster in clusters[ "items" ]:     name = cluster[ "metadata" ][ "name" ]     phase = cluster.get( "status" , {}).get( "phase" , "Unknown" )     replicas = cluster[ "spec" ][ "replicas" ]     print(f "{name}: phase={phase}, replicas={replicas}" ) # 以编程方式创建一个新的数据库集群new_cluster = {     "apiVersion" : f "{GROUP}/{VERSION}" ,     "kind" : "DatabaseCluster" ,     "metadata" : { "name" : "staging-mysql" , "namespace" : NAMESPACE},     "spec" : {         "engine" : "mysql" ,         "replicas" : 1,         "region" : "ap-south-1" ,         "storageGB" : 20,         "version" : "8.0"     } } 
custom_api.create_namespaced_custom_object(     group=GROUP,     version=VERSION,     namespace=NAMESPACE,     plural=PLURAL,     body=new_cluster ) print( "已创建 staging-mysql 数据库集群" ) 
#修补状态（通常仅由操作员执行） status_patch = { "status" : { "phase" : "Provisioning" }} custom_api.patch_namespaced_custom_object_status(     group=GROUP,     version=VERSION,    namespace=NAMESPACE,     plural=PLURAL,     name= "staging-mysql" ,     body=status_patch )

十一、隐藏的仪表盘技巧

additionalPrinterColumns:

kubectl get dbc

名称 副本数 区域 阶段 时间production-postgres 3 ap-south-1 就绪 2天staging-mysql 1 ap-south-1 配置中 5个月

十二、导致系统崩溃的常见错误

十三、你真正学到了什么

十四、接下来会讲什么

副本数：0

十五、最后，还有一个问题

apiVersion:  backup.example.com/v1  kind:  DatabaseBackup  metadata:  name:  my-postgres-daily  spec:   database:  "postgres-prod"   schedule:  "0 2 * * *"  # 每天凌晨 2 点 执行 retention:  7  # 保留 7 个备份

都能在XCOPS智能运维管理人年会-广州站上看到生产级实战案例、找到可参考可落地的方式方法。扫描下方二维码可了解大会详情及报名↓