CRD 与 Operator 模式

apiVersion: db.example.com/v1
kind: PostgresCluster
metadata:
  name: orders
spec:
  version: "16"
  instances: 3
  storage: 100Gi
  backup:
    schedule: "0 2 * * *"

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com      # 必须是 <plural>.<group>
spec:
  group: stable.example.com
  scope: Namespaced                      # 或 Cluster
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab
    shortNames: ["ct"]
  versions:
    - name: v1
      served: true                       # 是否通过 API 提供这个版本
      storage: true                      # 在 etcd 中以哪个版本存储（有且仅有一个）
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required: ["cronSpec", "image"]
              properties:
                cronSpec:
                  type: string
                  pattern: '^(\S+\s+){4}\S+$'
                image:
                  type: string
                replicas:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 1
                concurrencyPolicy:
                  type: string
                  enum: ["Allow", "Forbid", "Replace"]
                  default: Allow
              x-kubernetes-validations:
                - rule: "self.concurrencyPolicy != 'Allow' || self.replicas <= 3"
                  message: "replicas must be <= 3 when concurrencyPolicy is Allow"
            status:
              type: object
              properties:
                lastScheduleTime:
                  type: string
                  format: date-time
                phase:
                  type: string
      subresources:
        status: {}                       # 启用 /status 子资源
      additionalPrinterColumns:
        - name: Schedule
          type: string
          jsonPath: .spec.cronSpec
        - name: Phase
          type: string
          jsonPath: .status.phase
        - name: Age
          type: date
          jsonPath: .metadata.creationTimestamp

kubectl apply -f crontab-crd.yaml
kubectl get crd crontabs.stable.example.com
kubectl api-resources --api-group=stable.example.com
kubectl explain crontab.spec                 # schema 自动变成文档

cat <<'EOF' | kubectl apply -f -
apiVersion: stable.example.com/v1
kind: CronTab
metadata:
  name: bad
spec:
  cronSpec: "every minute"
  image: busybox
  replicas: 20
  colour: red
EOF
# The CronTab "bad" is invalid:
# * spec.cronSpec: Invalid value: "every minute": spec.cronSpec in body should match '^(\S+\s+){4}\S+$'
# * spec.replicas: Invalid value: 20: spec.replicas in body should be less than or equal to 10
# * spec: Invalid value: "object": replicas must be <= 3 when concurrencyPolicy is Allow

          ┌───────────────── watch 事件（CR、子资源变化）─────────────────┐
          ▼                                                              │
   WorkQueue（按 namespace/name 去重）                                    │
          │                                                              │
          ▼                                                              │
   Reconcile(namespace/name):                                            │
     1. 读取 CR 的当前 spec（期望状态）                                     │
     2. 读取它拥有的子资源（实际状态）                                       │
     3. 计算差异，创建/更新/删除子资源，使实际趋近期望 ──────────────────────┘
     4. 更新 CR 的 status
     5. 返回：成功 / 出错重试（指数退避）/ N 秒后再来

# 需要 Go 与 kubebuilder，版本以官方发布为准
kubebuilder init --domain example.com --repo example.com/webapp-operator
kubebuilder create api --group apps --version v1alpha1 --kind WebApp --resource --controller

webapp-operator/
├── api/v1alpha1/
│   └── webapp_types.go          # ← 定义 Spec/Status，CRD schema 从这里生成
├── internal/controller/
│   └── webapp_controller.go     # ← 写 Reconcile 逻辑
├── cmd/main.go                  # Manager 启动入口：注册 scheme、控制器、健康检查、选主
├── config/
│   ├── crd/                     # make manifests 生成的 CRD YAML
│   ├── rbac/                    # 由 +kubebuilder:rbac 标记生成的 ClusterRole（含聚合角色）
│   ├── manager/                 # Operator 自身的 Deployment
│   └── samples/                 # 示例 CR
└── Makefile                     # make manifests / generate / install / run / deploy

// WebAppSpec 定义期望状态
type WebAppSpec struct {
	// +kubebuilder:validation:MinLength=1
	Image string `json:"image"`

	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=20
	// +kubebuilder:default=2
	Replicas int32 `json:"replicas,omitempty"`

	// +kubebuilder:default=8080
	Port int32 `json:"port,omitempty"`
}

// WebAppStatus 定义观察到的状态
type WebAppStatus struct {
	ReadyReplicas      int32              `json:"readyReplicas,omitempty"`
	ObservedGeneration int64              `json:"observedGeneration,omitempty"`
	Conditions         []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:printcolumn:name="Image",type=string,JSONPath=`.spec.image`
// +kubebuilder:printcolumn:name="Ready",type=integer,JSONPath=`.status.readyReplicas`
type WebApp struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   WebAppSpec   `json:"spec,omitempty"`
	Status WebAppStatus `json:"status,omitempty"`
}

// +kubebuilder:rbac:groups=apps.example.com,resources=webapps,verbs=get;list;watch;update;patch
// +kubebuilder:rbac:groups=apps.example.com,resources=webapps/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups="",resources=services,verbs=get;list;watch;create;update;patch;delete

func (r *WebAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	log := logf.FromContext(ctx)

	// 1. 读取 CR；已被删除则什么都不做（子资源由 ownerReferences 级联删除）
	var app appsv1alpha1.WebApp
	if err := r.Get(ctx, req.NamespacedName, &app); err != nil {
		return ctrl.Result{}, client.IgnoreNotFound(err)
	}

	// 2. 确保 Deployment 存在且与 spec 一致（幂等：CreateOrUpdate）
	deploy := &appsv1.Deployment{ObjectMeta: metav1.ObjectMeta{Name: app.Name, Namespace: app.Namespace}}
	op, err := controllerutil.CreateOrUpdate(ctx, r.Client, deploy, func() error {
		labels := map[string]string{"app.kubernetes.io/name": app.Name}
		deploy.Spec.Replicas = &app.Spec.Replicas
		deploy.Spec.Selector = &metav1.LabelSelector{MatchLabels: labels}
		deploy.Spec.Template.Labels = labels
		deploy.Spec.Template.Spec.Containers = []corev1.Container{{
			Name:  "app",
			Image: app.Spec.Image,
			Ports: []corev1.ContainerPort{{ContainerPort: app.Spec.Port}},
		}}
		// 设置 controller owner：删除 WebApp 时 Deployment 被级联删除
		return controllerutil.SetControllerReference(&app, deploy, r.Scheme)
	})
	if err != nil {
		return ctrl.Result{}, err // 返回错误 → 自动指数退避重试
	}
	log.Info("reconciled deployment", "operation", op)

	// 3. Service 同理（省略）

	// 4. 回写 status（走 /status 子资源）
	app.Status.ReadyReplicas = deploy.Status.ReadyReplicas
	app.Status.ObservedGeneration = app.Generation
	if err := r.Status().Update(ctx, &app); err != nil {
		return ctrl.Result{}, err // 409 冲突也会在这里被重试
	}
	return ctrl.Result{}, nil
}

// SetupWithManager 声明要 watch 什么
func (r *WebAppReconciler) SetupWithManager(mgr ctrl.Manager) error {
	return ctrl.NewControllerManagedBy(mgr).
		For(&appsv1alpha1.WebApp{}).     // 主资源变化 → Reconcile 它
		Owns(&appsv1.Deployment{}).      // 子资源变化 → Reconcile 其 owner
		Owns(&corev1.Service{}).
		Complete(r)
}

make manifests generate      # 根据标记生成 CRD、RBAC 和 DeepCopy 代码
make install                 # 把 CRD 安装到当前 kubeconfig 指向的集群
make run                     # 在本机以当前 kubeconfig 运行控制器，便于调试

kubectl apply -f config/samples/apps_v1alpha1_webapp.yaml
kubectl get webapp,deploy
kubectl scale deploy webapp-sample --replicas=5   # 控制器会把它改回 spec 中的值

# 正式部署：构建镜像并加载到 kind
make docker-build IMG=webapp-operator:dev
kind load docker-image webapp-operator:dev
make deploy IMG=webapp-operator:dev