4. API 定义与 CRD 生成：定义自定义资源（CR）结构体、使用 markers 标签、生成 CRD YAML

在 Operator 开发中，自定义资源（CR）是核心数据模型，它定义了用户期望的集群状态。本章将深入讲解如何使用 Go 结构体定义 CR、通过 markers 标签控制生成行为，并最终生成 CRD（CustomResourceDefinition）YAML 文件。

4.1 自定义资源结构体定义

Operator SDK 使用 Kubernetes 风格的 API 结构体来定义 CR。每个 CR 通常包含三个核心部分：TypeMeta、ObjectMeta 和 Spec/Status。

以下是一个典型的 CR 结构体定义示例（位于 api/v1/ 目录下）：

package v1

import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

// MyAppSpec 定义用户期望的应用配置
type MyAppSpec struct {
    // +kubebuilder:validation:Required
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=10
    Replicas int32 `json:"replicas"`

    // +kubebuilder:validation:Required
    Image string `json:"image"`

    // +kubebuilder:validation:Optional
    // +kubebuilder:default="default-config"
    ConfigName string `json:"configName,omitempty"`
}

// MyAppStatus 定义应用当前状态
type MyAppStatus struct {
    // +kubebuilder:validation:Optional
    AvailableReplicas int32 `json:"availableReplicas,omitempty"`

    // +kubebuilder:validation:Optional
    Conditions []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:path=myapps,scope=Namespaced
// +kubebuilder:printcolumn:name="Replicas",type="integer",JSONPath=".spec.replicas"
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"

// MyApp 是 CR 的主结构体
type MyApp struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   MyAppSpec   `json:"spec,omitempty"`
    Status MyAppStatus `json:"status,omitempty"`
}

// +kubebuilder:object:root=true

// MyAppList 包含多个 MyApp 实例
type MyAppList struct {
    metav1.TypeMeta `json:",inline"`
    metav1.ListMeta `json:"metadata,omitempty"`
    Items           []MyApp `json:"items"`
}

4.2 Markers 标签详解

Markers 是 Operator SDK 中用于控制代码生成、CRD 验证、打印列等行为的注释标签。它们以 +kubebuilder: 或 +k8s: 开头，直接写在结构体或字段上方。

4.3 CRD YAML 生成流程

定义好结构体和 markers 后，通过以下命令生成 CRD YAML：

# 生成所有 CRD YAML 文件（默认输出到 config/crd/bases/）
make generate

# 仅生成 CRD 清单（不包含其他资源）
make manifests

# 查看生成的 CRD 文件
ls config/crd/bases/
# 输出示例：example.com_myapps.yaml

生成的 CRD YAML 文件结构如下：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.14.0
  name: myapps.example.com
spec:
  group: example.com
  names:
    kind: MyApp
    listKind: MyAppList
    plural: myapps
    singular: myapp
  scope: Namespaced
  versions:
  - name: v1
    schema:
      openAPIV3Schema:
        description: MyApp 是 CR 的主结构体
        properties:
          spec:
            properties:
              replicas:
                format: int32
                minimum: 1
                maximum: 10
                type: integer
              image:
                type: string
              configName:
                default: default-config
                type: string
            required:
            - replicas
            - image
            type: object
          status:
            properties:
              availableReplicas:
                format: int32
                type: integer
              conditions:
                items:
                  type: object
                  x-kubernetes-preserve-unknown-fields: true
                type: array
            type: object
        type: object
    subresources:
      status: {}
    additionalPrinterColumns:
    - jsonPath: .spec.replicas
      name: Replicas
      type: integer
    - jsonPath: .metadata.creationTimestamp
      name: Age
      type: date

4.4 CRD 生成流程示意图

下图展示了从 Go 结构体到 CRD YAML 的完整生成链路：

4.5 验证 CRD 与测试 CR 实例

生成 CRD 后，可以通过以下步骤验证：

1. 安装 CRD 到集群：make install 或 kubectl apply -f config/crd/bases/
2. 查看已安装的 CRD：kubectl get crd | grep myapps
3. 创建 CR 实例：编写 YAML 文件并 kubectl apply -f config/samples/
4. 验证 CR 状态：kubectl get myapps -o yaml

示例 CR 实例 YAML（config/samples/example_v1_myapp.yaml）：

apiVersion: example.com/v1
kind: MyApp
metadata:
  name: myapp-sample
spec:
  replicas: 3
  image: nginx:1.25
  configName: prod-config

4.6 常见问题与避坑指南