介绍

[!Tip] 心急的读者可以直接跳到 快速开始。

[!Important] 仍在使用旧版 Kubebuilder？请查看遗留文档：v1、v2 或 v3。

这适合谁

Kubernetes 的用户

Kubernetes 用户将通过学习 API 设计和实现的基本概念，深入理解 Kubernetes。 本书将教会读者如何开发自己的 Kubernetes API 以及核心 Kubernetes API 设计的原则。

包括：

• Kubernetes API 和资源的结构
• API 版本控制语义
• 自我修复
• 垃圾收集与终结器
• 声明式 API 与 命令式 API
• 基于级别 vs 基于边沿的 API
• 资源与子资源

Kubernetes API 扩展开发者

API 扩展开发者将学习实现规范 Kubernetes API 的原则和概念，以及用于快速执行的简单工具和库。 本书涵盖了扩展开发者常遇到的陷阱和误解。

包括：

• 如何将多个事件批量合并到一次对账调用中
• 如何配置定期对账
• 即将到来
  • 何时使用列出缓存与实时查找
  • 垃圾回收（Garbage Collection）与终结器（Finalizers）
  • 如何使用声明式验证与 Webhook 验证
  • 如何实现 API 版本控制

为什么选择 Kubernetes API

Kubernetes API 为遵循一致且丰富结构的对象提供统一且定义清晰的端点。

这种方式促进了丰富的工具和库生态系统与 Kubernetes API 进行交互。

用户通过将对象声明为 YAML 或 JSON 配置，并使用通用工具来管理这些对象，从而使用 API。

将服务构建为 Kubernetes API 相较于传统的REST，有以下优势：

• 托管的 API 网络端点、存储和验证。
• 丰富的工具和命令行接口，例如 kubectl 和 kustomize。
• 支持身份验证（AuthN）和细粒度授权（AuthZ）。
• 通过 API 版本控制和转换并且支持 API 版本演进。
• 促进自适应/自愈 API 的实现，它们能够在没有用户干预的情况下持续响应系统状态的变化。
• Kubernetes 是一个托管环境

开发者可以构建并发布自己的 Kubernetes API，方便安装到运行中的 Kubernetes 集群中。

贡献

如果您想为本书或代码贡献内容，请先阅读我们的 贡献 指南。

资源

• 仓库: sigs.k8s.io/kubebuilder

• Slack频道：#kubebuilder

• Google 群组: kubebuilder@googlegroups.com

架构概念图

下面的图表将帮助您更好地了解 Kubebuilder 的概念和架构。

快速开始

本快速入门指南将涵盖：

• 创建项目
• 创建一个API
• 本地运行
• 在集群中运行

前提条件

• go 版本 v1.24.6+
• 您已安装的 docker 版本为 17.03 或更高。
• kubectl 版本 v1.11.3 及以上。
• 访问 Kubernetes v1.11.3+ 集群。

安装

安装 kubebuilder：

# 下载 kubebuilder 并在本地安装。
curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
chmod +x kubebuilder && sudo mv kubebuilder /usr/local/bin/

创建一个项目

创建一个目录，然后在其中运行 init 命令以初始化新项目。示例如下：

mkdir -p ~/projects/guestbook
cd ~/projects/guestbook
kubebuilder init --domain my.domain --repo my.domain/guestbook

创建一个API

运行以下命令以创建一个新的 API（组/版本）webapp/v1，并在其上创建新的 Kind（CRD）Guestbook：

kubebuilder create api --group webapp --version v1 --kind Guestbook

可选： 编辑 API 定义和调整业务逻辑。有关更多信息，请参见 设计 API 和 控制器中的内容。

如果您正在编辑 API 定义，请使用生成清单，例如自定义资源（CRs）或自定义资源定义（CRDs）。

make manifests

// GuestbookSpec 定义了 Guestbook 的期望状态
type GuestbookSpec struct {
	// 插入额外的规格字段 - 集群的期望状态
	// 注意：修改此文件后，运行"make"以重新生成代码

	// 实例数量
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=10
	Size int32 `json:"size"`

	// GuestbookSpec 配置的 ConfigMap 名称
	// +kubebuilder:validation:MaxLength=15
	// +kubebuilder:validation:MinLength=1
	ConfigMapName string `json:"configMapName"`

	// +kubebuilder:validation:Enum=电话;地址;名称
	Type string `json:"type,omitempty"`
}

// GuestbookStatus 定义了 Guestbook 的观察状态
type GuestbookStatus struct {
	// 插入额外的状态字段 - 定义集群的观察状态
	// 重要：在修改此文件后，请运行 "make" 以重新生成代码

	// 活动的 Guestbook 节点的 Pod 名称。
	Active string `json:"active"`

	// 待命 Guestbook 节点的 Pod 名称。
	Standby []string `json:"standby"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:scope=Cluster

// Guestbook 是 guestbooks API 的 Schema
type Guestbook struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   GuestbookSpec   `json:"spec,omitempty"`
	Status GuestbookStatus `json:"status,omitempty"`
}

试一试

您需要一个可运行的 Kubernetes 集群。可以使用 KinD 获取本地测试集群，也可以针对远程集群运行。

将 CRD 安装到集群中：

make install

为了快速反馈和代码级调试，请运行控制器（该命令在前台运行；若希望保持运行，请另开终端）：

make run

安装自定义资源实例

如果在 Create Resource [y/n] 时选择了 y，则会在 config/samples/ 目录中为 CRD 创建示例 CR。

编辑 config/samples/webapp_v1_guestbook.yaml，填入有效的 spec。例如：

# ...
spec:
  foo: bar

提示：“foo” 是在 api/v1/guestbook_types.go 中定义的字符串字段：

// foo 是 Guestbook 的示例字段。请编辑 guestbook_types.go 以删除/更新
// +optional
Foo *string `json:"foo,omitempty"`

kubectl apply -k config/samples/

现在可以查看已应用的资源：

kubectl get guestbooks.webapp.my.domain guestbook-sample -o yaml

在集群中运行

当您的控制器准备好进行打包并在其他集群中测试时。

构建并将您的镜像推送到 IMG 所指定的位置：

make docker-build docker-push IMG=<some-registry>/<project-name>:tag

将控制器部署到集群，使用 IMG 指定的镜像：

make deploy IMG=<some-registry>/<project-name>:tag

卸载 CRD（自定义资源定义）

要从集群中删除您的 CRD：

make uninstall

取消部署控制器

将控制器从集群中撤销部署：

make undeploy

使用插件

Kubebuilder 的设计基于插件，您可以使用可用插件为项目添加可选功能。

后续步骤

• 入门指南（约 30 分钟）— 打下坚实基础
• CronJob 教程 — 通过构建示例项目学习
• 组、版本与种类 — 理解 API 设计概念

入门

本指南创建一个示例项目以演示其工作方式。该示例：

• 对 Memcached CR 进行调整 - 该 CR 表示在集群上部署/管理的 Memcached 实例
• 使用 Memcached 镜像创建一个部署
• 不允许超过 CR 中定义的 size 的实例数
• 更新 Memcached CR 状态

创建一个项目

首先，创建并导航到你的项目目录。然后，使用 kubebuilder 初始化它：

mkdir $GOPATH/memcached-operator
cd $GOPATH/memcached-operator
kubebuilder init --domain=example.com

创建 Memcached API（CRD）

接下来，创建负责在集群上部署并管理 Memcached 实例的 API。

kubebuilder create api --group cache --version v1alpha1 --kind Memcached

理解API

该命令的主要目的是为 Memcached Kind 生成自定义资源（CR）与自定义资源定义（CRD）。它创建 group 为 cache.example.com、version 为 v1alpha1 的 API，唯一标识 Memcached Kind 的新 CRD。借助 Kubebuilder，您可以定义代表这些平台上解决方案的 API 与对象。

本示例只添加一种 Kind 资源，但您可以按需拥有任意数量的 Groups 与 Kinds。为便于理解，可将 CRD 视为自定义对象的定义，而 CR 是它们的实例。

定义我们的 API

定义 Spec

现在定义集群上每个 Memcached 资源实例可取的值。本例中，配置允许用如下方式设置实例数量：

type MemcachedSpec struct {
	...
	// +kubebuilder:validation:Minimum=0
	// +required
	Size *int32 `json:"size,omitempty"`
}

创建 Status 定义

控制器还需要跟踪为管理 Memcached CR 所执行操作的状态。这样可以核验自定义资源对 API 的描述，并判断是否全部成功或是否遇到错误，方式与处理任何 Kubernetes API 资源相同。

// MemcachedStatus 定义了 Memcached 的观察状态
type MemcachedStatus struct {
    // +listType=map
    // +listMapKey=type
    // +optional
    Conditions []metav1.Condition `json:"conditions,omitempty"`
}

标记和验证

此外，应对 CustomResource 中的取值进行校验以确保有效。为此可使用标记，例如 +kubebuilder:validation:Minimum=1。

现在，请查看我们完全完成的示例。

Apache License

http://www.apache.org/licenses/LICENSE-2.0

Imports

package v1alpha1

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

// 请编辑本文件！这是供您拥有的脚手架代码！
// 注意：需要 json 标签。新增字段必须带有 json 标签才能被序列化。

// MemcachedSpec 定义 Memcached 的期望状态
type MemcachedSpec struct {
	// 在此插入额外 SPEC 字段 — 集群期望状态
	// 重要：修改本文件后请运行 "make" 重新生成代码
	// 下列标记将使用 OpenAPI v3 schema 校验取值
	// 更多信息： https://book.kubebuilder.io/reference/markers/crd-validation.html

	// size 定义 Memcached 实例数量
	// 下列标记将使用 OpenAPI v3 schema 校验取值
	// 更多信息： https://book.kubebuilder.io/reference/markers/crd-validation.html
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=3
	// +kubebuilder:validation:ExclusiveMaximum=false
	// +optional
	Size *int32 `json:"size,omitempty"`
}

// MemcachedStatus 定义 Memcached 的观测状态.
type MemcachedStatus struct {
	// 插入额外的状态字段 - 定义集群的观察状态
	// 重要：在修改此文件后，请运行 "make" 以重新生成代码

	// Kubernetes API 约定参见：
	// https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties

	// conditions 表示 Memcached 资源的当前状态。
	// 每个 condition 有唯一类型，反映资源某一方面的状态。
	//
	// Standard condition types include:
	// - "Available": the resource is fully functional
	// - "Progressing": the resource is being created or updated
	// - "Degraded": the resource failed to reach or maintain its desired state
	//
	// The status of each condition is one of True, False, or Unknown.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status

// Memcached 是 memcacheds API 的 Schema
type Memcached struct {
	metav1.TypeMeta `json:",inline"`

	// metadata 是标准对象元数据
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec 定义 Memcached 的期望状态
	// +required
	Spec MemcachedSpec `json:"spec"`

	// status 定义 Memcached 的观测状态
	// +optional
	Status MemcachedStatus `json:"status,omitzero"`
}

// +kubebuilder:object:root=true

// MemcachedList 包含 Memcached 的列表
type MemcachedList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []Memcached `json:"items"`
}

func init() {
	SchemeBuilder.Register(func(s *runtime.Scheme) error {
		s.AddKnownTypes(SchemeGroupVersion, &Memcached{}, &MemcachedList{})
		return nil
	})
}

生成具有规格和验证的清单

生成所有所需的文件：

1. 运行 make generate,会在 api/v1alpha1/zz_generated.deepcopy.go 文件中添加深度拷贝（DeepCopy）内容。

2. 然后运行 make manifests，在 config/crd/bases 下生成 CRD 清单，并在 config/samples 下生成示例。

这两个命令都使用 controller-gen 工具，但是用于代码和清单生成的标志会有所不同。

---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.22.0
  name: memcacheds.cache.example.com
spec:
  group: cache.example.com
  names:
    kind: Memcached
    listKind: MemcachedList
    plural: memcacheds
    singular: Memcached
  scope: Namespaced
  versions:
  - name: v1alpha1
    schema:
      openAPIV3Schema:
        description: Memcached 是 memcacheds API 的 Schema
        properties:
          apiVersion:
            description: |-
              APIVersion defines the versioned schema of this representation of an object.
              Servers should convert recognized schemas to the latest internal value, and
              may reject unrecognized values.
              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
            type: string
          kind:
            description: |-
              Kind is a string value representing the REST resource this object represents.
              Servers may infer this from the endpoint the client submits requests to.
              Cannot be updated.
              In CamelCase.
              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
            type: string
          metadata:
            type: object
          spec:
            description: spec defines the desired state of Memcached
            properties:
              size:
                description: |-
                  size defines the number of Memcached instances
                  The following markers will use OpenAPI v3 schema to validate the value
                  More info: https://book.kubebuilder.io/reference/markers/crd-validation.html
                format: int32
                maximum: 3
                minimum: 1
                type: integer
            type: object
          status:
            description: status defines the observed state of Memcached
            properties:
              conditions:
                description: |-
                  conditions represent the current state of the Memcached resource.
                  Each condition has a unique type and reflects the status of a specific aspect of the resource.

                  Standard condition types include:
                  - "Available": the resource is fully functional
                  - "Progressing": the resource is being created or updated
                  - "Degraded": the resource failed to reach or maintain its desired state

                  The status of each condition is one of True, False, or Unknown.
                items:
                  description: Condition contains details for one aspect of the current
                    state of this API Resource.
                  properties:
                    lastTransitionTime:
                      description: |-
                        lastTransitionTime is the last time the condition transitioned from one status to another.
                        This should be when the underlying condition changed.  If that is not known, then using the time when the API field changed is acceptable.
                      format: date-time
                      type: string
                    message:
                      description: |-
                        message is a human readable message indicating details about the transition.
                        This may be an empty string.
                      maxLength: 32768
                      type: string
                    observedGeneration:
                      description: |-
                        observedGeneration represents the .metadata.generation that the condition was set based upon.
                        For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
                        with respect to the current state of the instance.
                      format: int64
                      minimum: 0
                      type: integer
                    reason:
                      description: |-
                        reason contains a programmatic identifier indicating the reason for the condition's last transition.
                        Producers of specific condition types may define expected values and meanings for this field,
                        and whether the values are considered a guaranteed API.
                        The value should be a CamelCase string.
                        This field may not be empty.
                      maxLength: 1024
                      minLength: 1
                      pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
                      type: string
                    status:
                      description: status of the condition, one of True, False, Unknown.
                      enum:
                      - "True"
                      - "False"
                      - Unknown
                      type: string
                    type:
                      description: type of condition in CamelCase or in foo.example.com/CamelCase.
                      maxLength: 316
                      pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
                      type: string
                  required:
                  - lastTransitionTime
                  - message
                  - reason
                  - status
                  - type
                  type: object
                type: array
                x-kubernetes-list-map-keys:
                - type
                x-kubernetes-list-type: map
            type: object
        required:
        - spec
        type: object
    served: true
    storage: true
    subresources:
      status: {}

自定义资源示例

在 config/samples 目录下的清单,可以应用于集群的自定义资源示例。在这个例子中，通过将给定的资源应用于集群，我们将生成一个实例大小为1的部署（请参见 size: 1）。

apiVersion: cache.example.com/v1alpha1
kind: Memcached
metadata:
  labels:
    app.kubernetes.io/name: project
    app.kubernetes.io/managed-by: kustomize
  name: memcached-sample
spec:
  # TODO(用户)：编辑以下值以确保您的操作数在集群中的 Pod/实例数量
 size: 1

协调过程

简单来说，Kubernetes 允许声明系统期望状态，控制器持续观察集群并采取行动，使实际状态与期望状态一致。自定义 API 与控制器的过程类似。请记住，您是在扩展 Kubernetes 行为及其 API 以满足特定需求。

在控制器中，我们实现协调过程。

本质上， reconciliation 过程作为一个循环运行，不断检查条件并执行必要的操作，直到达到所需的状态。该过程将持续运行，直到系统中的所有条件与我们实施中定义的所需状态一致。

这是一个伪代码示例来说明这一点：

reconcile App {

  // 检查应用的 Deployment 是否存在，若不存在则创建
  // 若出错，则从协调过程开头重新开始
  if err != nil {
    return reconcile.Result{}, err
  }

  // 检查应用的 Service 是否存在，若不存在则创建
  // 若出错，则从协调过程开头重新开始
  if err != nil {
    return reconcile.Result{}, err
  }

  // 查找 Database CR/CRD
  // 检查 Database Deployment 的副本数
  // 若 deployment.replicas 与 cr.size 不匹配， then update it
  // Then, requeue the reconciliation to ensure the desired state is reached. For example, by returning `reconcile.Result{RequeueAfter: time.Minute}, nil`.
  if err != nil {
    return reconcile.Result{RequeueAfter: time.Minute}, nil
  }
  ...

  // 若循环结束时：
  // 全部执行成功，协调可以停止
  return reconcile.Result{}, nil

}

在我们例子的背景下。

将示例自定义资源（CR）应用到集群时（即 kubectl apply -f config/sample/cache_v1alpha1_memcached.yaml），确保控制器为 Memcached 镜像创建 Deployment，且副本数与 CR 中定义一致。

为此，首先实现检查集群上是否已有该 Memcached 实例的 Deployment 的操作；若不存在，控制器再创建。因此协调过程必须包含用于持续维持该期望状态的操作，例如：

	// 检查部署是否已经存在，如果不存在则创建一个新部署。
	found := &appsv1.Deployment{}
	err = r.Get(ctx, types.NamespacedName{Name: memcached.Name, Namespace: memcached.Namespace}, found)
	if err != nil && apierrors.IsNotFound(err) {
		// 定义新的部署 
		dep := r.deploymentForMemcached()
		// 在集群上创建部署
		if err = r.Create(ctx, dep); err != nil {
            log.Error(err, "无法创建新的部署",
            "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
            return ctrl.Result{}, err
        }
		...
	}

接下来注意，deploymentForMemcached() 需要定义并返回应在集群上创建的 Deployment。该函数应按必要规格构造 Deployment 对象，如下例所示：

    dep := &appsv1.Deployment{
		Spec: appsv1.DeploymentSpec{
			Replicas: &replicas,
			Template: corev1.PodTemplateSpec{
				Spec: corev1.PodSpec{
					Containers: []corev1.Container{{
						Image:           "memcached:1.6.26-alpine3.19",
						Name:            "memcached",
						ImagePullPolicy: corev1.PullIfNotPresent,
						Ports: []corev1.ContainerPort{{
							ContainerPort: 11211,
							Name:          "memcached",
						}},
						Command: []string{"memcached", "--memory-limit=64", "-o", "modern", "-v"},
					}},
				},
			},
		},
	}

此外，实现机制以校验集群上 Memcached 副本数是否与 Custom Resource（CR）中的期望数量一致。若不一致，协调必须更新集群以保持一致。这意味着每当创建或更新 Memcached Kind 的 CR 时，控制器会持续协调，直到实际副本数与期望一致。下例说明该过程：

	...
	size := memcached.Spec.Size
	if *found.Spec.Replicas != size {
		found.Spec.Replicas = &size
		if err = r.Update(ctx, found); err != nil {
			log.Error(err, "Failed to update Deployment",
				"Deployment.Namespace", found.Namespace, "Deployment.Name", found.Name)
            return ctrl.Result{}, err
        }
    ...

现在，您可以查看负责管理 Memcached 类型自定义资源的完整控制器。该控制器确保集群中维持所需状态，确保我们的 Memcached 实例继续运行，并保持用户指定的副本数量。

/*
Copyright 2026 The Kubernetes authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

package controller

import (
	"context"
	"fmt"
	"time"

	appsv1 "k8s.io/api/apps/v1"
	corev1 "k8s.io/api/core/v1"
	apierrors "k8s.io/apimachinery/pkg/api/errors"
	"k8s.io/apimachinery/pkg/api/meta"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/types"

	"k8s.io/apimachinery/pkg/runtime"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/client"
	logf "sigs.k8s.io/controller-runtime/pkg/log"

	cachev1alpha1 "example.com/memcached/api/v1alpha1"
)

// 管理状态条件的定义
const (
	// typeAvailableMemcached 表示部署调整的状态
	typeAvailableMemcached = "Available"
)

const memcachedContainerName = "memcached"

// MemcachedReconciler 负责调整 Memcached 对象。
type MemcachedReconciler struct {
	client.Client
	Scheme *runtime.Scheme
}

// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/finalizers,verbs=update
// +kubebuilder:rbac:groups=events.k8s.io,resources=events,verbs=create;patch
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=core,resources=pods,verbs=get;list;watch

// Reconcile 是主 kubernetes 协调循环的一部分，其目标是
// 使集群当前状态更接近期望状态。
// It is essential for the controller's reconciliation loop to be idempotent. By following the Operator
// pattern you will create Controllers which provide a reconcile function
// responsible for synchronizing resources until the desired state is reached on the cluster.
// Breaking this recommendation goes against the design principles of controller-runtime.
// and may lead to unforeseen consequences such as resources becoming stuck and requiring manual intervention.
// For further info:
// - About Operator Pattern: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/
// - About Controllers: https://kubernetes.io/docs/concepts/architecture/controller/
//
// 更多细节参见 Reconcile 及其 Result：
// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.25.0/pkg/reconcile
func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	log := logf.FromContext(ctx)

	// 获取 Memcached 实例
	// 目的是检查 Kind Memcached 的自定义资源是否
	// 已在集群上应用，如果没有，我们返回 nil 以停止对账过程
	memcached := &cachev1alpha1.Memcached{}
	err := r.Get(ctx, req.NamespacedName, memcached)
	if err != nil {
		if apierrors.IsNotFound(err) {
			// 如果未找到自定义资源，通常意味着它已被删除或未创建
			// 这样，我们将停止调整过程
			log.Info("Memcached resource not found. Ignoring since object must be deleted")
			return ctrl.Result{}, nil
		}
		// 读取对象时出错 - 重新排队请求。
		log.Error(err, "Failed to get memcached")
		return ctrl.Result{}, err
	}

	// 当没有可用状态时，我们将状态设置为未知。
	if len(memcached.Status.Conditions) == 0 {
		meta.SetStatusCondition(&memcached.Status.Conditions, metav1.Condition{Type: typeAvailableMemcached, Status: metav1.ConditionUnknown, Reason: reasonReconciling, Message: "Starting reconciliation"})
		if err = r.Status().Update(ctx, memcached); err != nil {
			log.Error(err, "Failed to update Memcached status")
			return ctrl.Result{}, err
		}

		// 在更新状态后，让我们重新获取 memcached 自定义资源
		// 这样我们就可以获得集群中资源的最新状态，避免
		// 引发错误"对象已被修改，请将
		// 您的更改应用于最新版本并重试"，这将在后续操作中
		// 如果我们再次尝试更新它，将重新触发对账过程
		if err := r.Get(ctx, req.NamespacedName, memcached); err != nil {
			log.Error(err, "Failed to re-fetch memcached")
			return ctrl.Result{}, err
		}
	}

	// 检查部署是否已经存在，如果不存在则创建一个新部署。
	found := &appsv1.Deployment{}
	err = r.Get(ctx, types.NamespacedName{Name: memcached.Name, Namespace: memcached.Namespace}, found)
	if err != nil && apierrors.IsNotFound(err) {
		// 定义新的部署 
		dep, err := r.deploymentForMemcached(memcached)
		if err != nil {
			log.Error(err, "Failed to define new Deployment resource for Memcached")

			// 以下实现将更新状态
			meta.SetStatusCondition(&memcached.Status.Conditions, metav1.Condition{Type: typeAvailableMemcached,
				Status: metav1.ConditionFalse, Reason: reasonReconciling,
				Message: fmt.Sprintf("Failed to create Deployment for the custom resource (%s): (%s)", memcached.Name, err)})

			if err := r.Status().Update(ctx, memcached); err != nil {
				log.Error(err, "Failed to update Memcached status")
				return ctrl.Result{}, err
			}

			return ctrl.Result{}, err
		}

		log.Info("Creating a new Deployment",
			"Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
		if err = r.Create(ctx, dep); err != nil {
			log.Error(err, "无法创建新的部署",
				"Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
			return ctrl.Result{}, err
		}

		// 部署成功创建
		// 我们将重新排队调整，以确保状态
		// 并继续进行下一步操作
		return ctrl.Result{RequeueAfter: time.Minute}, nil
	} else if err != nil {
		log.Error(err, "Failed to get Deployment")
		// 让我们返回错误，以便重新触发对账。
		return ctrl.Result{}, err
	}

	// 若 Custom Resource 未定义 size，则将期望副本数设为 0
	var desiredReplicas int32 = 0
	if memcached.Spec.Size != nil {
		desiredReplicas = *memcached.Spec.Size
	}

	// CRD API 定义了 Memcached 类型具有一个 MemcachedSpec.Size 字段
	// 用于设置集群中部署实例的数量到所需状态。
	// 因此，以下代码将确保部署的大小与我们正在对账的
	// 自定义资源的 Size 规格中定义的相同。
	if found.Spec.Replicas == nil || *found.Spec.Replicas != desiredReplicas {
		found.Spec.Replicas = new(desiredReplicas)
		if err = r.Update(ctx, found); err != nil {
			log.Error(err, "Failed to update Deployment",
				"Deployment.Namespace", found.Namespace, "Deployment.Name", found.Name)

			// 在更新状态之前重新获取 memcached 自定义资源，
			// 以便我们能够获得集群中资源的最新状态，并避免
			// 引发错误"对象已被修改，请将您的更改应用于
			// 最新版本并重试"，这将重新触发调整。
			if err := r.Get(ctx, req.NamespacedName, memcached); err != nil {
				log.Error(err, "Failed to re-fetch memcached")
				return ctrl.Result{}, err
			}

			// 以下实现将更新状态
			meta.SetStatusCondition(&memcached.Status.Conditions, metav1.Condition{Type: typeAvailableMemcached,
				Status: metav1.ConditionFalse, Reason: "Resizing",
				Message: fmt.Sprintf("Failed to update the size for the custom resource (%s): (%s)", memcached.Name, err)})

			if err := r.Status().Update(ctx, memcached); err != nil {
				log.Error(err, "Failed to update Memcached status")
				return ctrl.Result{}, err
			}

			return ctrl.Result{}, err
		}

		// 现在我们更新了大小，我们想要重新排队对账
		// 以便确保在更新之前我们拥有资源的最新状态。
		// 此外，它还将有助于确保集群上的期望状态。
		return ctrl.Result{RequeueAfter: time.Minute}, nil
	}

	// 以下实现将更新状态
	meta.SetStatusCondition(&memcached.Status.Conditions, metav1.Condition{Type: typeAvailableMemcached,
		Status: metav1.ConditionTrue, Reason: reasonReconciling,
		Message: fmt.Sprintf("自定义资源（%s）部署成功，创建了 %d 个副本", memcached.Name, desiredReplicas)})

	if err := r.Status().Update(ctx, memcached); err != nil {
		log.Error(err, "Failed to update Memcached status")
		return ctrl.Result{}, err
	}

	return ctrl.Result{}, nil
}

// SetupWithManager 将控制器与管理器进行设置。
func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error {
	return ctrl.NewControllerManagedBy(mgr).
		For(&cachev1alpha1.Memcached{}).
		Owns(&appsv1.Deployment{}).
		Named("memcached").
		Complete(r)
}

// deploymentForMemcached 返回一个 Memcached 部署对象。
func (r *MemcachedReconciler) deploymentForMemcached(
	memcached *cachev1alpha1.Memcached) (*appsv1.Deployment, error) {
	image := "memcached:1.6.26-alpine3.19"

	dep := &appsv1.Deployment{
		ObjectMeta: metav1.ObjectMeta{
			Name:      memcached.Name,
			Namespace: memcached.Namespace,
		},
		Spec: appsv1.DeploymentSpec{
			Replicas: memcached.Spec.Size,
			Selector: &metav1.LabelSelector{
				MatchLabels: map[string]string{"app.kubernetes.io/name": "project"},
			},
			Template: corev1.PodTemplateSpec{
				ObjectMeta: metav1.ObjectMeta{
					Labels: map[string]string{"app.kubernetes.io/name": "project"},
				},
				Spec: corev1.PodSpec{
					SecurityContext: &corev1.PodSecurityContext{
						RunAsNonRoot: new(true),
						SeccompProfile: &corev1.SeccompProfile{
							Type: corev1.SeccompProfileTypeRuntimeDefault,
						},
					},
					Containers: []corev1.Container{{
						Image:           image,
						Name:            memcachedContainerName,
						ImagePullPolicy: corev1.PullIfNotPresent,
						// 确保容器的限制性上下文
						// 详细信息请参考： https://kubernetes.io/docs/concepts/security/pod-security-standards/#restricted
						SecurityContext: &corev1.SecurityContext{
							RunAsNonRoot:             new(true),
							RunAsUser:                new(int64(1001)),
							AllowPrivilegeEscalation: new(false),
							Capabilities: &corev1.Capabilities{
								Drop: []corev1.Capability{
									"ALL",
								},
							},
						},
						Ports: []corev1.ContainerPort{{
							ContainerPort: 11211,
							Name:          memcachedContainerName,
						}},
						Command: []string{"memcached", "--memory-limit=64", "-o", "modern", "-v"},
					}},
				},
			},
		},
	}

	// 设置 Deployment 的 ownerRef
	// 更多信息： https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/
	if err := ctrl.SetControllerReference(memcached, dep, r.Scheme); err != nil {
		return nil, err
	}
	return dep, nil
}

深入控制器实现

配置 Manager 监视资源

整个想法是关注对控制器重要的资源。当控制器感兴趣的资源发生变化时，Watch 会触发控制器的对账循环，确保资源的实际状态与控制器逻辑中定义的期望状态相匹配。

注意如何配置 Manager，以监视 Memcached Kind 自定义资源（CR）的创建、更新或删除，以及控制器所管理并拥有的 Deployment 的任何变更：

// SetupWithManager 将控制器与管理器设置起来。
// 部署也会被监视以确保其
// 在集群中的期望状态。
func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
		// 监视 Memcached 自定义资源，并在其
		//创建、更新或删除时触发协调
		For(&cachev1alpha1.Memcached{}).
		// 监视由 Memcached 控制器管理的 Deployment。若 Deployment 发生任何变更
        // owned and managed by this controller, it triggers reconciliation, ensuring that the cluster
        // state aligns with the desired state.
		Owns(&appsv1.Deployment{}).
		Complete(r)
    }

但是，Manager 如何知道哪些资源归它所有？

控制器不应监视集群上任意 Deployment 并触发协调循环，而应仅在运行 Memcached 实例的特定 Deployment 发生变化时触发。例如，若有人误删 Deployment 或更改副本数，应触发协调以恢复期望状态。

Manager 知道应观察哪个 Deployment，是因为设置了 ownerRef（所有者引用）：

if err := ctrl.SetControllerReference(memcached, dep, r.Scheme); err != nil {
    return nil, err
}

授予权限

务必确保控制器对其管理的资源具备必要权限（例如 create、get、update、list）。

通过 RBAC 标记 配置 RBAC 权限，controller-gen 据此生成并更新 config/rbac/ 中的清单。可在各控制器的 Reconcile() 方法上找到（并应定义）这些标记，参见示例实现：

// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/finalizers,verbs=update
// +kubebuilder:rbac:groups=events.k8s.io,resources=events,verbs=create;patch
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=core,resources=pods,verbs=get;list;watch

修改控制器后，运行 make manifests。这将让 controller-gen 刷新 config/rbac 下的文件。

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: manager-role
rules:
- apiGroups:
  - ""
  resources:
  - pods
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - apps
  resources:
  - deployments
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - cache.example.com
  resources:
  - memcacheds
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - cache.example.com
  resources:
  - memcacheds/finalizers
  verbs:
  - update
- apiGroups:
  - cache.example.com
  resources:
  - memcacheds/status
  verbs:
  - get
  - patch
  - update
- apiGroups:
  - events.k8s.io
  resources:
  - events
  verbs:
  - create
  - patch

监控程序 (main.go)

cmd/main.go 文件中的 Manager 负责管理您应用程序中的控制器。

/*
Copyright 2026 The Kubernetes authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

package main

import (
	"crypto/tls"
	"flag"
	"os"

	// 导入所有 Kubernetes 客户端身份验证插件（例如 Azure、GCP、OIDC 等）
	// 确保 exec-entrypoint 和 run 可以使用它们。
	_ "k8s.io/client-go/plugin/pkg/client/auth"

	"k8s.io/apimachinery/pkg/runtime"
	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
	clientgoscheme "k8s.io/client-go/kubernetes/scheme"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/healthz"
	"sigs.k8s.io/controller-runtime/pkg/log/zap"
	"sigs.k8s.io/controller-runtime/pkg/metrics/filters"
	metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
	"sigs.k8s.io/controller-runtime/pkg/webhook"

	cachev1alpha1 "example.com/memcached/api/v1alpha1"
	"example.com/memcached/internal/controller"
	// +kubebuilder:scaffold:imports
)

var (
	scheme   = runtime.NewScheme()
	setupLog = ctrl.Log.WithName("setup")
)

func init() {
	utilruntime.Must(clientgoscheme.AddToScheme(scheme))

	utilruntime.Must(cachev1alpha1.AddToScheme(scheme))
	// +kubebuilder:scaffold:scheme
}

// nolint:gocyclo
func main() {
	var metricsAddr string
	var metricsCertPath, metricsCertName, metricsCertKey string
	var webhookCertPath, webhookCertName, webhookCertKey string
	var webhookPort int
	var enableLeaderElection bool
	var probeAddr string
	var secureMetrics bool
	var enableHTTP2 bool
	var tlsOpts []func(*tls.Config)
	flag.StringVar(&metricsAddr, "metrics-bind-address", "0", "The address the metrics endpoint binds to. "+
		"使用 :8443 进行 HTTPS，使用 :8080 进行 HTTP，或者保持为 0 以禁用指标服务。")
	flag.StringVar(&probeAddr, "health-probe-bind-address", ":8081", "The address the probe endpoint binds to.")
	flag.BoolVar(&enableLeaderElection, "leader-elect", false,
		"Enable leader election for controller manager. "+
			"启用此功能将确保只有一个活动的控制管理器。")
	flag.BoolVar(&secureMetrics, "metrics-secure", true,
		"如果设置，指标端点将通过 HTTPS 安全提供。请使用 --metrics-secure=false 以改为使用 HTTP。")
	flag.StringVar(&webhookCertPath, "webhook-cert-path", "", "The directory that contains the webhook certificate.")
	flag.StringVar(&webhookCertName, "webhook-cert-name", "tls.crt", "The name of the webhook certificate file.")
	flag.StringVar(&webhookCertKey, "webhook-cert-key", "tls.key", "The name of the webhook key file.")
	flag.IntVar(&webhookPort, "webhook-port", 9443, "Port the webhook server listens on. "+
		"Defaults to 9443. Set -1 to disable the webhook server.")
	flag.StringVar(&metricsCertPath, "metrics-cert-path", "",
		"The directory that contains the metrics server certificate.")
	flag.StringVar(&metricsCertName, "metrics-cert-name", "tls.crt", "The name of the metrics server certificate file.")
	flag.StringVar(&metricsCertKey, "metrics-cert-key", "tls.key", "The name of the metrics server key file.")
	flag.BoolVar(&enableHTTP2, "enable-http2", false,
		"If set, HTTP/2 will be enabled for the metrics and webhook servers")
	opts := zap.Options{
		Development: true,
	}
	opts.BindFlags(flag.CommandLine)
	flag.Parse()

	ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts)))

	// 如果 enable-http2 标志为 false（默认值），则应禁用 http/2
	// 由于其存在的漏洞。更具体地说，禁用 http/2 将
	// 防止受到 HTTP/2 流取消和
	// 快速重置 CVE 的漏洞影响。有关更多信息，请参见：
	// - https://github.com/advisories/GHSA-qppj-fm5r-hxr3
	// - https://github.com/advisories/GHSA-4374-p667-p6c8
	disableHTTP2 := func(c *tls.Config) {
		setupLog.Info("Disabling HTTP/2")
		c.NextProtos = []string{"http/1.1"}
	}

	if !enableHTTP2 {
		tlsOpts = append(tlsOpts, disableHTTP2)
	}

	// 初始Webhook TLS选项
	webhookTLSOpts := tlsOpts
	webhookServerOptions := webhook.Options{
		TLSOpts: webhookTLSOpts,
		Port:    webhookPort,
	}

	if len(webhookCertPath) > 0 {
		setupLog.Info("使用提供的证书初始化 Webhook 证书监视器",
			"webhook-cert-path", webhookCertPath, "webhook-cert-name", webhookCertName, "webhook-cert-key", webhookCertKey)

		webhookServerOptions.CertDir = webhookCertPath
		webhookServerOptions.CertName = webhookCertName
		webhookServerOptions.KeyName = webhookCertKey
	}

	webhookServer := webhook.NewServer(webhookServerOptions)

	// Metrics 端点已在 'config/default/kustomization.yaml'. Metrics 选项用于配置服务器。
	// 更多信息：
	// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.25.0/pkg/metrics/server
	// - https://book.kubebuilder.io/reference/metrics.html
	metricsServerOptions := metricsserver.Options{
		BindAddress:   metricsAddr,
		SecureServing: secureMetrics,
		TLSOpts:       tlsOpts,
	}

	if secureMetrics {
		// FilterProvider 用于通过认证/鉴权保护 metrics 端点。
		// These configurations ensure that only authorized users and service accounts
		// can access the metrics endpoint. The RBAC are configured in 'config/rbac/kustomization.yaml'. More info:
		// https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.25.0/pkg/metrics/filters#WithAuthenticationAndAuthorization
		metricsServerOptions.FilterProvider = filters.WithAuthenticationAndAuthorization
	}

	// 如果未指定证书，controller-runtime 将自动
	// 为指标服务器生成自签名证书。虽然对于开发和测试来说很方便，
	// 但这种设置不建议用于生产环境。
	//
	// TODO(用户)：如果您启用 certManager，请取消注释以下行：
	// - [METRICS-WITH-CERTS] 在 config/default/kustomization.yaml 中生成并使用
	// 由 cert-manager 管理的指标服务器证书。
	// - [PROMETHEUS-WITH-CERTS] 在 config/prometheus/kustomization.yaml 中用于 TLS 认证。
	if len(metricsCertPath) > 0 {
		setupLog.Info("使用提供的证书初始化指标证书监视器",
			"metrics-cert-path", metricsCertPath, "metrics-cert-name", metricsCertName, "metrics-cert-key", metricsCertKey)

		metricsServerOptions.CertDir = metricsCertPath
		metricsServerOptions.CertName = metricsCertName
		metricsServerOptions.KeyName = metricsCertKey
	}

	mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
		Scheme:                 scheme,
		Metrics:                metricsServerOptions,
		WebhookServer:          webhookServer,
		HealthProbeBindAddress: probeAddr,
		LeaderElection:         enableLeaderElection,
		LeaderElectionID:       "4b13cc52.example.com",
		// LeaderElectionReleaseOnCancel 定义了当管理器结束时，领导者是否应自愿辞职
		// 当管理器停止时，这要求二进制文件立即结束，否则这个设置是不安全的。设置这个可以显著
		// 加快自愿领导者的过渡，因为新的领导者不必首先等待
		// LeaseDuration 时间。
		//
		// 在提供的默认脚手架中，程序会在
		// 管理器停止后立即结束，因此启用此选项是可以的。不过，
		// 如果您正在进行或打算在管理器停止后执行任何操作，如执行清理，
		// 那么使用它可能是不安全的。
		// LeaderElectionReleaseOnCancel: true,
	})
	if err != nil {
		setupLog.Error(err, "Failed to start manager")
		os.Exit(1)
	}

	if err := (&controller.MemcachedReconciler{
		Client: mgr.GetClient(),
		Scheme: mgr.GetScheme(),
	}).SetupWithManager(mgr); err != nil {
		setupLog.Error(err, "Failed to create controller", "controller", "memcached")
		os.Exit(1)
	}
	// +kubebuilder:scaffold:builder

	if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
		setupLog.Error(err, "Failed to set up health check")
		os.Exit(1)
	}
	if err := mgr.AddReadyzCheck("readyz", healthz.Ping); err != nil {
		setupLog.Error(err, "Failed to set up ready check")
		os.Exit(1)
	}

	setupLog.Info("Starting manager")
	if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
		setupLog.Error(err, "Failed to run manager")
		os.Exit(1)
	}
}

使用 Kubebuilder 插件脚手架附加选项

在更好理解如何创建自有 API 与控制器后，让我们在本项目中脚手架插件 autoupdate.kubebuilder.io/v1-alpha，以便项目能跟进最新 Kubebuilder 发行版的脚手架变更，从而采用生态中的改进。

kubebuilder edit --plugins="autoupdate/v1-alpha"

查看 .github/workflows/auto-update.yml 文件以了解其工作方式。

检查集群中运行的项目

此时，您可以通过查看快速入门中定义的步骤来检查在集群上验证项目的步骤，请参见：在集群上运行。

后续步骤

• 若要更深入地开发解决方案，可继续阅读 CronJob 教程
• 有关优化您方法的见解，请参阅最佳实践文档。

教程：构建 CronJob

太多教程开始时使用一些非常生硬的设置，或者是一些简单应用来讲解基础知识，然后在更复杂的内容上停滞不前。相反，本教程将带您几乎体验 Kubebuilder 的全部复杂性，从简单开始，逐渐构建到一个功能齐全的应用。

假设（是的，这有点牵强）你终于厌倦了维护 Kubernetes 中非 Kubebuilder 实现的 CronJob 控制器的负担，并希望用 Kubebuilder 重写它。

CronJob 控制器的工作（并不是双关）是在 Kubernetes 集群中定期运行一次性任务。它是通过在 Job 控制器之上构建来实现这一目标的，Job 控制器的任务是一次性运行任务，并确保其完成。

不必同时重写 Job 控制器，把这当作学习如何与外部类型交互的机会。

搭建我们的项目

正如在快速入门中所述，我们需要搭建一个新的项目。请确保您已安装 Kubebuilder，然后搭建一个新项目：

# 创建一个项目目录，然后运行初始化命令。
mkdir project
cd project
# 本示例使用域名 tutorial.kubebuilder.io，
# so all API groups is <group>.tutorial.kubebuilder.io.
kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project

现在项目已经就绪，来看看 Kubebuilder 目前脚手架了哪些内容……

一个基本项目都包含了什么？

在搭建新项目时，Kubebuilder 为我们提供了一些基本的模板代码。

构建基础设施

首先，构建项目所需的基本基础设施：

module tutorial.kubebuilder.io/project

go 1.26.0

require (
	github.com/onsi/ginkgo/v2 v2.27.4
	github.com/onsi/gomega v1.39.0
	github.com/robfig/cron v1.2.0
	k8s.io/api v0.37.0
	k8s.io/apimachinery v0.37.0
	k8s.io/client-go v0.37.0
	sigs.k8s.io/controller-runtime v0.25.0
)

require (
	cel.dev/expr v0.25.1 // indirect
	github.com/Masterminds/semver/v3 v3.4.0 // indirect
	github.com/antlr4-go/antlr/v4 v4.13.1 // indirect
	github.com/beorn7/perks v1.0.1 // indirect
	github.com/blang/semver/v4 v4.0.0 // indirect
	github.com/cenkalti/backoff/v5 v5.0.3 // indirect
	github.com/cespare/xxhash/v2 v2.3.0 // indirect
	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
	github.com/emicklei/go-restful/v3 v3.13.0 // indirect
	github.com/evanphx/json-patch/v5 v5.9.11 // indirect
	github.com/felixge/httpsnoop v1.0.4 // indirect
	github.com/fsnotify/fsnotify v1.9.0 // indirect
	github.com/fxamacker/cbor/v2 v2.9.1 // indirect
	github.com/go-logr/logr v1.4.3 // indirect
	github.com/go-logr/stdr v1.2.2 // indirect
	github.com/go-logr/zapr v1.3.0 // indirect
	github.com/go-openapi/jsonpointer v1.0.0 // indirect
	github.com/go-openapi/jsonreference v1.0.0 // indirect
	github.com/go-openapi/swag v0.27.1 // indirect
	github.com/go-openapi/swag/cmdutils v0.27.1 // indirect
	github.com/go-openapi/swag/conv v0.27.1 // indirect
	github.com/go-openapi/swag/fileutils v0.27.1 // indirect
	github.com/go-openapi/swag/jsonutils v0.27.1 // indirect
	github.com/go-openapi/swag/loading v0.27.1 // indirect
	github.com/go-openapi/swag/mangling v0.27.1 // indirect
	github.com/go-openapi/swag/netutils v0.27.1 // indirect
	github.com/go-openapi/swag/pools v0.27.1 // indirect
	github.com/go-openapi/swag/stringutils v0.27.1 // indirect
	github.com/go-openapi/swag/typeutils v0.27.1 // indirect
	github.com/go-openapi/swag/yamlutils v0.27.1 // indirect
	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
	github.com/google/cel-go v0.29.2 // indirect
	github.com/google/gnostic-models v0.7.0 // indirect
	github.com/google/go-cmp v0.7.0 // indirect
	github.com/google/pprof v0.0.0-20250403155104-27863c87afa6 // indirect
	github.com/google/uuid v1.6.0 // indirect
	github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0 // indirect
	github.com/inconshreveable/mousetrap v1.1.0 // indirect
	github.com/json-iterator/go v1.1.12 // indirect
	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
	github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
	github.com/prometheus/client_golang v1.24.0 // indirect
	github.com/prometheus/client_model v0.6.2 // indirect
	github.com/prometheus/common v0.70.0 // indirect
	github.com/prometheus/procfs v0.21.1 // indirect
	github.com/spf13/cobra v1.10.2 // indirect
	github.com/spf13/pflag v1.0.10 // indirect
	github.com/x448/float16 v0.8.4 // indirect
	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 // indirect
	go.opentelemetry.io/otel v1.44.0 // indirect
	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.44.0 // indirect
	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.44.0 // indirect
	go.opentelemetry.io/otel/metric v1.44.0 // indirect
	go.opentelemetry.io/otel/sdk v1.44.0 // indirect
	go.opentelemetry.io/otel/trace v1.44.0 // indirect
	go.opentelemetry.io/proto/otlp v1.10.0 // indirect
	go.uber.org/multierr v1.11.0 // indirect
	go.uber.org/zap v1.27.1 // indirect
	go.yaml.in/yaml/v2 v2.4.4 // indirect
	go.yaml.in/yaml/v3 v3.0.4 // indirect
	golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f // indirect
	golang.org/x/mod v0.37.0 // indirect
	golang.org/x/net v0.57.0 // indirect
	golang.org/x/oauth2 v0.36.0 // indirect
	golang.org/x/sync v0.22.0 // indirect
	golang.org/x/sys v0.47.0 // indirect
	golang.org/x/term v0.45.0 // indirect
	golang.org/x/text v0.40.0 // indirect
	golang.org/x/time v0.15.0 // indirect
	golang.org/x/tools v0.47.0 // indirect
	gomodules.xyz/jsonpatch/v2 v2.4.0 // indirect
	google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa // indirect
	google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa // indirect
	google.golang.org/grpc v1.82.1 // indirect
	google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af // indirect
	gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
	gopkg.in/inf.v0 v0.9.1 // indirect
	k8s.io/apiextensions-apiserver v0.37.0 // indirect
	k8s.io/apiserver v0.37.0 // indirect
	k8s.io/component-base v0.37.0 // indirect
	k8s.io/klog/v2 v2.140.0 // indirect
	k8s.io/kube-openapi v0.0.0-20260721132016-d427ff9ee9ad // indirect
	k8s.io/streaming v0.37.0 // indirect
	k8s.io/utils v0.0.0-20260626114624-be93311217bd // indirect
	sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.36.0 // indirect
	sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect
	sigs.k8s.io/randfill v1.0.0 // indirect
	sigs.k8s.io/structured-merge-diff/v6 v6.4.2 // indirect
	sigs.k8s.io/yaml v1.6.0 // indirect
)

# 用于所有构建/推送镜像目标的镜像 URL
IMG ?= controller:latest
# YEAR 定义用于替换样板文件头中 YEAR 占位符的年份值。
YEAR ?= $(shell date +%Y)

# 获取当前使用的 Go 安装路径（在 GOPATH/bin 中，除非设置了 GOBIN）
ifeq (,$(shell go env GOBIN))
GOBIN=$(shell go env GOPATH)/bin
else
GOBIN=$(shell go env GOBIN)
endif

# CONTAINER_TOOL 定义用于构建镜像的容器工具。
# 请注意，目标命令仅针对默认脚手架的 Docker 进行了测试。
# 不过，您可能想换成其他工具。
# （例如 podman）
CONTAINER_TOOL ?= docker

将SHELL设置为bash允许通过配方执行bash命令。
# 选项设置为：当配方行以非零退出或管道命令失败时退出。
SHELL = /usr/bin/env bash -o pipefail
.SHELLFLAGS = -ec

.PHONY: all
all: build

##@ 通用

# help 目标按类别组织并打印所有目标及其描述
# 。类别用 '##@' 表示，
# 目标描述用 '##' 表示。awk 命令负责读取
# 本次调用包含的全部 makefile，查找形如
# xyz: ## something 的行，并美化格式化目标与帮助。然后，
# 若有 ##@ something 行，则作为类别美化打印。
# 有关终端格式化 ANSI 控制字符用法的更多信息：
# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
# 有关 awk 命令的更多信息：
# http://linuxcommand.org/lc3_adv_awk.php

.PHONY: help
help: ## 显示此帮助。
	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

##@ 开发

.PHONY: manifests
manifests: controller-gen ## 生成 WebhookConfiguration、ClusterRole 和 CustomResourceDefinition 对象。
	# 注意：默认脚手架加入了 maxDescLen=0 选项以解决该问题
	# Too long: must have at most 262144 bytes。使用 kubectl apply 创建/更新资源时会写入注解
	# 由 K8s API 创建，用于存储资源的最新版本 (kubectl.kubernetes.io/last-applied-configuration)。
	# 但该注解有大小限制；若 CRD 过大且描述很长，会导致失败。
	"$(CONTROLLER_GEN)" rbac:roleName=manager-role crd:maxDescLen=0 webhook paths="./..." output:crd:artifacts:config=config/crd/bases

.PHONY: generate
generate: controller-gen ## 生成包含 DeepCopy、DeepCopyInto 和 DeepCopyObject 方法实现的代码。
	"$(CONTROLLER_GEN)" object:headerFile="hack/boilerplate.go.txt",year=$(YEAR) paths="./..."

.PHONY: fmt
fmt: ## 对代码运行 go fmt。
	go fmt ./...

.PHONY: vet
vet: ## 对代码运行 go vet。
	go vet ./...

.PHONY: test
test: manifests generate fmt vet setup-envtest ## 运行测试。
	KUBEBUILDER_ASSETS="$(shell "$(ENVTEST)" use $(ENVTEST_K8S_VERSION) --bin-dir "$(LOCALBIN)" -p path)" go test $$(go list ./... | grep -v /e2e) -coverprofile cover.out

# TODO(user)：若要为 e2e 测试使用其他厂商工具，请修改 tests/e2e 下的设置。
# 默认设置假定已预装 Kind，并在本地构建/加载 Manager Docker 镜像。
# 为测试隔离默认禁用 kubectl kuberc；启用方式：
# - KUBECTL_KUBERC=true
# 默认安装 CertManager；跳过方式：
# - CERT_MANAGER_INSTALL_SKIP=true
KIND_CLUSTER ?= project-test-e2e

.PHONY: setup-test-e2e
setup-test-e2e: ## 若不存在则为 e2e 测试搭建 Kind 集群
	@command -v $(KIND) >/dev/null 2>&1 || { \
		echo "Kind is not installed. Please install Kind manually."; \
		exit 1; \
	}
	@case "$$($(KIND) get clusters)" in \
		*"$(KIND_CLUSTER)"*) \
			echo "Kind cluster '$(KIND_CLUSTER)' already exists. Skipping creation." ;; \
		*) \
			echo "Creating Kind cluster '$(KIND_CLUSTER)'..."; \
			$(KIND) create cluster --name $(KIND_CLUSTER) ;; \
	esac

.PHONY: test-e2e
test-e2e: setup-test-e2e manifests generate fmt vet ## 运行 e2e 测试。预期使用 Kind 的隔离环境。
	KIND=$(KIND) KIND_CLUSTER=$(KIND_CLUSTER) go test -tags=e2e ./test/e2e/ -v -ginkgo.v
	$(MAKE) cleanup-test-e2e

.PHONY: cleanup-test-e2e
cleanup-test-e2e: ## 拆除用于 e2e 测试的 Kind 集群
	@$(KIND) delete cluster --name $(KIND_CLUSTER)

.PHONY: lint
lint: golangci-lint ## 运行 golangci-lint 检查器
	"$(GOLANGCI_LINT)" run

.PHONY: lint-fix
lint-fix: golangci-lint ## 运行 golangci-lint 检查器并自动修复
	"$(GOLANGCI_LINT)" run --fix

.PHONY: lint-config
lint-config: golangci-lint ## 校验 golangci-lint 配置
	"$(GOLANGCI_LINT)" config verify

##@ 构建

.PHONY: build
build: manifests generate fmt vet ## 构建 manager 二进制文件。
	go build -o bin/manager cmd/main.go

.PHONY: run
run: manifests generate fmt vet ## 在主机上运行控制器。
	go run ./cmd/main.go

# 若要构建面向其他平台的 manager 镜像，可使用 --platform 标志。
# （例如 docker build --platform linux/arm64）。但必须为此启用 docker buildKit。
# 更多信息：https://docs.docker.com/develop/develop-images/build_enhancements/
# 覆盖 BASE_IMAGE 以从其他仓库构建，例如：
# make docker-build IMG=<img> BASE_IMAGE=docker.io/library/golang:1.26
.PHONY: docker-build
docker-build: ## 构建包含 manager 的 docker 镜像。
	$(CONTAINER_TOOL) build $(if $(BASE_IMAGE),--build-arg BASE_IMAGE=$(BASE_IMAGE)) -t ${IMG} .

.PHONY: docker-push
docker-push: ## 推送包含 manager 的 docker 镜像。
	$(CONTAINER_TOOL) push ${IMG}

# PLATFORMS 定义构建 manager 镜像的目标平台，以提供多
# 架构支持。（例如 make docker-buildx IMG=myregistry/mypoperator:0.0.1）。使用此选项需要：
# - 能够使用 docker buildx。更多信息：https://docs.docker.com/build/buildx/
# - 已启用 BuildKit。更多信息：https://docs.docker.com/develop/develop-images/build_enhancements/
# - 能够将镜像推送到仓库（即若未通过 IMG=<myregistry/image:<tag>> 设置有效值，导出将失败）
# 为充分提供兼容多平台的方案，应考虑使用此选项。
PLATFORMS ?= linux/arm64,linux/amd64,linux/s390x,linux/ppc64le
.PHONY: docker-buildx
docker-buildx: ## 为跨平台支持构建并推送 manager 的 docker 镜像
	# 复制现有 Dockerfile，向 Dockerfile.cross 插入 --platform=${BUILDPLATFORM}，并保留原始 Dockerfile
	sed -e '1 s/\(^FROM\)/FROM --platform=\$$\{BUILDPLATFORM\}/; t' -e ' 1,// s//FROM --platform=\$$\{BUILDPLATFORM\}/' Dockerfile > Dockerfile.cross
	- $(CONTAINER_TOOL) buildx create --name project-builder
	$(CONTAINER_TOOL) buildx use project-builder
	- $(CONTAINER_TOOL) buildx build --push --platform=$(PLATFORMS) $(if $(BASE_IMAGE),--build-arg BASE_IMAGE=$(BASE_IMAGE)) --tag ${IMG} -f Dockerfile.cross .
	- $(CONTAINER_TOOL) buildx rm project-builder
	rm Dockerfile.cross

.PHONY: build-installer
build-installer: manifests generate kustomize ## 生成包含 CRD 与 deployment 的合并 YAML。
	mkdir -p dist
	cd config/manager && "$(KUSTOMIZE)" edit set image controller=${IMG}
	"$(KUSTOMIZE)" build config/default > dist/install.yaml

##@ 部署

ifndef ignore-not-found
  ignore-not-found = false
endif

.PHONY: install
install: manifests kustomize ## 将 CRD 安装到 ~/.kube/config 指定的 K8s 集群。
	@out="$$( "$(KUSTOMIZE)" build config/crd 2>/dev/null || true )"; \
	if [ -n "$$out" ]; then echo "$$out" | "$(KUBECTL)" apply -f -; else echo "No CRDs to install; skipping."; fi

.PHONY: uninstall
uninstall: manifests kustomize ## 从 ~/.kube/config 指定的 K8s 集群卸载 CRD。调用时可加 ignore-not-found=true 以在删除时忽略资源未找到错误。
	@out="$$( "$(KUSTOMIZE)" build config/crd 2>/dev/null || true )"; \
	if [ -n "$$out" ]; then echo "$$out" | "$(KUBECTL)" delete --ignore-not-found=$(ignore-not-found) -f -; else echo "No CRDs to delete; skipping."; fi

.PHONY: deploy
deploy: manifests kustomize ## 将控制器部署到 ~/.kube/config 指定的 K8s 集群。
	cd config/manager && "$(KUSTOMIZE)" edit set image controller=${IMG}
	"$(KUSTOMIZE)" build config/default | "$(KUBECTL)" apply -f -

.PHONY: undeploy
undeploy: kustomize ## 从 ~/.kube/config 指定的 K8s 集群卸载控制器。调用时可加 ignore-not-found=true 以在删除时忽略资源未找到错误。
	"$(KUSTOMIZE)" build config/default | "$(KUBECTL)" delete --ignore-not-found=$(ignore-not-found) -f -

##@ 依赖

## 依赖安装位置
LOCALBIN ?= $(shell pwd)/bin
$(LOCALBIN):
	mkdir -p "$(LOCALBIN)"

## 工具二进制
KUBECTL ?= kubectl
KIND ?= kind
KUSTOMIZE ?= $(LOCALBIN)/kustomize
CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
ENVTEST ?= $(LOCALBIN)/setup-envtest
GOLANGCI_LINT = $(LOCALBIN)/golangci-lint

## 工具版本
KUSTOMIZE_VERSION ?= v5.8.1
CONTROLLER_TOOLS_VERSION ?= v0.22.0

# ENVTEST_VERSION 是 setup-envtest 使用的 controller-runtime 版本，从 go.mod 推导
ENVTEST_VERSION ?= $(shell v='$(call gomodver,sigs.k8s.io/controller-runtime)'; \
  [ -n "$$v" ] || { echo "请手动设置 ENVTEST_VERSION（controller-runtime replace 无 tag）" >&2; exit 1; }; \
  printf '%s\n' "$$v")

# ENVTEST_K8S_VERSION 是设置 ENVTEST 二进制所用的 Kubernetes 版本（例如 1.31）
ENVTEST_K8S_VERSION ?= $(shell v='$(call gomodver,k8s.io/api)'; \
  [ -n "$$v" ] || { echo "请手动设置 ENVTEST_K8S_VERSION（k8s.io/api replace 无 tag）" >&2; exit 1; }; \
  printf '%s\n' "$$v" | sed -E 's/^v?[0-9]+\.([0-9]+).*/1.\1/')

GOLANGCI_LINT_VERSION ?= v2.13.1
.PHONY: kustomize
kustomize: $(KUSTOMIZE) ## 如有必要则本地下载 kustomize。
$(KUSTOMIZE): $(LOCALBIN)
	$(call go-install-tool,$(KUSTOMIZE),sigs.k8s.io/kustomize/kustomize/v5,$(KUSTOMIZE_VERSION))

.PHONY: controller-gen
controller-gen: $(CONTROLLER_GEN) ## 如有必要则本地下载 controller-gen。
$(CONTROLLER_GEN): $(LOCALBIN)
	$(call go-install-tool,$(CONTROLLER_GEN),sigs.k8s.io/controller-tools/cmd/controller-gen,$(CONTROLLER_TOOLS_VERSION))

.PHONY: setup-envtest
setup-envtest: envtest ## 将 ENVTEST 所需二进制下载到本地 bin 目录。
	@echo "Setting up envtest binaries for Kubernetes version $(ENVTEST_K8S_VERSION)..."
	@"$(ENVTEST)" use $(ENVTEST_K8S_VERSION) --bin-dir "$(LOCALBIN)" -p path || { \
		echo "Error: Failed to set up envtest binaries for version $(ENVTEST_K8S_VERSION)."; \
		exit 1; \
	}

.PHONY: envtest
envtest: $(ENVTEST) ## 如有必要则本地下载 setup-envtest。
$(ENVTEST): $(LOCALBIN)
	$(call go-install-tool,$(ENVTEST),sigs.k8s.io/controller-runtime/tools/setup-envtest,$(ENVTEST_VERSION))

.PHONY: golangci-lint
golangci-lint: $(GOLANGCI_LINT) ## 如有必要则本地下载 golangci-lint。
$(GOLANGCI_LINT): $(LOCALBIN)
	$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/v2/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION))
	@test -f .custom-gcl.yml && { \
		echo "Building custom golangci-lint with plugins..." && \
		$(GOLANGCI_LINT) custom --destination $(LOCALBIN) --name golangci-lint-custom && \
		mv -f $(LOCALBIN)/golangci-lint-custom $(GOLANGCI_LINT); \
	} || true

# go-install-tool 将对任何包执行 'go install'，并使用自定义目标和二进制文件名称，如果该文件不存在的话。
# $1 - 目标路径和二进制文件名称
# $2 - 可安装的包 URL
# $3 - 特定版本的包
define go-install-tool
@[ -f "$(1)-$(3)" ] && [ "$$(readlink -- "$(1)" 2>/dev/null)" = "$(1)-$(3)" ] || { \
set -e; \
package=$(2)@$(3) ;\
echo "Downloading $${package}" ;\
rm -f "$(1)" ;\
GOBIN="$(LOCALBIN)" go install $${package} ;\
mv "$(LOCALBIN)/$$(basename "$(1)")" "$(1)-$(3)" ;\
} ;\
ln -sf "$$(realpath "$(1)-$(3)")" "$(1)"
endef

define gomodver
$(shell go list -m -f '{{if .Replace}}{{.Replace.Version}}{{else}}{{.Version}}{{end}}' $(1) 2>/dev/null)
endef

##@ Helm Deployment

## Helm binary to use for deploying the chart
HELM ?= helm
## Namespace to deploy the Helm release
HELM_NAMESPACE ?= project-system
## Name of the Helm release
HELM_RELEASE ?= project
## Path to the Helm chart directory
HELM_CHART_DIR ?= dist/chart
## Additional arguments to pass to helm commands
HELM_EXTRA_ARGS ?=

.PHONY: install-helm
install-helm: ## Install the latest version of Helm.
	@command -v $(HELM) >/dev/null 2>&1 || { \
		echo "Installing Helm..." && \
		curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4 | bash; \
	}

.PHONY: helm-deploy
helm-deploy: install-helm ## Deploy manager to the K8s cluster via Helm. Specify an image with IMG.
	IMG="$(IMG)"; $(HELM) upgrade --install $(HELM_RELEASE) $(HELM_CHART_DIR) \
		--namespace $(HELM_NAMESPACE) \
		--create-namespace \
		--set manager.image.repository=$${IMG%:*} \
		--set manager.image.tag=$${IMG##*:} \
		--wait \
		--timeout 5m \
		$(HELM_EXTRA_ARGS)

.PHONY: helm-uninstall
helm-uninstall: ## Uninstall the Helm release from the K8s cluster.
	$(HELM) uninstall $(HELM_RELEASE) --namespace $(HELM_NAMESPACE)

.PHONY: helm-status
helm-status: ## Show Helm release status.
	$(HELM) status $(HELM_RELEASE) --namespace $(HELM_NAMESPACE)

.PHONY: helm-history
helm-history: ## Show Helm release history.
	$(HELM) history $(HELM_RELEASE) --namespace $(HELM_NAMESPACE)

.PHONY: helm-rollback
helm-rollback: ## Rollback to previous Helm release.
	$(HELM) rollback $(HELM_RELEASE) --namespace $(HELM_NAMESPACE)

# Code generated by tool. DO NOT EDIT.
# 此文件用于跟踪脚手架项目所用的信息
# 并使插件能正常工作。
# 更多信息: https://book.kubebuilder.io/reference/project-config.html
cliVersion: (devel)
domain: tutorial.kubebuilder.io
layout:
- go.kubebuilder.io/v4
plugins:
  helm.kubebuilder.io/v2-alpha:
    manifests: dist/install.yaml
    output: dist
projectName: project
repo: 教程.kubebuilder.io/项目
resources:
- api:
    crdVersion: v1
    namespaced: true
  controller: true
  domain: tutorial.kubebuilder.io
  group: batch
  kind: CronJob
  path: tutorial.kubebuilder.io/project/api/v1
  version: v1
  webhooks:
    defaulting: true
    validation: true
    webhookVersion: v1
version: "3"

启动配置

我们还在 config/ 目录下获取启动配置。目前，它只包含启动控制器所需的 Kustomize YAML 定义，但一旦我们开始编写控制器，它还将包含我们的 CustomResourceDefinitions、自定义访问控制配置（RBAC）和 WebhookConfigurations。

config/default 包含一个 Kustomize 基础，用于以标准配置启动控制器。

每个目录包含不同的配置，这些配置被重构到它们自己的基础中：

• config/manager: 在集群中以 pod 形式启动您的控制器

• config/rbac: 运行您的控制器所需的权限，以便在它们自己的服务帐户下运行。

入口点

最后但同样重要的是，Kubebuilder 搭建了我们项目的基本入口文件：main.go。接下来我们来看看这个文件…

每段旅程都需要一个开始，每个程序都需要一个主函数。

Apache License

http://www.apache.org/licenses/LICENSE-2.0

package main

import (
	"flag"
	"os"

	// 导入所有 Kubernetes 客户端身份验证插件（例如 Azure、GCP、OIDC 等）
	// 确保 exec-entrypoint 和 run 可以使用它们。
	_ "k8s.io/client-go/plugin/pkg/client/auth"

	"k8s.io/apimachinery/pkg/runtime"
	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
	clientgoscheme "k8s.io/client-go/kubernetes/scheme"
	_ "k8s.io/client-go/plugin/pkg/client/auth/gcp"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/cache"
	"sigs.k8s.io/controller-runtime/pkg/healthz"
	"sigs.k8s.io/controller-runtime/pkg/log/zap"
	"sigs.k8s.io/controller-runtime/pkg/metrics/server"
	"sigs.k8s.io/controller-runtime/pkg/webhook"
	// +kubebuilder:scaffold:imports
)

var (
	scheme   = runtime.NewScheme()
	setupLog = ctrl.Log.WithName("setup")
)

func init() {
	utilruntime.Must(clientgoscheme.AddToScheme(scheme))

	// +kubebuilder:scaffold:scheme
}

func main() {
	var metricsAddr string
	var enableLeaderElection bool
	var probeAddr string
	flag.StringVar(&metricsAddr, "metrics-bind-address", ":8080", "The address the metric endpoint binds to.")
	flag.StringVar(&probeAddr, "health-probe-bind-address", ":8081", "The address the probe endpoint binds to.")
	flag.BoolVar(&enableLeaderElection, "leader-elect", false,
		"Enable leader election for controller manager. "+
			"启用此功能将确保只有一个活动的控制管理器。")
	opts := zap.Options{
		Development: true,
	}
	opts.BindFlags(flag.CommandLine)
	flag.Parse()

	ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts)))

	mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
		Scheme: scheme,
		Metrics: server.Options{
			BindAddress: metricsAddr,
		},
		WebhookServer:          webhook.NewServer(webhook.Options{Port: 9443}),
		HealthProbeBindAddress: probeAddr,
		LeaderElection:         enableLeaderElection,
		LeaderElectionID:       "80807133.tutorial.kubebuilder.io",
	})
	if err != nil {
		setupLog.Error(err, "unable to start manager")
		os.Exit(1)
	}

	mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
		Scheme: scheme,
		Cache: cache.Options{
			DefaultNamespaces: map[string]cache.Config{
				namespace: {},
			},
		},
		Metrics: server.Options{
			BindAddress: metricsAddr,
		},
		WebhookServer:          webhook.NewServer(webhook.Options{Port: 9443}),
		HealthProbeBindAddress: probeAddr,
		LeaderElection:         enableLeaderElection,
		LeaderElectionID:       "80807133.tutorial.kubebuilder.io",
	})

	var namespaces []string // 命名空间列表
	defaultNamespaces := make(map[string]cache.Config)

	for _, ns := range namespaces {
		defaultNamespaces[ns] = cache.Config{}
	}

	mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
		Scheme: scheme,
		Cache: cache.Options{
			DefaultNamespaces: defaultNamespaces,
		},
		Metrics: server.Options{
			BindAddress: metricsAddr,
		},
		WebhookServer:          webhook.NewServer(webhook.Options{Port: 9443}),
		HealthProbeBindAddress: probeAddr,
		LeaderElection:         enableLeaderElection,
		LeaderElectionID:       "80807133.tutorial.kubebuilder.io",
	})

	// +kubebuilder:scaffold:builder

	if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
		setupLog.Error(err, "unable to set up health check")
		os.Exit(1)
	}
	if err := mgr.AddReadyzCheck("readyz", healthz.Ping); err != nil {
		setupLog.Error(err, "unable to set up ready check")
		os.Exit(1)
	}

	setupLog.Info("starting manager")
	if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
		setupLog.Error(err, "problem running manager")
		os.Exit(1)
	}
}

解决了这个问题后，我们可以开始搭建我们的 API 了！

组、版本和种类，真是让人头大！

开始 API 之前，先谈一点术语。

讨论 Kubernetes API 时常用四个术语：groups（组）、versions（版本）、kinds（种类）和 resources（资源）。

组与版本

Kubernetes 中的 API 组 只是相关功能的集合。每个组都有一个或多个 版本，顾名思义，这些版本允许我们随着时间的推移改变 API 的工作方式。

种类与资源

每个 API 组版本包含一个或多个 API 类型，我们称之为 Kinds。虽然一个 Kind 可能在不同版本之间改变形式，但每种形式必须能够以某种方式存储其他形式的所有数据（我们可以将数据存储在字段中或注释中）。这意味着使用旧的 API 版本不会导致较新的数据丢失或损坏。有关更多信息，请参阅 Kubernetes API 指南。

您有时还会听到提到 资源。资源只是 API 中对 Kind 的一种使用。通常，Kinds 和资源之间存在一对一的映射关系。例如，pods 资源对应于 Pod Kind。然而，有时候，同一个 Kind 可能会由多个资源返回。例如，Scale Kind 会由所有缩放子资源返回，如 deployments/scale 或 replicasets/scale。这使得 Kubernetes 的 HorizontalPodAutoscaler 能够与不同的资源进行交互。然而，对于自定义资源定义（CRDs）而言，每个 Kind 将对应一个单一的资源。

请注意，资源始终使用小写字母，并且根据惯例，它们是 Kind 的小写形式。

那么，这与围棋有什么关系呢？

指称某一特定组版本中的 kind 时，称为 GroupVersionKind，简称 GVK。资源对应有 GVR。稍后可见，每个 GVK 对应包中某个根 Go 类型。

术语清楚后，真正 创建 API！

那么，如何创建 API？

在下一部分添加新的 API中，我们将检查该工具如何通过命令 kubebuilder create api 帮助我们创建自己的 API。

此命令的目标是为我们的类型创建一个自定义资源（CR）和自定义资源定义（CRD）。要进一步了解，请参见：使用自定义资源定义扩展Kubernetes API。

但是，为什么要创建API呢？

新 API 是你向 Kubernetes 介绍自定义对象的方式。Controller-gen 用 Go 结构体生成 CRD，其中包含数据 schema 以及新类型名称等跟踪信息。随后可创建由控制器管理的自定义对象实例。

API 与资源代表你在集群上的方案。简单说，CRD 是自定义对象的定义，CR 是其实例。

啊，你有例子吗？

想想经典场景：目标是在 Kubernetes 平台上运行应用及其数据库。可用一个 CRD 表示 App，另一个表示 DB。分别描述 App 与 DB 可避免破坏封装、单一职责与内聚等概念；损害这些概念可能导致难以扩展、复用或维护等副作用。

通过这种方式，我们可以创建应用程序的 CRD，它将拥有自己的控制器，负责诸如创建包含应用程序的 Deployment、创建访问该应用程序的 Service 等。类似地，我们可以创建一个 CRD 来表示数据库，并部署一个控制器来管理数据库实例。

呃，那个 Scheme 是什么？

我们之前看到的 Scheme 只是一个用来跟踪给定 GVK 对应的 Go 类型的方式（不要被它的 godocs 压倒）。

例如，假设我们将 "tutorial.kubebuilder.io/api/v1".CronJob{} 类型标记为属于 batch.tutorial.kubebuilder.io/v1 API 组（隐含地表示它的 Kind 为 CronJob）。

然后，我们可以根据API服务器提供的JSON数据，稍后构建一个新的 &CronJob{}。

{
    "kind": "CronJob",
    "apiVersion": "batch.tutorial.kubebuilder.io/v1",
    ...
}

或者在我们提交一个 &CronJob{} 的更新时，正确查找组版本。

添加一个新 API

要构建一个新的 Kind（你有注意到上一章吗？），以及相应的控制器，我们可以使用 kubebuilder create api：

kubebuilder create api --group batch --version v1 --kind CronJob

按 y 以确认\

第一次为每个组版本调用此命令时，它将为新的组版本创建一个目录。

在这种情况下，api/v1/ 目录被创建，对应于 batch.tutorial.kubebuilder.io/v1（还记得我们最开始的 --domain 设置 吗？）。

它还为我们的 CronJob 类型添加了一个文件 api/v1/cronjob_types.go。每次我们调用带有不同类型的命令时，它都会添加一个相应的新文件。

先看看开箱即得的内容，再动手填写。

Apache License

http://www.apache.org/licenses/LICENSE-2.0

package v1

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

// 请编辑本文件！这是供您拥有的脚手架代码！
// 注意：需要 json 标签。新增字段必须带有 json 标签才能被序列化。

// CronJobSpec 定义 CronJob 的期望状态
type CronJobSpec struct {
	// 插入额外的规格字段 - 集群的期望状态
	// 注意：修改此文件后，运行"make"以重新生成代码
}

// CronJobStatus 定义 CronJob 的观测状态
type CronJobStatus struct {
	// 插入额外的状态字段 - 定义集群的观察状态
	// 重要：在修改此文件后，请运行 "make" 以重新生成代码
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status

// CronJob 是 cronjobs API 的 Schema
type CronJob struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   CronJobSpec   `json:"spec,omitempty"`
	Status CronJobStatus `json:"status,omitempty"`
}

// +kubebuilder:object:root=true

// CronJobList 包含一个 CronJob 列表
type CronJobList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []CronJob `json:"items"`
}

func init() {
	SchemeBuilder.Register(&CronJob{}, &CronJobList{})
}

现在我们已经了解了基本结构，让我们来完善它吧！

设计一个 API

在 Kubernetes 中设计 API 有若干规则。即：所有序列化字段_必须_为 camelCase，因此用 JSON 结构体标签指定。也可用 omitempty 标记空值时省略序列化。

字段可以使用大部分原始类型。数字是一个例外：出于API兼容性考虑，我们接受三种数字形式：int32 和 int64 用于整数，resource.Quantity 用于小数。

我们使用的另一种特殊类型是 metav1.Time。它的功能与 time.Time 相同，但具有固定的可移植序列化格式。

在处理完这些之后，我们来看看我们的 CronJob 对象是什么样的！

Apache License

http://www.apache.org/licenses/LICENSE-2.0

package v1

Imports

import (
	batchv1 "k8s.io/api/batch/v1"
	corev1 "k8s.io/api/core/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime"
)

// 请编辑本文件！这是供您拥有的脚手架代码！
// 注意：需要 json 标签。新增字段必须带有 json 标签才能被序列化。

// CronJobSpec 定义 CronJob 的期望状态
type CronJobSpec struct {
	// Cron 格式的调度表达式，参见 https://en.wikipedia.org/wiki/Cron.
	// +kubebuilder:validation:MinLength=0
	// +required
	Schedule string `json:"schedule"`

	// startingDeadlineSeconds 定义若错过计划时间则启动 Job 的秒数截止
	// time for any reason.  Missed jobs executions will be counted as failed ones.
	// +optional
	// +kubebuilder:validation:Minimum=0
	StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`

	// concurrencyPolicy 指定如何处理 Job 的并发执行。
	// 有效值为：
	// - "Allow"（默认）：允许 CronJob 并发运行；
	// - "Forbid"：禁止并发，若上次运行未结束则跳过下次；
	// - "Replace"：取消当前运行的 Job 并用新 Job 替换
	// +optional
	// +kubebuilder:default:=Allow
	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`

	// suspend 告诉控制器暂停后续执行，它
	// 不适用于已开始的执行。默认为 false。
	// +optional
	Suspend *bool `json:"suspend,omitempty"`

	// jobTemplate 定义执行 CronJob 时将创建的 Job。
	// +required
	JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`

	// successfulJobsHistoryLimit 定义要保留的成功完成 Job 数量。
	// 使用指针以区分显式零值与未指定。
	// +optional
	// +kubebuilder:validation:Minimum=0
	SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`

	// failedJobsHistoryLimit 定义要保留的失败完成 Job 数量。
	// 使用指针以区分显式零值与未指定。
	// +optional
	// +kubebuilder:validation:Minimum=0
	FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
}

// ConcurrencyPolicy 描述如何处理 Job。
// 下列并发策略只能指定其一。
// 若未指定下列任一策略，则默认
// 为 AllowConcurrent。
// +kubebuilder:validation:Enum=Allow;Forbid;Replace
type ConcurrencyPolicy string

const (
	// AllowConcurrent 允许 CronJob 并发运行。
	AllowConcurrent ConcurrencyPolicy = "Allow"

	// ForbidConcurrent 禁止并发运行；若上次
	// 尚未结束则跳过下次运行。
	ForbidConcurrent ConcurrencyPolicy = "Forbid"

	// ReplaceConcurrent 取消当前运行的 Job 并用新 Job 替换。
	ReplaceConcurrent ConcurrencyPolicy = "Replace"
)

// CronJobStatus 定义 CronJob 的观测状态.
type CronJobStatus struct {
	// 插入额外的状态字段 - 定义集群的观察状态
	// 重要：在修改此文件后，请运行 "make" 以重新生成代码

	// active 定义指向当前运行 Job 的指针列表。
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=10
	Active []corev1.ObjectReference `json:"active,omitempty"`

	// lastScheduleTime 定义 Job 上次成功调度的时间。
	// +optional
	LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`

	// Kubernetes API 约定参见：
	// https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties

	// conditions 表示 CronJob 资源的当前状态。
	// 每个 condition 有唯一类型，反映资源某一方面的状态。
	//
	// Standard condition types include:
	// - "Available": the resource is fully functional
	// - "Progressing": the resource is being created or updated
	// - "Degraded": the resource failed to reach or maintain its desired state
	//
	// The status of each condition is one of True, False, or Unknown.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status

// CronJob 是 cronjobs API 的 Schema
type CronJob struct {

Root Object Definitions

	metav1.TypeMeta `json:",inline"`

	// metadata 是标准对象元数据
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec 定义 CronJob 的期望状态
	// +required
	Spec CronJobSpec `json:"spec"`

	// status 定义 CronJob 的观测状态
	// +optional
	Status CronJobStatus `json:"status,omitzero"`
}

// +kubebuilder:object:root=true

// CronJobList 包含一个 CronJob 列表
type CronJobList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []CronJob `json:"items"`
}

func init() {
	SchemeBuilder.Register(func(s *runtime.Scheme) error {
		s.AddKnownTypes(SchemeGroupVersion, &CronJob{}, &CronJobList{})
		return nil
	})
}

现在我们有了一个API，我们需要编写一个控制器来实际实现该功能。

简短的插曲：这些其他东西是什么？

如果你查看了 api/v1/ 目录中的其他文件，可能会注意到除了 cronjob_types.go 之外还有两个额外的文件：groupversion_info.go 和 zz_generated.deepcopy.go。

这两个文件都不需要编辑（前者保持不变，后者是自动生成的），但了解它们的内容是很有用的。

groupversion_info.go

groupversion_info.go 包含有关组版本的常见元数据：

Apache License

http://www.apache.org/licenses/LICENSE-2.0

// Package v1 包含 batch v1 API 组的 API Schema 定义。
// +kubebuilder:object:generate=true
// +groupName=batch.tutorial.kubebuilder.io
package v1

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

var (
	// SchemeGroupVersion 是用于注册这些对象的组版本。
	// This name is used by applyconfiguration generators (e.g. controller-gen).
	SchemeGroupVersion = schema.GroupVersion{Group: "batch.tutorial.kubebuilder.io", Version: "v1"}

	// GroupVersion 是 SchemeGroupVersion 的别名，用于向后兼容。
	GroupVersion = SchemeGroupVersion

	// SchemeBuilder 用于将 go 类型添加到 GroupVersionKind scheme。
	SchemeBuilder = runtime.NewSchemeBuilder(func(scheme *runtime.Scheme) error {
		metav1.AddToGroupVersion(scheme, SchemeGroupVersion)
		return nil
	})

	// AddToScheme 将该组版本中的类型添加到给定 scheme。
	AddToScheme = SchemeBuilder.AddToScheme
)

zz_generated.deepcopy.go

zz_generated.deepcopy.go 包含了上述 runtime.Object 接口的自动生成实现，它将我们的所有根类型标记为表示种类（Kinds）。

runtime.Object 接口的核心是一个深拷贝方法 DeepCopyObject。

controller-tools中的object生成器还为每个根类型及其所有子类型生成了两个其他实用方法：DeepCopy和DeepCopyInto。

控制器中包含什么？

控制器是Kubernetes和任何操作器的核心。

控制器的职责是确保对于任何给定的对象，实际的世界状态（包括集群状态以及可能的外部状态，例如 Kubelet 的运行容器或云服务提供商的负载均衡器）与对象中的期望状态相匹配。每个控制器专注于一个_根_ Kind，但可能与其他 Kind 进行交互。

我们称这个过程为 调整。

在 controller-runtime 中，实现特定种类的对账逻辑的部分称为 Reconciler。一个 reconciler 接收一个对象的名称，并返回是否需要重新尝试（例如，在出现错误或周期性控制器的情况下，如水平 Pod 自动缩放器）。

Apache License

http://www.apache.org/licenses/LICENSE-2.0

package controllers

import (
	"context"

	"k8s.io/apimachinery/pkg/runtime"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/client"
	logf "sigs.k8s.io/controller-runtime/pkg/log"

	batchv1 "tutorial.kubebuilder.io/project/api/v1"
)

// CronJobReconciler 协调 CronJob 对象
type CronJobReconciler struct {
	client.Client
	Scheme *runtime.Scheme
}

// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs/status,verbs=get;update;patch

make manifests

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

	// 在此编写逻辑

	return ctrl.Result{}, nil
}

func (r *CronJobReconciler) SetupWithManager(mgr ctrl.Manager) error {
	return ctrl.NewControllerManagedBy(mgr).
		For(&batchv1.CronJob{}).
		Complete(r)
}

现在我们已经看到了 reconciler 的基本结构，让我们来完善 CronJob 的逻辑。

实现控制器

我们CronJob控制器的基本逻辑是这样的：

1. 加载指定的 CronJob

2. 列出所有有效的工作，并更新状态。

3. 根据历史限制清理旧的工作记录。

4. 检查是否已挂起（若已挂起则不做其他事）

5. 获取下一个计划的运行时间

6. 如果新工作在计划时间内、未超过截止日期且未被我们的并发策略阻止，则可以运行。

7. 当我们看到一个正在运行的任务（自动完成）或是下一个定时运行的时间到时，请重新排队。

Apache License

http://www.apache.org/licenses/LICENSE-2.0

package controller

import (
	"context"
	"fmt"
	"maps"
	"slices"
	"time"

	"github.com/robfig/cron"
	kbatch "k8s.io/api/batch/v1"
	corev1 "k8s.io/api/core/v1"
	apierrors "k8s.io/apimachinery/pkg/api/errors"
	"k8s.io/apimachinery/pkg/api/meta"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime"
	ref "k8s.io/client-go/tools/reference"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/client"
	logf "sigs.k8s.io/controller-runtime/pkg/log"

	batchv1 "tutorial.kubebuilder.io/project/api/v1"
)

// CronJobReconciler 协调 CronJob 对象
type CronJobReconciler struct {
	client.Client
	Scheme *runtime.Scheme
	Clock
}

Clock Code Implementation

type realClock struct{}

func (_ realClock) Now() time.Time { return time.Now() } //nolint:staticcheck

// Clock 知道如何获取当前时间。
// 可用于在测试中伪造时间。
type Clock interface {
	Now() time.Time
}

// 管理状态条件的定义
const (
	// typeAvailableCronJob 表示 CronJob 协调的状态
	typeAvailableCronJob = "Available"
	// typeProgressingCronJob 表示 CronJob 正在协调时使用的状态
	typeProgressingCronJob = "Progressing"
	// typeDegradedCronJob 表示 CronJob 遇到错误时使用的状态
	typeDegradedCronJob = "Degraded"
)

// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs/finalizers,verbs=update
// +kubebuilder:rbac:groups=batch,resources=jobs,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=batch,resources=jobs/status,verbs=get

var (
	scheduledTimeAnnotation = "batch.tutorial.kubebuilder.io/scheduled-at"
)

// Reconcile 是主 kubernetes 协调循环的一部分，其目标是
// 使集群当前状态更接近期望状态。
// TODO(user): Modify the Reconcile function to compare the state specified by
// the CronJob object against the actual cluster state, and then
// perform operations to make the cluster state reflect the state specified by
// the user.
//
// 更多细节参见 Reconcile 及其 Result：
// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.25.0/pkg/reconcile
// nolint:gocyclo
func (r *CronJobReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	log := logf.FromContext(ctx)

	var cronJob batchv1.CronJob
	if err := r.Get(ctx, req.NamespacedName, &cronJob); err != nil {
		if apierrors.IsNotFound(err) {
			// 如果未找到自定义资源，通常意味着它已被删除或未创建
			// 这样，我们将停止调整过程
			log.Info("CronJob resource not found. Ignoring since object must be deleted")
			return ctrl.Result{}, nil
		}
		// 读取对象时出错 - 重新排队请求。
		log.Error(err, "Failed to get CronJob")
		return ctrl.Result{}, err
	}

	// 若尚未存在则初始化 status conditions
	if len(cronJob.Status.Conditions) == 0 {
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeProgressingCronJob,
			Status:  metav1.ConditionUnknown,
			Reason:  "Reconciling",
			Message: "Starting reconciliation",
		})
		if err := r.Status().Update(ctx, &cronJob); err != nil {
			log.Error(err, "Failed to update CronJob status")
			return ctrl.Result{}, err
		}

	

		if err := r.Get(ctx, req.NamespacedName, &cronJob); err != nil {
			log.Error(err, "Failed to re-fetch CronJob")
			return ctrl.Result{}, err
		}
	}

	var childJobs kbatch.JobList
	if err := r.List(ctx, &childJobs, client.InNamespace(req.Namespace), client.MatchingFields{jobOwnerKey: req.Name}); err != nil {
		log.Error(err, "unable to list child Jobs")
	

		if fetchErr := r.Get(ctx, req.NamespacedName, &cronJob); fetchErr != nil {
			log.Error(fetchErr, "Failed to re-fetch CronJob")
			return ctrl.Result{}, fetchErr
		}
		// 更新 status condition 以反映错误
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeDegradedCronJob,
			Status:  metav1.ConditionTrue,
			Reason:  "ReconciliationError",
			Message: fmt.Sprintf("Failed to list child jobs: %v", err),
		})
		if statusErr := r.Status().Update(ctx, &cronJob); statusErr != nil {
			log.Error(statusErr, "Failed to update CronJob status")
		}
		return ctrl.Result{}, err
	}

	// 查找活动 Job 列表
	var activeJobs []*kbatch.Job
	var successfulJobs []*kbatch.Job
	var failedJobs []*kbatch.Job
	var mostRecentTime *time.Time // 查找上次运行以便更新 status

isJobFinished

	isJobFinished := func(job *kbatch.Job) (bool, kbatch.JobConditionType) {
		for _, c := range job.Status.Conditions {
			if (c.Type == kbatch.JobComplete || c.Type == kbatch.JobFailed) && c.Status == corev1.ConditionTrue {
				return true, c.Type
			}
		}

		return false, ""
	}

getScheduledTimeForJob

	getScheduledTimeForJob := func(job *kbatch.Job) (*time.Time, error) {
		timeRaw := job.Annotations[scheduledTimeAnnotation]
		if len(timeRaw) == 0 {
			return nil, nil
		}

		timeParsed, err := time.Parse(time.RFC3339, timeRaw)
		if err != nil {
			return nil, err
		}
		return &timeParsed, nil
	}

	for i, job := range childJobs.Items {
		_, finishedType := isJobFinished(&job)
		switch finishedType {
		case "": // 进行中
			activeJobs = append(activeJobs, &childJobs.Items[i])
		case kbatch.JobFailed:
			failedJobs = append(failedJobs, &childJobs.Items[i])
		case kbatch.JobComplete:
			successfulJobs = append(successfulJobs, &childJobs.Items[i])
		}

		// 我们将启动时间存在注解中，以便从
		// 活动 Job 自身重建。
		scheduledTimeForJob, err := getScheduledTimeForJob(&job)
		if err != nil {
			log.Error(err, "unable to parse schedule time for child job", "job", &job)
			continue
		}
		if scheduledTimeForJob != nil {
			if mostRecentTime == nil || mostRecentTime.Before(*scheduledTimeForJob) {
				mostRecentTime = scheduledTimeForJob
			}
		}
	}

	if mostRecentTime != nil {
		cronJob.Status.LastScheduleTime = &metav1.Time{Time: *mostRecentTime}
	} else {
		cronJob.Status.LastScheduleTime = nil
	}
	cronJob.Status.Active = nil
	for _, activeJob := range activeJobs {
		jobRef, err := ref.GetReference(r.Scheme, activeJob)
		if err != nil {
			log.Error(err, "unable to make reference to active job", "job", activeJob)
			continue
		}
		cronJob.Status.Active = append(cronJob.Status.Active, *jobRef)
	}

	log.V(1).Info("job count", "active jobs", len(activeJobs), "successful jobs", len(successfulJobs), "failed jobs", len(failedJobs))

	// 检查 CronJob 是否已挂起
	isSuspended := cronJob.Spec.Suspend != nil && *cronJob.Spec.Suspend

	// 根据当前状态更新 status conditions
	if isSuspended {
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeAvailableCronJob,
			Status:  metav1.ConditionFalse,
			Reason:  "Suspended",
			Message: "CronJob is suspended",
		})
	} else if len(failedJobs) > 0 {
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeDegradedCronJob,
			Status:  metav1.ConditionTrue,
			Reason:  "JobsFailed",
			Message: fmt.Sprintf("%d job(s) have failed", len(failedJobs)),
		})
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeAvailableCronJob,
			Status:  metav1.ConditionFalse,
			Reason:  "JobsFailed",
			Message: fmt.Sprintf("%d job(s) have failed", len(failedJobs)),
		})
	} else if len(activeJobs) > 0 {
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeProgressingCronJob,
			Status:  metav1.ConditionTrue,
			Reason:  "JobsActive",
			Message: fmt.Sprintf("%d job(s) are currently active", len(activeJobs)),
		})
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeAvailableCronJob,
			Status:  metav1.ConditionTrue,
			Reason:  "JobsActive",
			Message: fmt.Sprintf("CronJob is progressing with %d active job(s)", len(activeJobs)),
		})
	} else {
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeAvailableCronJob,
			Status:  metav1.ConditionTrue,
			Reason:  "AllJobsCompleted",
			Message: "All jobs have completed successfully",
		})
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeProgressingCronJob,
			Status:  metav1.ConditionFalse,
			Reason:  "NoJobsActive",
			Message: "No jobs are currently active",
		})
	}

	if err := r.Status().Update(ctx, &cronJob); err != nil {
		log.Error(err, "unable to update CronJob status")
		return ctrl.Result{}, err
	}

	// 注意：删除为“尽力而为”——若某一个失败，
	// 不会仅为完成删除而重新入队。
	if cronJob.Spec.FailedJobsHistoryLimit != nil {
		slices.SortStableFunc(failedJobs, func(a, b *kbatch.Job) int {
			aStartTime := a.Status.StartTime
			bStartTime := b.Status.StartTime
			switch {
			case aStartTime == nil && bStartTime == nil:
				return 0
			case aStartTime == nil:
				return -1
			case bStartTime == nil:
				return 1
			case aStartTime.Before(bStartTime):
				return -1
			case bStartTime.Before(aStartTime):
				return 1
			default:
				return 0
			}
		})
		for i, job := range failedJobs {
			if int32(i) >= int32(len(failedJobs))-*cronJob.Spec.FailedJobsHistoryLimit {
				break
			}
			if err := r.Delete(ctx, job, client.PropagationPolicy(metav1.DeletePropagationBackground)); client.IgnoreNotFound(err) != nil {
				log.Error(err, "unable to delete old failed job", "job", job)
			} else {
				log.V(1).Info("deleted old failed job", "job", job)
			}
		}
	}

	if cronJob.Spec.SuccessfulJobsHistoryLimit != nil {
		slices.SortStableFunc(successfulJobs, func(a, b *kbatch.Job) int {
			aStartTime := a.Status.StartTime
			bStartTime := b.Status.StartTime
			switch {
			case aStartTime == nil && bStartTime == nil:
				return 0
			case aStartTime == nil:
				return -1
			case bStartTime == nil:
				return 1
			case aStartTime.Before(bStartTime):
				return -1
			case bStartTime.Before(aStartTime):
				return 1
			default:
				return 0
			}
		})
		for i, job := range successfulJobs {
			if int32(i) >= int32(len(successfulJobs))-*cronJob.Spec.SuccessfulJobsHistoryLimit {
				break
			}
			if err := r.Delete(ctx, job, client.PropagationPolicy(metav1.DeletePropagationBackground)); err != nil {
				log.Error(err, "unable to delete old successful job", "job", job)
			} else {
				log.V(1).Info("deleted old successful job", "job", job)
			}
		}
	}

	if cronJob.Spec.Suspend != nil && *cronJob.Spec.Suspend {
		log.V(1).Info("cronjob suspended, skipping")
		return ctrl.Result{}, nil
	}

getNextSchedule

	getNextSchedule := func(cronJob *batchv1.CronJob, now time.Time) (lastMissed time.Time, next time.Time, err error) {
		sched, err := cron.ParseStandard(cronJob.Spec.Schedule)
		if err != nil {
			return time.Time{}, time.Time{}, fmt.Errorf("unparseable schedule %q: %w", cronJob.Spec.Schedule, err)
		}

		// 为优化，略取巧地从上次观测到的运行时间开始
		// we could reconstitute this here, but there's not much point, since we've
		// just updated it.
		var earliestTime time.Time
		if cronJob.Status.LastScheduleTime != nil {
			earliestTime = cronJob.Status.LastScheduleTime.Time
		} else {
			earliestTime = cronJob.CreationTimestamp.Time
		}
		if cronJob.Spec.StartingDeadlineSeconds != nil {
			// 控制器不会在此点之下调度任何内容
			schedulingDeadline := now.Add(-time.Second * time.Duration(*cronJob.Spec.StartingDeadlineSeconds))

			if schedulingDeadline.After(earliestTime) {
				earliestTime = schedulingDeadline
			}
		}
		if earliestTime.After(now) {
			return time.Time{}, sched.Next(now), nil
		}

		starts := 0
		for t := sched.Next(earliestTime); !t.After(now); t = sched.Next(t) {
			lastMissed = t
			// 对象可能错过多次启动。例如，若
			// 控制器在周五下午 5:01 卡住，而大家都
			// gone home, and someone comes in on Tuesday AM and discovers
			// the problem and restarts the controller, then all the hourly
			// jobs, more than 80 of them for one hourly scheduledJob, should
			// all start running with no further intervention (if the scheduledJob
			// allows concurrency and late starts).
			//
			// However, if there is a bug somewhere, or incorrect clock
			// on controller's server or apiservers (for setting creationTimestamp)
			// then there could be so many missed start times (it could be off
			// by decades or more), that it would eat up all the CPU and memory
			// of this controller. In that case, we want to not try to list
			// all the missed start times.
			starts++
			if starts > 100 {
				// 无法获取最近时间则返回空切片
				return time.Time{}, time.Time{}, fmt.Errorf("Too many missed start times (> 100). Set or decrease .spec.startingDeadlineSeconds or check clock skew.") //nolint:staticcheck
			}
		}
		return lastMissed, sched.Next(now), nil
	}

	// 算出下次需要创建的时间
	// Job 的时间点（或任何错过的）。
	missedRun, nextRun, err := getNextSchedule(&cronJob, r.Now())
	if err != nil {
		log.Error(err, "unable to figure out CronJob schedule")
		if fetchErr := r.Get(ctx, req.NamespacedName, &cronJob); fetchErr != nil {
			log.Error(fetchErr, "Failed to re-fetch CronJob")
			return ctrl.Result{}, fetchErr
		}
		// 更新 status condition 以反映调度错误
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeDegradedCronJob,
			Status:  metav1.ConditionTrue,
			Reason:  "InvalidSchedule",
			Message: fmt.Sprintf("Failed to parse schedule: %v", err),
		})
		if statusErr := r.Status().Update(ctx, &cronJob); statusErr != nil {
			log.Error(statusErr, "Failed to update CronJob status")
		}
		// 在收到能修复调度的更新前不必重新入队
		// 因此不返回错误
		return ctrl.Result{}, nil
	}

	scheduledResult := ctrl.Result{RequeueAfter: nextRun.Sub(r.Now())} // 保存以便别处复用
	log = log.WithValues("now", r.Now(), "next run", nextRun)

	if missedRun.IsZero() {
		log.V(1).Info("no upcoming scheduled times, sleeping until next")
		return scheduledResult, nil
	}

	// 确保启动运行尚未过晚
	log = log.WithValues("current run", missedRun)
	tooLate := false
	if cronJob.Spec.StartingDeadlineSeconds != nil {
		tooLate = missedRun.Add(time.Duration(*cronJob.Spec.StartingDeadlineSeconds) * time.Second).Before(r.Now())
	}
	if tooLate {
		log.V(1).Info("missed starting deadline for last run, sleeping till next")
		if fetchErr := r.Get(ctx, req.NamespacedName, &cronJob); fetchErr != nil {
			log.Error(fetchErr, "Failed to re-fetch CronJob")
			return ctrl.Result{}, fetchErr
		}
		// 更新 status condition 以反映错过截止时间
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeDegradedCronJob,
			Status:  metav1.ConditionTrue,
			Reason:  "MissedSchedule",
			Message: fmt.Sprintf("Missed starting deadline for run at %v", missedRun),
		})
		if statusErr := r.Status().Update(ctx, &cronJob); statusErr != nil {
			log.Error(statusErr, "Failed to update CronJob status")
		}
		return scheduledResult, nil
	}

	// 确定如何运行此 Job——并发策略可能禁止我们
	// 同时运行多个……
	if cronJob.Spec.ConcurrencyPolicy == batchv1.ForbidConcurrent && len(activeJobs) > 0 {
		log.V(1).Info("concurrency policy blocks concurrent runs, skipping", "num active", len(activeJobs))
		return scheduledResult, nil
	}

	// ……或指示我们替换现有的……
	if cronJob.Spec.ConcurrencyPolicy == batchv1.ReplaceConcurrent {
		for _, activeJob := range activeJobs {
			// 不关心 Job 是否已删除
			if err := r.Delete(ctx, activeJob, client.PropagationPolicy(metav1.DeletePropagationBackground)); client.IgnoreNotFound(err) != nil {
				log.Error(err, "unable to delete active job", "job", activeJob)
				return ctrl.Result{}, err
			}
		}
	}

constructJobForCronJob

	constructJobForCronJob := func(cronJob *batchv1.CronJob, scheduledTime time.Time) (*kbatch.Job, error) {
		// 希望给定名义启动时间的 Job 名称确定性，避免重复创建同一 Job
		name := fmt.Sprintf("%s-%d", cronJob.Name, scheduledTime.Unix())

		job := &kbatch.Job{
			ObjectMeta: metav1.ObjectMeta{
				Labels:      make(map[string]string),
				Annotations: make(map[string]string),
				Name:        name,
				Namespace:   cronJob.Namespace,
			},
			Spec: *cronJob.Spec.JobTemplate.Spec.DeepCopy(),
		}
		maps.Copy(job.Annotations, cronJob.Spec.JobTemplate.Annotations)
		job.Annotations[scheduledTimeAnnotation] = scheduledTime.Format(time.RFC3339)
		maps.Copy(job.Labels, cronJob.Spec.JobTemplate.Labels)
		if err := ctrl.SetControllerReference(cronJob, job, r.Scheme); err != nil {
			return nil, err
		}

		return job, nil
	}

	// 实际创建 Job……
	job, err := constructJobForCronJob(&cronJob, missedRun)
	if err != nil {
		log.Error(err, "unable to construct job from template")
		// 不要立即重试；失败发生在构造 Job 时。
		// 将在下次计划运行时再次协调, and updates to the CronJob
		// can also trigger reconciliation sooner
		return scheduledResult, nil
	}

	// ...and create it on the cluster
	if err := r.Create(ctx, job); err != nil {
		log.Error(err, "unable to create Job for CronJob", "job", job)
		if fetchErr := r.Get(ctx, req.NamespacedName, &cronJob); fetchErr != nil {
			log.Error(fetchErr, "Failed to re-fetch CronJob")
			return ctrl.Result{}, fetchErr
		}
		// 更新 status condition 以反映错误
		meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
			Type:    typeDegradedCronJob,
			Status:  metav1.ConditionTrue,
			Reason:  "JobCreationFailed",
			Message: fmt.Sprintf("Failed to create job: %v", err),
		})
		if statusErr := r.Status().Update(ctx, &cronJob); statusErr != nil {
			log.Error(statusErr, "Failed to update CronJob status")
		}
		return ctrl.Result{}, err
	}

	log.V(1).Info("created Job for CronJob run", "job", job)

	if fetchErr := r.Get(ctx, req.NamespacedName, &cronJob); fetchErr != nil {
		log.Error(fetchErr, "Failed to re-fetch CronJob")
		return ctrl.Result{}, fetchErr
	}
	// Update status condition to reflect successful job creation
	meta.SetStatusCondition(&cronJob.Status.Conditions, metav1.Condition{
		Type:    typeProgressingCronJob,
		Status:  metav1.ConditionTrue,
		Reason:  "JobCreated",
		Message: fmt.Sprintf("Created job %s", job.Name),
	})
	if statusErr := r.Status().Update(ctx, &cronJob); statusErr != nil {
		log.Error(statusErr, "Failed to update CronJob status")
	}

	// we'll requeue once we see the running job, and update our status
	return scheduledResult, nil
}

var (
	jobOwnerKey = ".metadata.controller"
	apiGVStr    = batchv1.GroupVersion.String()
)

// SetupWithManager 将控制器与管理器进行设置。
func (r *CronJobReconciler) SetupWithManager(mgr ctrl.Manager) error {
	// set up a real clock, since we're not in a test
	if r.Clock == nil {
		r.Clock = realClock{}
	}

	if err := mgr.GetFieldIndexer().IndexField(context.Background(), &kbatch.Job{}, jobOwnerKey, func(rawObj client.Object) []string {
		// grab the job object, extract the owner...
		job := rawObj.(*kbatch.Job)
		owner := metav1.GetControllerOf(job)
		if owner == nil {
			return nil
		}
		// ...make sure it's a CronJob...
		if owner.APIVersion != apiGVStr || owner.Kind != "CronJob" {
			return nil
		}

		// ...and if so, return it
		return []string{owner.Name}
	}); err != nil {
		return err
	}

	return ctrl.NewControllerManagedBy(mgr).
		For(&batchv1.CronJob{}).
		Owns(&kbatch.Job{}).
		Named("cronjob").
		Complete(r)
}

那真是个难题，不过现在我们有了一个可用的控制器。接下来让我们对集群进行测试，如果没有问题，就可以部署了！

你提到过主吗？

但是首先，记得我们说过要再次回到 main.go 吗？让我们来看看有没有什么变化，以及我们需要添加的内容。

Apache License

http://www.apache.org/licenses/LICENSE-2.0

Imports

package main

import (
	"crypto/tls"
	"flag"
	"os"

	// 导入所有 Kubernetes 客户端身份验证插件（例如 Azure、GCP、OIDC 等）
	// 确保 exec-entrypoint 和 run 可以使用它们。
	_ "k8s.io/client-go/plugin/pkg/client/auth"

	"k8s.io/apimachinery/pkg/runtime"
	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
	clientgoscheme "k8s.io/client-go/kubernetes/scheme"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/healthz"
	"sigs.k8s.io/controller-runtime/pkg/log/zap"
	"sigs.k8s.io/controller-runtime/pkg/metrics/filters"
	metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
	"sigs.k8s.io/controller-runtime/pkg/webhook"

	batchv1 "tutorial.kubebuilder.io/project/api/v1"
	"tutorial.kubebuilder.io/project/internal/controller"
	webhookv1 "tutorial.kubebuilder.io/project/internal/webhook/v1"
	// +kubebuilder:scaffold:imports
)

var (
	scheme   = runtime.NewScheme()
	setupLog = ctrl.Log.WithName("setup")
)

func init() {
	utilruntime.Must(clientgoscheme.AddToScheme(scheme))

	utilruntime.Must(batchv1.AddToScheme(scheme))
	// +kubebuilder:scaffold:scheme
}

// nolint:gocyclo
func main() {

Remaining code from main.go

	var metricsAddr string
	var metricsCertPath, metricsCertName, metricsCertKey string
	var webhookCertPath, webhookCertName, webhookCertKey string
	var webhookPort int
	var enableLeaderElection bool
	var probeAddr string
	var secureMetrics bool
	var enableHTTP2 bool
	var tlsOpts []func(*tls.Config)
	flag.StringVar(&metricsAddr, "metrics-bind-address", "0", "The address the metrics endpoint binds to. "+
		"使用 :8443 进行 HTTPS，使用 :8080 进行 HTTP，或者保持为 0 以禁用指标服务。")
	flag.StringVar(&probeAddr, "health-probe-bind-address", ":8081", "The address the probe endpoint binds to.")
	flag.BoolVar(&enableLeaderElection, "leader-elect", false,
		"Enable leader election for controller manager. "+
			"启用此功能将确保只有一个活动的控制管理器。")
	flag.BoolVar(&secureMetrics, "metrics-secure", true,
		"如果设置，指标端点将通过 HTTPS 安全提供。请使用 --metrics-secure=false 以改为使用 HTTP。")
	flag.StringVar(&webhookCertPath, "webhook-cert-path", "", "The directory that contains the webhook certificate.")
	flag.StringVar(&webhookCertName, "webhook-cert-name", "tls.crt", "The name of the webhook certificate file.")
	flag.StringVar(&webhookCertKey, "webhook-cert-key", "tls.key", "The name of the webhook key file.")
	flag.IntVar(&webhookPort, "webhook-port", 9443, "Port the webhook server listens on. "+
		"Defaults to 9443. Set -1 to disable the webhook server.")
	flag.StringVar(&metricsCertPath, "metrics-cert-path", "",
		"The directory that contains the metrics server certificate.")
	flag.StringVar(&metricsCertName, "metrics-cert-name", "tls.crt", "The name of the metrics server certificate file.")
	flag.StringVar(&metricsCertKey, "metrics-cert-key", "tls.key", "The name of the metrics server key file.")
	flag.BoolVar(&enableHTTP2, "enable-http2", false,
		"If set, HTTP/2 will be enabled for the metrics and webhook servers")
	opts := zap.Options{
		Development: true,
	}
	opts.BindFlags(flag.CommandLine)
	flag.Parse()

	ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts)))

	// 如果 enable-http2 标志为 false（默认值），则应禁用 http/2
	// 由于其存在的漏洞。更具体地说，禁用 http/2 将
	// 防止受到 HTTP/2 流取消和
	// 快速重置 CVE 的漏洞影响。有关更多信息，请参见：
	// - https://github.com/advisories/GHSA-qppj-fm5r-hxr3
	// - https://github.com/advisories/GHSA-4374-p667-p6c8
	disableHTTP2 := func(c *tls.Config) {
		setupLog.Info("Disabling HTTP/2")
		c.NextProtos = []string{"http/1.1"}
	}

	if !enableHTTP2 {
		tlsOpts = append(tlsOpts, disableHTTP2)
	}

	// 初始Webhook TLS选项
	webhookTLSOpts := tlsOpts
	webhookServerOptions := webhook.Options{
		TLSOpts: webhookTLSOpts,
		Port:    webhookPort,
	}

	if len(webhookCertPath) > 0 {
		setupLog.Info("使用提供的证书初始化 Webhook 证书监视器",
			"webhook-cert-path", webhookCertPath, "webhook-cert-name", webhookCertName, "webhook-cert-key", webhookCertKey)

		webhookServerOptions.CertDir = webhookCertPath
		webhookServerOptions.CertName = webhookCertName
		webhookServerOptions.KeyName = webhookCertKey
	}

	webhookServer := webhook.NewServer(webhookServerOptions)

	// Metrics 端点已在 'config/default/kustomization.yaml'. Metrics 选项用于配置服务器。
	// 更多信息：
	// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.25.0/pkg/metrics/server
	// - https://book.kubebuilder.io/reference/metrics.html
	metricsServerOptions := metricsserver.Options{
		BindAddress:   metricsAddr,
		SecureServing: secureMetrics,
		TLSOpts:       tlsOpts,
	}

	if secureMetrics {
		// FilterProvider 用于通过认证/鉴权保护 metrics 端点。
		// These configurations ensure that only authorized users and service accounts
		// can access the metrics endpoint. The RBAC are configured in 'config/rbac/kustomization.yaml'. More info:
		// https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.25.0/pkg/metrics/filters#WithAuthenticationAndAuthorization
		metricsServerOptions.FilterProvider = filters.WithAuthenticationAndAuthorization
	}

	// 如果未指定证书，controller-runtime 将自动
	// 为指标服务器生成自签名证书。虽然对于开发和测试来说很方便，
	// 但这种设置不建议用于生产环境。
	//
	// TODO(用户)：如果您启用 certManager，请取消注释以下行：
	// - [METRICS-WITH-CERTS] 在 config/default/kustomization.yaml 中生成并使用
	// 由 cert-manager 管理的指标服务器证书。
	// - [PROMETHEUS-WITH-CERTS] 在 config/prometheus/kustomization.yaml 中用于 TLS 认证。
	if len(metricsCertPath) > 0 {
		setupLog.Info("使用提供的证书初始化指标证书监视器",
			"metrics-cert-path", metricsCertPath, "metrics-cert-name", metricsCertName, "metrics-cert-key", metricsCertKey)

		metricsServerOptions.CertDir = metricsCertPath
		metricsServerOptions.CertName = metricsCertName
		metricsServerOptions.KeyName = metricsCertKey
	}

	mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
		Scheme:                 scheme,
		Metrics:                metricsServerOptions,
		WebhookServer:          webhookServer,
		HealthProbeBindAddress: probeAddr,
		LeaderElection:         enableLeaderElection,
		LeaderElectionID:       "80807133.tutorial.kubebuilder.io",
		// LeaderElectionReleaseOnCancel 定义了当管理器结束时，领导者是否应自愿辞职
		// 当管理器停止时，这要求二进制文件立即结束，否则这个设置是不安全的。设置这个可以显著
		// 加快自愿领导者的过渡，因为新的领导者不必首先等待
		// LeaseDuration 时间。
		//
		// 在提供的默认脚手架中，程序会在
		// 管理器停止后立即结束，因此启用此选项是可以的。不过，
		// 如果您正在进行或打算在管理器停止后执行任何操作，如执行清理，
		// 那么使用它可能是不安全的。
		// LeaderElectionReleaseOnCancel: true,
	})
	if err != nil {
		setupLog.Error(err, "Failed to start manager")
		os.Exit(1)
	}

	if err := (&controller.CronJobReconciler{
		Client: mgr.GetClient(),
		Scheme: mgr.GetScheme(),
	}).SetupWithManager(mgr); err != nil {
		setupLog.Error(err, "Failed to create controller", "controller", "cronjob")
		os.Exit(1)
	}

	// nolint:goconst
	if os.Getenv("ENABLE_WEBHOOKS") != "false" {
		if err := webhookv1.SetupCronJobWebhookWithManager(mgr); err != nil {
			setupLog.Error(err, "Failed to create webhook", "webhook", "CronJob")
			os.Exit(1)
		}
	}
	// +kubebuilder:scaffold:builder

	if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
		setupLog.Error(err, "Failed to set up health check")
		os.Exit(1)
	}
	if err := mgr.AddReadyzCheck("readyz", healthz.Ping); err != nil {
		setupLog.Error(err, "Failed to set up ready check")
		os.Exit(1)
	}

	setupLog.Info("Starting manager")
	if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
		setupLog.Error(err, "Failed to run manager")
		os.Exit(1)
	}
}

_现在_我们可以实现我们的控制器。

实现默认值/验证的 Webhook

如果您想为您的 CRD 实现 admission webhooks ，您需要做的唯一一件事是实现 CustomDefaulter 和（或）CustomValidator 接口。

Kubebuilder 会为您处理其余的任务，例如：

1. 创建 webhook 服务器。
2. 确保服务器已在管理器中添加。
3. 为您的 webhooks 创建处理程序。
4. 在你的服务器中为每个处理程序注册路径。

首先，让我们为我们的自定义资源定义（CronJob）搭建 Webhook。我们需要使用 --defaulting 和 --programmatic-validation 标志运行以下命令（因为我们的测试项目将使用默认和验证 Webhook）：

kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --programmatic-validation

这将为您构建 webhook 函数，并在您的 main.go 中将 webhook 注册到管理器。

Custom webhook paths

你可以使用 --defaulting-path 和 --validation-path 标志为 Webhook 指定自定义 HTTP 路径：

# Custom path for defaulting webhook
kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --defaulting-path=/my-custom-mutate-path

# Custom path for validation webhook
kubebuilder create webhook --group batch --version v1 --kind CronJob --programmatic-validation --validation-path=/my-custom-validate-path

# Both webhooks with different custom paths
kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --programmatic-validation \
  --defaulting-path=/custom-mutate --validation-path=/custom-validate

这会更改 Webhook 标记注解中的路径，但不会更改 Webhook 文件的脚手架位置。Webhook 文件仍会创建在 internal/webhook/v1/。

Apache License

http://www.apache.org/licenses/LICENSE-2.0

Imports

package v1

import (
	"context"

	"github.com/robfig/cron"
	apierrors "k8s.io/apimachinery/pkg/api/errors"
	"k8s.io/apimachinery/pkg/runtime/schema"
	validationutils "k8s.io/apimachinery/pkg/util/validation"
	"k8s.io/apimachinery/pkg/util/validation/field"

	ctrl "sigs.k8s.io/controller-runtime"
	logf "sigs.k8s.io/controller-runtime/pkg/log"
	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"

	batchv1 "tutorial.kubebuilder.io/project/api/v1"
)

var cronjoblog = logf.Log.WithName("cronjob-resource")

// SetupCronJobWebhookWithManager registers the webhook for CronJob in the manager.
func SetupCronJobWebhookWithManager(mgr ctrl.Manager) error {
	return ctrl.NewWebhookManagedBy(mgr, &batchv1.CronJob{}).
		WithValidator(&CronJobValidator{}).
		WithDefaulter(&CronJobDefaulter{
			DefaultConcurrencyPolicy:          batchv1.AllowConcurrent,
			DefaultSuspend:                    false,
			DefaultSuccessfulJobsHistoryLimit: 3,
			DefaultFailedJobsHistoryLimit:     1,
		}).
		Complete()
}

// +kubebuilder:webhook:path=/mutate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=true,failurePolicy=fail,sideEffects=None,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=mcronjob-v1.kb.io,admissionReviewVersions=v1

// CronJobDefaulter struct is responsible for setting default values on the custom resource of the
// Kind CronJob when those are created or updated.
//
// NOTE: The +kubebuilder:object:generate=false marker prevents controller-gen from generating DeepCopy methods,
// as it is used only for temporary operations and does not need to be deeply copied.
type CronJobDefaulter struct {

	// Default values for various CronJob fields
	DefaultConcurrencyPolicy          batchv1.ConcurrencyPolicy
	DefaultSuspend                    bool
	DefaultSuccessfulJobsHistoryLimit int32
	DefaultFailedJobsHistoryLimit     int32
}

// Default implements admission.Defaulter so a webhook will be registered for the Kind CronJob.
func (d *CronJobDefaulter) Default(_ context.Context, obj *batchv1.CronJob) error {
	cronjoblog.Info("Defaulting for CronJob", "name", obj.GetName())

	// Set default values
	d.applyDefaults(obj)
	return nil
}

// applyDefaults applies default values to CronJob fields.
func (d *CronJobDefaulter) applyDefaults(cronJob *batchv1.CronJob) {
	if cronJob.Spec.ConcurrencyPolicy == "" {
		cronJob.Spec.ConcurrencyPolicy = d.DefaultConcurrencyPolicy
	}
	if cronJob.Spec.Suspend == nil {
		cronJob.Spec.Suspend = new(bool)
		*cronJob.Spec.Suspend = d.DefaultSuspend
	}
	if cronJob.Spec.SuccessfulJobsHistoryLimit == nil {
		cronJob.Spec.SuccessfulJobsHistoryLimit = new(int32)
		*cronJob.Spec.SuccessfulJobsHistoryLimit = d.DefaultSuccessfulJobsHistoryLimit
	}
	if cronJob.Spec.FailedJobsHistoryLimit == nil {
		cronJob.Spec.FailedJobsHistoryLimit = new(int32)
		*cronJob.Spec.FailedJobsHistoryLimit = d.DefaultFailedJobsHistoryLimit
	}
}

// NOTE: If you want to customise the 'path', use the flags '--defaulting-path' or '--validation-path'.
// +kubebuilder:webhook:path=/validate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=false,failurePolicy=fail,sideEffects=None,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=vcronjob-v1.kb.io,admissionReviewVersions=v1

// CronJobValidator struct is responsible for validating the CronJob resource
// when it is created, updated, or deleted.
//
// NOTE: The +kubebuilder:object:generate=false marker prevents controller-gen from generating DeepCopy methods,
// as this struct is used only for temporary operations and does not need to be deeply copied.
type CronJobValidator struct {
	// TODO(user): Add more fields as needed for validation
}

// ValidateCreate implements admission.Validator so a webhook will be registered for the type CronJob.
func (v *CronJobValidator) ValidateCreate(_ context.Context, obj *batchv1.CronJob) (admission.Warnings, error) {
	cronjoblog.Info("Validation for CronJob upon creation", "name", obj.GetName())

	return nil, validateCronJob(obj)
}

// ValidateUpdate implements admission.Validator so a webhook will be registered for the type CronJob.
func (v *CronJobValidator) ValidateUpdate(_ context.Context, oldObj, newObj *batchv1.CronJob) (admission.Warnings, error) {
	cronjoblog.Info("Validation for CronJob upon update", "name", newObj.GetName())

	return nil, validateCronJob(newObj)
}

// ValidateDelete implements admission.Validator so a webhook will be registered for the type CronJob.
func (v *CronJobValidator) ValidateDelete(_ context.Context, obj *batchv1.CronJob) (admission.Warnings, error) {
	cronjoblog.Info("Validation for CronJob upon deletion", "name", obj.GetName())

	// TODO(user): fill in your validation logic upon object deletion.

	return nil, nil
}

// validateCronJob validates the fields of a CronJob object.
func validateCronJob(cronjob *batchv1.CronJob) error {
	var allErrs field.ErrorList
	if err := validateCronJobName(cronjob); err != nil {
		allErrs = append(allErrs, err)
	}
	if err := validateCronJobSpec(cronjob); err != nil {
		allErrs = append(allErrs, err)
	}
	if len(allErrs) == 0 {
		return nil
	}

	return apierrors.NewInvalid(
		schema.GroupKind{Group: "batch.tutorial.kubebuilder.io", Kind: "CronJob"},
		cronjob.Name, allErrs)
}

func validateCronJobSpec(cronjob *batchv1.CronJob) *field.Error {
	// The field helpers from the kubernetes API machinery help us return nicely
	// structured validation errors.
	return validateScheduleFormat(
		cronjob.Spec.Schedule,
		field.NewPath("spec").Child("schedule"))
}

func validateScheduleFormat(schedule string, fldPath *field.Path) *field.Error {
	if _, err := cron.ParseStandard(schedule); err != nil {
		return field.Invalid(fldPath, schedule, err.Error())
	}
	return nil
}

validateCronJobName() Code Implementation

func validateCronJobName(cronjob *batchv1.CronJob) *field.Error {
	if len(cronjob.Name) > validationutils.DNS1035LabelMaxLength-11 {
		// The job name length is 63 characters like all Kubernetes objects
		// (which must fit in a DNS subdomain). The cronjob controller appends
		// a 11-character suffix to the cronjob (`-$TIMESTAMP`) when creating
		// a job. The job name length limit is 63 characters. Therefore cronjob
		// names must have length <= 63-11=52. If we don't validate this here,
		// then job creation will fail later.
		return field.Invalid(field.NewPath("metadata").Child("name"), cronjob.Name, "must be no more than 52 characters")
	}
	return nil
}

运行和部署控制器

Optional

如果选择对 API 定义进行任何更改，请在继续之前生成类似于 CR 或 CRD 的清单。

make manifests

为了测试控制器，我们可以在集群上本地运行它。不过，在此之前，我们需要安装我们的 CRD，按照 快速启动 的指南。这将自动使用 controller-tools 更新 YAML 清单（如果需要的话）：

make install

安装 CRD 后，针对集群运行控制器。这使用你连接集群所用的凭据，因此暂时不必担心 RBAC。

在另一个终端中运行

export ENABLE_WEBHOOKS=错误
make run

您应该看到控制器关于启动的日志，但它暂时不会执行任何操作。

此时，我们需要一个 CronJob 进行测试。让我们在 config/samples/batch_v1_cronjob.yaml 中写一个示例，并使用它：

apiVersion: batch.tutorial.kubebuilder.io/v1
kind: CronJob
metadata:
  labels:
    app.kubernetes.io/name: project
    app.kubernetes.io/managed-by: kustomize
  name: cron作业示例
spec:
  日程安排: "*/1 * * * *"
  启动截止时间（秒）: 60
  并发策略: 允许 # 显式指定，但允许也是默认值。
  工作模板:
    spec:
      template:
        spec:
          安全上下文:
            以非root用户身份运行: true
            以用户身份运行: 1000
            seccompProfile:
              type: RuntimeDefault
          容器:
          - name: 你好
            image: busybox
            args:
            - /bin/sh
            - -c
            - 日期; 在Kubernetes集群中打招呼。
            安全上下文:
              allowPrivilegeEscalation: false
              capabilities:
                drop:
                - ALL
              readOnlyRootFilesystem: false
          重启策略: 失败时
  

kubectl create -f config/samples/batch_v1_cronjob.yaml

此时，你应该会看到一阵忙碌的活动。如果你观察这些变化，你应该能看到你的定时任务在运行，并更新状态：

kubectl get cronjob.batch.tutorial.kubebuilder.io -o yaml
kubectl get job

现在我们知道它可以正常工作，我们可以在集群中运行它。停止 make run 调用，然后运行

make docker-build docker-push IMG=<some-registry>/<project-name>:tag
make deploy IMG=<some-registry>/<project-name>:tag

如果我们像之前一样再次列出定时任务，我们应该能看到控制器再次正常运行！

部署 cert-manager

使用 cert-manager 为 Webhook 服务器供应证书。只要把证书放到期望位置，其他方案也可行。

您可以按照 cert-manager 文档 来进行安装。

cert-manager 还有一个组件称为 CA Injector，它的责任是将 CA 包注入到 MutatingWebhookConfiguration / ValidatingWebhookConfiguration 中。

要实现这一点，您需要在 MutatingWebhookConfiguration / ValidatingWebhookConfiguration 对象中使用一个带有键 cert-manager.io/inject-ca-from 的注解。该注解的值应指向一个现有的 证书请求实例，格式为 <certificate-namespace>/<certificate-name>。

这是我们用于注解 MutatingWebhookConfiguration / ValidatingWebhookConfiguration 对象的 kustomize 补丁。

部署 Admission Webhook

cert-manager

按照 cert-manager 安装指南 安装 cert-manager 捆绑包。

构建你的形象

运行以下命令以在本地构建您的镜像。

make docker-build docker-push IMG=<some-registry>/<project-name>:tag

部署 Webhooks

您需要通过 kustomize 启用 webhook 和证书管理器配置。config/default/kustomization.yaml 现在应该如下所示：

Resources - 添加 webhook 与 cert-manager 资源：

# [WEBHOOK] 要启用 webhook，请取消注释所有带有 [WEBHOOK] 前缀的部分，包括在
# crd/kustomization.yaml中的那部分。
# crd/kustomization.yaml
- ../webhook
# [CERTMANAGER] 要启用 cert-manager，请取消注释所有带 'CERTMANAGER' 的部分。需要 'WEBHOOK' 组件。
- ../证书管理器

Patches - 添加 webhook manager 补丁：

# [WEBHOOK] 要启用 webhook，请取消注释所有带有 [WEBHOOK] 前缀的部分，包括在
# crd/kustomization.yaml中的那部分。
# crd/kustomization.yaml
- path: manager_webhook_patch.yaml
  目标:
    kind: 部署

Replacements - 添加 webhook 证书替换：

 - source: # 如果您有任何 webhook，请取消注释以下代码块。: 服务
     version: v1
     name: Webhook 服务
     字段路径: .metadata.name # 服务名称
   目标:
     - 选择:
         kind: 证书
         group: cert-manager.io
         version: v1
         name: 服务证书
       字段路径:
         - .spec.dnsNames.0
         - .spec.dnsNames.1
       选项:
         分隔符: '.'
         索引: 0
         create: true
 - source:
     kind: 服务
     version: v1
     name: Webhook 服务
     字段路径: .metadata.namespace # 服务的命名空间
   targets:
     - 选择:
         kind: 证书
         group: cert-manager.io
         version: v1
         name: 服务证书
       字段路径:
         - .spec.dnsNames.0
         - .spec.dnsNames.1
       选项:
         分隔符: '.'
         索引: 1
         create: true

 - source: # 如果您有一个有效的验证Webhook (--programmatic-validation)，请取消注释以下代码块
     kind: 证书
     group: cert-manager.io
     version: v1
     name: serving-cert # 此名称应与 certificate.yaml 中的名称匹配
     fieldPath: .metadata.namespace # 证书 CR 的命名空间
   目标:
     - 选择:
         kind: 有效性Webhook配置
       字段路径:
         - .metadata.annotations.[cert-manager.io/inject-ca-from]
       选项:
         分隔符: '/'
         索引: 0
         create: true
 - source:
     kind: 证书
     group: cert-manager.io
     version: v1
     name: 服务证书
     字段路径: .metadata.name
   目标:
     - 选择:
         kind: 有效性Webhook配置
       字段路径:
         - .metadata.annotations.[cert-manager.io/inject-ca-from]
       选项:
         分隔符: '/'
         索引: 1
         create: true

 - source: # 如果你有一个默认的 Webhook (--defaulting)，请取消注释以下代码块
     类型: 证书
     group: cert-manager.io
     version: v1
     name: 服务证书
     字段路径: .metadata.namespace # 证书 CR 的命名空间
   目标:
     - 选择:
         kind: 变更Webhook配置
       字段路径:
         - .metadata.annotations.[cert-manager.io/inject-ca-from]
       选项:
         分隔符: '/'
         索引: 0
         create: true
 - source:
     kind: 证书
     group: cert-manager.io
     version: v1
     name: 服务证书
     字段路径: .metadata.name
   目标:
     - 选择:
         kind: 变更Webhook配置
       字段路径:
         - .metadata.annotations.[cert-manager.io/inject-ca-from]
       选项:
         分隔符: '/'
         索引: 1
         create: true

现在 config/crd/kustomization.yaml 应该如下所示：

# This kustomization.yaml is not intended to be run by itself,
# 因为它依赖于此 kustomize 包之外的 service 名称与命名空间。
# 应由 config/default 运行
resources:
- bases/batch.tutorial.kubebuilder.io_cronjobs.yaml
# +kubebuilder:scaffold:crdkustomizeresource

贴片:
# [WEBHOOK] 要启用 Webhook，请取消注释所有带 [WEBHOOK] 前缀的部分。
# 此处的补丁用于为每个 CRD 启用转换 Webhook
# +kubebuilder:scaffold:crdkustomizewebhookpatch

# [WEBHOOK] 要启用 Webhook，请取消注释以下部分
# 以下配置用于指导 kustomize 如何对 CRD 做 kustomization。
#configurations:
#- kustomizeconfig.yaml

现在您可以通过以下方式将其部署到您的集群中：

make deploy IMG=<some-registry>/<project-name>:tag

请稍等，直到 webhook pod 启动并且证书被配置。通常在 1 分钟内完成。

现在您可以创建一个有效的 CronJob 来测试您的 webhooks。创建过程应该成功完成。

kubectl create -f config/samples/batch_v1_cronjob.yaml

您还可以尝试创建一个无效的 CronJob（例如，使用格式不正确的调度字段）。您应该会看到创建失败并出现验证错误。

编写控制器测试

测试 Kubernetes 控制器是一个大主题，而 kubebuilder 为您生成的样板测试文件相对较少。

为了引导您了解用于 Kubebuilder 生成的控制器的集成测试模式，我们将重新审视在首个教程中构建的 CronJob，并为其编写一个简单的测试。

基本的方法是，在您生成的 suite_test.go 文件中，您将使用 envtest 创建一个本地 Kubernetes API 服务器，实例化并运行您的控制器，然后编写额外的 *_test.go 文件，通过 Ginkgo 来进行测试。

如果您想要调整您的 envtest 集群的配置，请参阅为集成测试配置 envtest一节，以及envtest 文档。

测试环境设置

Apache License

http://www.apache.org/licenses/LICENSE-2.0

Imports

package controller

import (
	"context"
	"os"
	"path/filepath"
	"testing"

	ctrl "sigs.k8s.io/controller-runtime"

	. "github.com/onsi/ginkgo/v2"
	. "github.com/onsi/gomega"

	"k8s.io/client-go/kubernetes/scheme"
	"k8s.io/client-go/rest"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/envtest"
	logf "sigs.k8s.io/controller-runtime/pkg/log"
	"sigs.k8s.io/controller-runtime/pkg/log/zap"

	batchv1 "tutorial.kubebuilder.io/project/api/v1"
	// +kubebuilder:scaffold:imports
)

// These tests use Ginkgo (BDD-style Go testing framework). Refer to
// http://onsi.github.io/ginkgo/ to learn more about Ginkgo.

var (
	ctx       context.Context
	cancel    context.CancelFunc
	testEnv   *envtest.Environment
	cfg       *rest.Config
	k8sClient client.Client // You'll be using this client in your tests.
)

func TestControllers(t *testing.T) {
	RegisterFailHandler(Fail)

	RunSpecs(t, "Controller Suite")
}

var _ = BeforeSuite(func() {
	logf.SetLogger(zap.New(zap.WriteTo(GinkgoWriter), zap.UseDevMode(true)))

	ctx, cancel = context.WithCancel(context.TODO())

	var err error

	err = batchv1.AddToScheme(scheme.Scheme)
	Expect(err).NotTo(HaveOccurred())

	// +kubebuilder:scaffold:scheme

	By("bootstrapping test environment")
	testEnv = &envtest.Environment{
		CRDDirectoryPaths:     []string{filepath.Join("..", "..", "config", "crd", "bases")},
		ErrorIfCRDPathMissing: true,
	}

	// Retrieve the first found binary directory to allow running tests from IDEs
	if getFirstFoundEnvTestBinaryDir() != "" {
		testEnv.BinaryAssetsDirectory = getFirstFoundEnvTestBinaryDir()
	}

	// cfg is defined in this file globally.
	cfg, err = testEnv.Start()
	Expect(err).NotTo(HaveOccurred())
	Expect(cfg).NotTo(BeNil())

	k8sClient, err = client.New(cfg, client.Options{Scheme: scheme.Scheme})
	Expect(err).NotTo(HaveOccurred())
	Expect(k8sClient).NotTo(BeNil())

	k8sManager, err := ctrl.NewManager(cfg, ctrl.Options{
		Scheme: scheme.Scheme,
	})
	Expect(err).ToNot(HaveOccurred())

	err = (&CronJobReconciler{
		Client: k8sManager.GetClient(),
		Scheme: k8sManager.GetScheme(),
	}).SetupWithManager(k8sManager)
	Expect(err).ToNot(HaveOccurred())

	go func() {
		defer GinkgoRecover()
		err = k8sManager.Start(ctx)
		Expect(err).ToNot(HaveOccurred(), "failed to run manager")
	}()
})

var _ = AfterSuite(func() {
	By("tearing down the test environment")
	cancel()
	err := testEnv.Stop()
	Expect(err).NotTo(HaveOccurred())
})

// getFirstFoundEnvTestBinaryDir locates the first binary in the specified path.
// ENVTEST-based tests depend on specific binaries, usually located in paths set by
// controller-runtime. When running tests directly (e.g., via an IDE) without using
// Makefile targets, the 'BinaryAssetsDirectory' must be explicitly configured.
//
// This function streamlines the process by finding the required binaries, similar to
// setting the 'KUBEBUILDER_ASSETS' environment variable. To ensure the binaries are
// properly set up, run 'make setup-envtest' beforehand.
func getFirstFoundEnvTestBinaryDir() string {
	basePath := filepath.Join("..", "..", "bin", "k8s")
	entries, err := os.ReadDir(basePath)
	if err != nil {
		logf.Log.Error(err, "Failed to read directory", "path", basePath)
		return ""
	}
	for _, entry := range entries {
		if entry.IsDir() {
			return filepath.Join(basePath, entry.Name())
		}
	}
	return ""
}

测试您的控制器行为

Apache License

http://www.apache.org/licenses/LICENSE-2.0

Imports

package controller

import (
	"context"
	"reflect"
	"time"

	. "github.com/onsi/ginkgo/v2"
	. "github.com/onsi/gomega"
	batchv1 "k8s.io/api/batch/v1"
	v1 "k8s.io/api/core/v1"
	"k8s.io/apimachinery/pkg/api/errors"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/types"

	cronjobv1 "tutorial.kubebuilder.io/project/api/v1"
)

var _ = Describe("CronJob controller", func() {
	Context("CronJob controller test", func() {

		const (
			CronjobName        = "test-cronjob"
			testContainerName  = "test-container"
			testContainerImage = "test-image"
		)

		ctx := context.Background()

		namespace := &v1.Namespace{
			ObjectMeta: metav1.ObjectMeta{
				Name:      CronjobName,
				Namespace: CronjobName,
			},
		}

		typeNamespacedName := types.NamespacedName{
			Name:      CronjobName,
			Namespace: CronjobName,
		}
		cronJob := &cronjobv1.CronJob{}

		SetDefaultEventuallyTimeout(2 * time.Minute)
		SetDefaultEventuallyPollingInterval(time.Second)

		BeforeEach(func() {
			By("Creating the Namespace to perform the tests")
			err := k8sClient.Get(ctx, types.NamespacedName{Name: CronjobName}, &v1.Namespace{})
			if err != nil && errors.IsNotFound(err) {
				err = k8sClient.Create(ctx, namespace)
				Expect(err).NotTo(HaveOccurred())
			}

			By("creating the custom resource for the Kind CronJob")
			cronJob = &cronjobv1.CronJob{}
			err = k8sClient.Get(ctx, typeNamespacedName, cronJob)
			if err != nil && errors.IsNotFound(err) {
			

				cronJob = &cronjobv1.CronJob{
					ObjectMeta: metav1.ObjectMeta{
						Name:      CronjobName,
						Namespace: namespace.Name,
					},
					Spec: cronjobv1.CronJobSpec{
						Schedule: "1 * * * *",
						JobTemplate: batchv1.JobTemplateSpec{
							Spec: batchv1.JobSpec{
								Template: v1.PodTemplateSpec{
									Spec: v1.PodSpec{
										Containers: []v1.Container{
											{
												Name:  testContainerName,
												Image: testContainerImage,
											},
										},
										RestartPolicy: v1.RestartPolicyOnFailure,
									},
								},
							},
						},
					},
				}

				err = k8sClient.Create(ctx, cronJob)
				Expect(err).NotTo(HaveOccurred())
			}
		})

	

		AfterEach(func() {
			By("removing the custom resource for the Kind CronJob")
			found := &cronjobv1.CronJob{}
			err := k8sClient.Get(ctx, typeNamespacedName, found)
			Expect(err).NotTo(HaveOccurred())

			Eventually(func(g Gomega) {
				g.Expect(k8sClient.Delete(context.TODO(), found)).To(Succeed())
			}).Should(Succeed())

			// TODO(user): Attention if you improve this code by adding other context test you MUST
			// be aware of the current delete namespace limitations.
			// More info: https://book.kubebuilder.io/reference/envtest.html#testing-considerations
			By("Deleting the Namespace to perform the tests")
			_ = k8sClient.Delete(ctx, namespace)
		})

	

		It("should successfully reconcile a custom resource for CronJob", func() {
			By("Checking if the custom resource was successfully created")
			Eventually(func(g Gomega) {
				found := &cronjobv1.CronJob{}
				g.Expect(k8sClient.Get(ctx, typeNamespacedName, found)).To(Succeed())
			}).Should(Succeed())

		

			By("Checking that status conditions are initialized")
			Eventually(func(g Gomega) {
				g.Expect(k8sClient.Get(ctx, typeNamespacedName, cronJob)).To(Succeed())
				g.Expect(cronJob.Status.Conditions).NotTo(BeEmpty())
			}).Should(Succeed())

		

			By("Checking that the CronJob has zero active Jobs")
			Consistently(func(g Gomega) {
				g.Expect(k8sClient.Get(ctx, typeNamespacedName, cronJob)).To(Succeed())
				g.Expect(cronJob.Status.Active).To(BeEmpty())
			}).WithTimeout(time.Second * 10).WithPolling(time.Millisecond * 250).Should(Succeed())

		

			By("Creating a new Job owned by the CronJob")
			testJob := &batchv1.Job{
				ObjectMeta: metav1.ObjectMeta{
					Name:      "test-job",
					Namespace: namespace.Name,
				},
				Spec: batchv1.JobSpec{
					Template: v1.PodTemplateSpec{
						Spec: v1.PodSpec{
							Containers: []v1.Container{
								{
									Name:  testContainerName,
									Image: testContainerImage,
								},
							},
							RestartPolicy: v1.RestartPolicyOnFailure,
						},
					},
				},
			}

			// Note that your CronJob’s GroupVersionKind is required to set up this owner reference.
			kind := reflect.TypeFor[cronjobv1.CronJob]().Name()
			gvk := cronjobv1.GroupVersion.WithKind(kind)

			controllerRef := metav1.NewControllerRef(cronJob, gvk)
			testJob.SetOwnerReferences([]metav1.OwnerReference{*controllerRef})
			Expect(k8sClient.Create(ctx, testJob)).To(Succeed())
			// Note that you can not manage the status values while creating the resource.
			// The status field is managed separately to reflect the current state of the resource.
			// Therefore, it should be updated using a PATCH or PUT operation after the resource has been created.
			// Additionally, it is recommended to use StatusConditions to manage the status. For further information see:
			// https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status
			testJob.Status.Active = 2
			Expect(k8sClient.Status().Update(ctx, testJob)).To(Succeed())

		

			By("Checking that the CronJob has one active Job in status")
			Eventually(func(g Gomega) {
				g.Expect(k8sClient.Get(ctx, typeNamespacedName, cronJob)).To(Succeed())
				g.Expect(cronJob.Status.Active).To(HaveLen(1), "should have exactly one active job")
				g.Expect(cronJob.Status.Active[0].Name).To(Equal("test-job"), "the active job name should match")
			}).Should(Succeed())

		

			By("Checking the latest Status Condition added to the CronJob instance")
			Expect(k8sClient.Get(ctx, typeNamespacedName, cronJob)).To(Succeed())
			var conditions []metav1.Condition
			Expect(cronJob.Status.Conditions).To(ContainElement(
				HaveField("Type", Equal("Available")), &conditions))
			Expect(conditions).To(HaveLen(1), "should have one Available condition")
			Expect(conditions[0].Status).To(Equal(metav1.ConditionTrue), "Available should be True")
			Expect(conditions[0].Reason).To(Equal("JobsActive"), "reason should be JobsActive")

		

			By("Checking that old finished Jobs are pruned by history limits")
			failedJobsHistoryLimit := int32(1)
			successfulJobsHistoryLimit := int32(1)
			Eventually(func(g Gomega) {
				g.Expect(k8sClient.Get(ctx, typeNamespacedName, cronJob)).To(Succeed())
				cronJob.Spec.FailedJobsHistoryLimit = &failedJobsHistoryLimit
				cronJob.Spec.SuccessfulJobsHistoryLimit = &successfulJobsHistoryLimit
				g.Expect(k8sClient.Update(ctx, cronJob)).To(Succeed())
			}).Should(Succeed())

			createFinishedJob := func(name string, conditionType batchv1.JobConditionType, startTime *metav1.Time) *batchv1.Job {
				finishedJob := &batchv1.Job{
					ObjectMeta: metav1.ObjectMeta{
						Name:      name,
						Namespace: namespace.Name,
					},
					Spec: batchv1.JobSpec{
						Template: v1.PodTemplateSpec{
							Spec: v1.PodSpec{
								Containers: []v1.Container{
									{
										Name:  testContainerName,
										Image: testContainerImage,
									},
								},
								RestartPolicy: v1.RestartPolicyOnFailure,
							},
						},
					},
				}
				finishedJob.SetOwnerReferences([]metav1.OwnerReference{*controllerRef})
				Expect(k8sClient.Create(ctx, finishedJob)).To(Succeed())

				finishedJob.Status.StartTime = startTime
				finishedJob.Status.Conditions = []batchv1.JobCondition{{
					Type:   conditionType,
					Status: v1.ConditionTrue,
				}}
				if conditionType == batchv1.JobFailed {
					finishedJob.Status.Conditions = append([]batchv1.JobCondition{{
						Type:   batchv1.JobFailureTarget,
						Status: v1.ConditionTrue,
					}}, finishedJob.Status.Conditions...)
				}
				if conditionType == batchv1.JobComplete {
					finishedJob.Status.CompletionTime = startTime
					finishedJob.Status.Conditions = append([]batchv1.JobCondition{{
						Type:   batchv1.JobSuccessCriteriaMet,
						Status: v1.ConditionTrue,
					}}, finishedJob.Status.Conditions...)
				}
				Expect(k8sClient.Status().Update(ctx, finishedJob)).To(Succeed())

				return finishedJob
			}

			baseTime := time.Now()
			failedOldStartTime := metav1.NewTime(baseTime.Add(-time.Minute))
			failedNewStartTime := metav1.NewTime(baseTime.Add(time.Second))
			successfulOldStartTime := metav1.NewTime(baseTime.Add(-time.Minute))
			successfulNewStartTime := metav1.NewTime(baseTime.Add(time.Second))

			failedOldJob := createFinishedJob("test-failed-job-old", batchv1.JobFailed, &failedOldStartTime)
			failedNewJob := createFinishedJob("test-failed-job-new", batchv1.JobFailed, &failedNewStartTime)
			successfulOldJob := createFinishedJob("test-successful-job-old", batchv1.JobComplete, &successfulOldStartTime)
			successfulNewJob := createFinishedJob("test-successful-job-new", batchv1.JobComplete, &successfulNewStartTime)

			assertJobDeleted := func(g Gomega, job *batchv1.Job) {
				found := &batchv1.Job{}
				err := k8sClient.Get(ctx, types.NamespacedName{Name: job.Name, Namespace: job.Namespace}, found)
				g.Expect(errors.IsNotFound(err)).To(BeTrue())
			}
			assertJobExists := func(g Gomega, job *batchv1.Job) {
				found := &batchv1.Job{}
				g.Expect(k8sClient.Get(ctx, types.NamespacedName{Name: job.Name, Namespace: job.Namespace}, found)).To(Succeed())
			}

			Eventually(func(g Gomega) {
				assertJobDeleted(g, failedOldJob)
				assertJobDeleted(g, successfulOldJob)
				assertJobExists(g, failedNewJob)
				assertJobExists(g, successfulNewJob)
			}).Should(Succeed())
		})
	})
})

以上的状态更新示例展示了一种针对自定义 Kind 及其下游对象的一般测试策略。到目前为止，希望您已经学习了以下测试控制器行为的方法：

• 在 envtest 集群上设置您的控制器
• 为创建测试对象编写存根
• 将变化孤立到一个对象，以测试特定控制器的行为

教程：多版本 API

大多数项目开始时都有一个不断变化的 alpha API。然而，最终，大多数项目需要转向一个更稳定的 API。然而，一旦你的 API 稳定后，你就不能对其进行破坏性更改。这就是 API 版本派上用场的地方。

对 CronJob API spec 做一些更改，并确保 CronJob 项目支持所有不同版本。

如果您还没有，请确保您已经阅读过基础的 CronJob 教程。

接下来，让我们找出我们想要进行哪些更改…

改变现状

在Kubernetes API中，相对常见的变化是将一些以前是非结构化或以某种特殊字符串格式存储的数据，改变为结构化数据。我们的 schedule 字段恰好符合这一点 —— 目前在 v1 中，我们的计划看起来是这样的：

日程安排: "*/1 * * * *"

这是一个典型的特殊字符串格式示例（如果你不是一个 Unix 系统管理员，它也相当难以阅读）。

让它更结构化一些。根据 CronJob 代码，它支持「标准」Cron 格式。

在 Kubernetes 中，所有版本必须能安全地相互往返转换。这意味着若从版本 1 转到版本 2，再转回版本 1，不得丢失信息。因此，对 API 的任何变更都必须与 v1 所支持的内容兼容，并且要确保在 v2 添加的任何内容在 v1 中也受支持。有时这意味着需要向 v1 添加新字段，但本例不必，因为你没有添加新功能。

考虑到这些，让我们将上述示例稍微结构化一下：

日程安排:
  分钟: */1

现在，我们至少有了每个字段的标签，但我们仍然可以轻松支持每个字段的不同语法。

此变更需要新的 API 版本。称之为 v2：

kubebuilder create api --group batch --version v2 --kind CronJob

按 y 以继续\

现在，让我们复制我们现有的类型，并进行更改：

Apache License

http://www.apache.org/licenses/LICENSE-2.0

package v2

Imports

import (
	batchv1 "k8s.io/api/batch/v1"
	corev1 "k8s.io/api/core/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime"
)

// 请编辑本文件！这是供您拥有的脚手架代码！
// 注意：需要 json 标签。新增字段必须带有 json 标签才能被序列化。

// CronJobSpec 定义 CronJob 的期望状态
type CronJobSpec struct {
	// Cron 格式的调度表达式，参见 https://en.wikipedia.org/wiki/Cron.
	// +required
	Schedule CronSchedule `json:"schedule"`

CronJobSpec Full Code

	// startingDeadlineSeconds 定义若错过计划时间则启动 Job 的秒数截止
	// time for any reason.  Missed jobs executions will be counted as failed ones.
	// +optional
	// +kubebuilder:validation:Minimum=0
	StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`

	// concurrencyPolicy defines how to treat concurrent executions of a Job.
	// 有效值为：
	// - "Allow"（默认）：允许 CronJob 并发运行；
	// - "Forbid"：禁止并发，若上次运行未结束则跳过下次；
	// - "Replace"：取消当前运行的 Job 并用新 Job 替换
	// +optional
	// +kubebuilder:default:=Allow
	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`

	// suspend 告诉控制器暂停后续执行，它
	// 不适用于已开始的执行。默认为 false。
	// +optional
	Suspend *bool `json:"suspend,omitempty"`

	// jobTemplate 定义执行 CronJob 时将创建的 Job。
	// +required
	JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`

	// successfulJobsHistoryLimit 定义要保留的成功完成 Job 数量。
	// 使用指针以区分显式零值与未指定。
	// +optional
	// +kubebuilder:validation:Minimum=0
	SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`

	// failedJobsHistoryLimit 定义要保留的失败完成 Job 数量。
	// 使用指针以区分显式零值与未指定。
	// +optional
	// +kubebuilder:validation:Minimum=0
	FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
}

// describes a Cron schedule.
type CronSchedule struct {
	// minute specifies the minutes during which the job executes.
	// +optional
	Minute *CronField `json:"minute,omitempty"`
	// hour specifies the hour during which the job executes.
	// +optional
	Hour *CronField `json:"hour,omitempty"`
	// dayOfMonth specifies the day of the month during which the job executes.
	// +optional
	DayOfMonth *CronField `json:"dayOfMonth,omitempty"`
	// month specifies the month during which the job executes.
	// +optional
	Month *CronField `json:"month,omitempty"`
	// dayOfWeek specifies the day of the week during which the job executes.
	// +optional
	DayOfWeek *CronField `json:"dayOfWeek,omitempty"`
}

// represents a Cron field specifier.
type CronField string

Other Types

// ConcurrencyPolicy 描述如何处理 Job。
// 下列并发策略只能指定其一。
// 若未指定下列任一策略，则默认
// 为 AllowConcurrent。
// +kubebuilder:validation:Enum=Allow;Forbid;Replace
type ConcurrencyPolicy string

const (
	// AllowConcurrent 允许 CronJob 并发运行。
	AllowConcurrent ConcurrencyPolicy = "Allow"

	// ForbidConcurrent 禁止并发运行；若上次
	// 尚未结束则跳过下次运行。
	ForbidConcurrent ConcurrencyPolicy = "Forbid"

	// ReplaceConcurrent 取消当前运行的 Job 并用新 Job 替换。
	ReplaceConcurrent ConcurrencyPolicy = "Replace"
)

// CronJobStatus 定义 CronJob 的观测状态.
type CronJobStatus struct {
	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
	// Important: Run "make" to regenerate code after modifying this file
	// active 定义指向当前运行 Job 的指针列表。
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=10
	Active []corev1.ObjectReference `json:"active,omitempty"`

	// lastScheduleTime defines the information when was the last time the job was successfully scheduled.
	// +optional
	LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`

	// Kubernetes API 约定参见：
	// https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties

	// conditions 表示 CronJob 资源的当前状态。
	// 每个 condition 有唯一类型，反映资源某一方面的状态。
	//
	// Standard condition types include:
	// - "Available": the resource is fully functional
	// - "Progressing": the resource is being created or updated
	// - "Degraded": the resource failed to reach or maintain its desired state
	//
	// The status of each condition is one of True, False, or Unknown.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +versionName=v2
// CronJob is the Schema for the cronjobs API
type CronJob struct {
	metav1.TypeMeta `json:",inline"`

	// metadata 是标准对象元数据
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec 定义 CronJob 的期望状态
	// +required
	Spec CronJobSpec `json:"spec"`

	// status 定义 CronJob 的观测状态
	// +optional
	Status CronJobStatus `json:"status,omitzero"`
}

// +kubebuilder:object:root=true

// CronJobList 包含一个 CronJob 列表
type CronJobList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []CronJob `json:"items"`
}

func init() {
	SchemeBuilder.Register(func(s *runtime.Scheme) error {
		s.AddKnownTypes(SchemeGroupVersion, &CronJob{}, &CronJobList{})
		return nil
	})
}

存储版本

Apache License

http://www.apache.org/licenses/LICENSE-2.0

package v1

Imports

import (
	batchv1 "k8s.io/api/batch/v1"
	corev1 "k8s.io/api/core/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/apimachinery/pkg/runtime"
)

// 请编辑本文件！这是供您拥有的脚手架代码！
// 注意：需要 json 标签。新增字段必须带有 json 标签才能被序列化。

Remaining code from cronjob_types.go

// CronJobSpec 定义 CronJob 的期望状态
type CronJobSpec struct {
	// Cron 格式的调度表达式，参见 https://en.wikipedia.org/wiki/Cron.
	// +kubebuilder:validation:MinLength=0
	// +required
	Schedule string `json:"schedule"`

	// startingDeadlineSeconds 定义若错过计划时间则启动 Job 的秒数截止
	// time for any reason.  Missed jobs executions will be counted as failed ones.
	// +optional
	// +kubebuilder:validation:Minimum=0
	StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`

	// concurrencyPolicy 指定如何处理 Job 的并发执行。
	// 有效值为：
	// - "Allow"（默认）：允许 CronJob 并发运行；
	// - "Forbid"：禁止并发，若上次运行未结束则跳过下次；
	// - "Replace"：取消当前运行的 Job 并用新 Job 替换
	// +optional
	// +kubebuilder:default:=Allow
	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`

	// suspend 告诉控制器暂停后续执行，它
	// 不适用于已开始的执行。默认为 false。
	// +optional
	Suspend *bool `json:"suspend,omitempty"`

	// jobTemplate 定义执行 CronJob 时将创建的 Job。
	// +required
	JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`

	// successfulJobsHistoryLimit 定义要保留的成功完成 Job 数量。
	// 使用指针以区分显式零值与未指定。
	// +optional
	// +kubebuilder:validation:Minimum=0
	SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`

	// failedJobsHistoryLimit 定义要保留的失败完成 Job 数量。
	// 使用指针以区分显式零值与未指定。
	// +optional
	// +kubebuilder:validation:Minimum=0
	FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
}

// ConcurrencyPolicy 描述如何处理 Job。
// 下列并发策略只能指定其一。
// 若未指定下列任一策略，则默认
// 为 AllowConcurrent。
// +kubebuilder:validation:Enum=Allow;Forbid;Replace
type ConcurrencyPolicy string

const (
	// AllowConcurrent 允许 CronJob 并发运行。
	AllowConcurrent ConcurrencyPolicy = "Allow"

	// ForbidConcurrent 禁止并发运行；若上次
	// 尚未结束则跳过下次运行。
	ForbidConcurrent ConcurrencyPolicy = "Forbid"

	// ReplaceConcurrent 取消当前运行的 Job 并用新 Job 替换。
	ReplaceConcurrent ConcurrencyPolicy = "Replace"
)

// CronJobStatus 定义 CronJob 的观测状态.
type CronJobStatus struct {
	// 插入额外的状态字段 - 定义集群的观察状态
	// 重要：在修改此文件后，请运行 "make" 以重新生成代码

	// active 定义指向当前运行 Job 的指针列表。
	// +optional
	// +listType=atomic
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=10
	Active []corev1.ObjectReference `json:"active,omitempty"`

	// lastScheduleTime 定义 Job 上次成功调度的时间。
	// +optional
	LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`

	// Kubernetes API 约定参见：
	// https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties

	// conditions 表示 CronJob 资源的当前状态。
	// 每个 condition 有唯一类型，反映资源某一方面的状态。
	//
	// Standard condition types include:
	// - "Available": the resource is fully functional
	// - "Progressing": the resource is being created or updated
	// - "Degraded": the resource failed to reach or maintain its desired state
	//
	// The status of each condition is one of True, False, or Unknown.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:storageversion
// +kubebuilder:subresource:status
// +versionName=v1
// +kubebuilder:storageversion
// CronJob is the Schema for the cronjobs API
type CronJob struct {
	metav1.TypeMeta `json:",inline"`

	// metadata 是标准对象元数据
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// spec 定义 CronJob 的期望状态
	// +required
	Spec CronJobSpec `json:"spec"`

	// status 定义 CronJob 的观测状态
	// +optional
	Status CronJobStatus `json:"status,omitzero"`
}

Remaining code from cronjob_types.go

// +kubebuilder:object:root=true

// CronJobList 包含一个 CronJob 列表
type CronJobList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []CronJob `json:"items"`
}

func init() {
	SchemeBuilder.Register(func(s *runtime.Scheme) error {
		s.AddKnownTypes(SchemeGroupVersion, &CronJob{}, &CronJobList{})
		return nil
	})
}

现在我们已经确定了类型，我们需要设置转换…

中心、辐条以及其他轮子隐喻

由于我们现在有两个不同的版本，并且用户可以请求任一版本，我们需要定义一种在我们的版本之间转换的方法。对于 CRD（自定义资源定义），这可以通过 webhook 实现，类似于我们在基本教程中定义的默认和验证 webhook。和之前一样，controller-runtime 将帮助我们将这些细节连接在一起，我们只需要实现实际的转换。

在我们进行之前，我们需要了解controller-runtime如何看待版本。具体而言:

完全图在航海方面不够充分。

定义转换的一个简单方法可能是定义转换函数，以在我们每个版本之间进行转换。然后，每当我们需要转换时，就查找适当的函数，并调用它来执行转换。

当我们只有两个版本时，这很好，但如果我们有 4 种类型呢？8 种类型呢？那将需要很多转换函数。

相反，controller-runtime 将转换建模为“中心与辐射“模型——我们将一个版本标记为“中心“，所有其他版本只定义与中心之间的转换：

然后，如果我们需要在两个非中心版本之间进行转换，我们首先转换为中心版本，然后再转换为我们所需的版本：

这减少了我们需要定义的转换函数的数量，并且是基于 Kubernetes 在内部的做法。

这与 Webhook 有什么关系？

当 API 客户端，如 kubectl 或者你的控制器，请求某个特定版本的资源时，Kubernetes API 服务器需要返回该版本的结果。然而，该版本可能与 API 服务器存储的版本不匹配。

在这种情况下，API 服务器需要知道如何在所需版本和存储版本之间进行转换。由于 CRD 并没有内置转换功能，Kubernetes API 服务器会调用一个 webhook 来执行转换。对于 Kubebuilder，这个 webhook 是由 controller-runtime 实现的，执行我们上面讨论的中心-辐射转换。

现在我们已经掌握了转换模型，我们可以实际执行我们的转换。

实施转换

转换模型就绪后，就可以实际实现转换函数了。为 CronJob API 版本 v1（Hub）到 Spoke 的 CronJob API 版本 v2 创建转换 Webhook，参见：

kubebuilder create webhook --group batch --version v1 --kind CronJob --conversion --spoke v2

上述命令将生成 cronjob_conversion.go 文件与我们的 cronjob_types.go 文件并排，以避免在主类型文件中混入额外的函数。

中心…

首先，我们将实现中心。我们将选择 v1 版本作为中心：

Apache License

http://www.apache.org/licenses/LICENSE-2.0

package v1

// Hub marks this type as a conversion hub.
func (*CronJob) Hub() {}

… 和发言人

然后，我们将实现我们的分支，v2 版本：

Apache License

http://www.apache.org/licenses/LICENSE-2.0

package v2

Imports

import (
	"fmt"
	"strings"

	"log"

	"sigs.k8s.io/controller-runtime/pkg/conversion"

	batchv1 "tutorial.kubebuilder.io/project/api/v1"
)

// ConvertTo converts this CronJob (v2) to the Hub version (v1).
func (src *CronJob) ConvertTo(dstRaw conversion.Hub) error {
	dst := dstRaw.(*batchv1.CronJob)
	log.Printf("ConvertTo: Converting CronJob from Spoke version v2 to Hub version v1;"+
		"source: %s/%s, target: %s/%s", src.Namespace, src.Name, dst.Namespace, dst.Name)

	sched := src.Spec.Schedule
	scheduleParts := []string{"*", "*", "*", "*", "*"}
	if sched.Minute != nil {
		scheduleParts[0] = string(*sched.Minute)
	}
	if sched.Hour != nil {
		scheduleParts[1] = string(*sched.Hour)
	}
	if sched.DayOfMonth != nil {
		scheduleParts[2] = string(*sched.DayOfMonth)
	}
	if sched.Month != nil {
		scheduleParts[3] = string(*sched.Month)
	}
	if sched.DayOfWeek != nil {
		scheduleParts[4] = string(*sched.DayOfWeek)
	}
	dst.Spec.Schedule = strings.Join(scheduleParts, " ")

rote conversion

	// ObjectMeta
	dst.ObjectMeta = src.ObjectMeta

	// Spec
	dst.Spec.StartingDeadlineSeconds = src.Spec.StartingDeadlineSeconds
	dst.Spec.ConcurrencyPolicy = batchv1.ConcurrencyPolicy(src.Spec.ConcurrencyPolicy)
	dst.Spec.Suspend = src.Spec.Suspend
	dst.Spec.JobTemplate = src.Spec.JobTemplate
	dst.Spec.SuccessfulJobsHistoryLimit = src.Spec.SuccessfulJobsHistoryLimit
	dst.Spec.FailedJobsHistoryLimit = src.Spec.FailedJobsHistoryLimit

	// Status
	dst.Status.Active = src.Status.Active
	dst.Status.LastScheduleTime = src.Status.LastScheduleTime

	return nil
}

// ConvertFrom converts the Hub version (v1) to this CronJob (v2).
func (dst *CronJob) ConvertFrom(srcRaw conversion.Hub) error {
	src := srcRaw.(*batchv1.CronJob)
	log.Printf("ConvertFrom: Converting CronJob from Hub version v1 to Spoke version v2;"+
		"source: %s/%s, target: %s/%s", src.Namespace, src.Name, dst.Namespace, dst.Name)

	schedParts := strings.Split(src.Spec.Schedule, " ")
	if len(schedParts) != 5 {
		return fmt.Errorf("invalid schedule: not a standard 5-field schedule")
	}
	partIfNeeded := func(raw string) *CronField {
		if raw == "*" {
			return nil
		}
		part := CronField(raw)
		return &part
	}
	dst.Spec.Schedule.Minute = partIfNeeded(schedParts[0])
	dst.Spec.Schedule.Hour = partIfNeeded(schedParts[1])
	dst.Spec.Schedule.DayOfMonth = partIfNeeded(schedParts[2])
	dst.Spec.Schedule.Month = partIfNeeded(schedParts[3])
	dst.Spec.Schedule.DayOfWeek = partIfNeeded(schedParts[4])

rote conversion

	// ObjectMeta
	dst.ObjectMeta = src.ObjectMeta

	// Spec
	dst.Spec.StartingDeadlineSeconds = src.Spec.StartingDeadlineSeconds
	dst.Spec.ConcurrencyPolicy = ConcurrencyPolicy(src.Spec.ConcurrencyPolicy)
	dst.Spec.Suspend = src.Spec.Suspend
	dst.Spec.JobTemplate = src.Spec.JobTemplate
	dst.Spec.SuccessfulJobsHistoryLimit = src.Spec.SuccessfulJobsHistoryLimit
	dst.Spec.FailedJobsHistoryLimit = src.Spec.FailedJobsHistoryLimit

	// Status
	dst.Status.Active = src.Status.Active
	dst.Status.LastScheduleTime = src.Status.LastScheduleTime

	return nil
}

现在我们已经设置好了转换，我们需要做的就是将主程序连接起来，以便提供 webhook！

设置网络hooks

我们的转换已经到位，因此剩下的就是告诉 controller-runtime 我们的转换。

v1 的 Webhook 设置

v1 Webhook 处理转换（作为 hub），并为基于字符串 schedule 的 v1 CronJob 格式提供校验/默认值：

Apache License

http://www.apache.org/licenses/LICENSE-2.0

Imports

package v1

import (
	"context"

	"github.com/robfig/cron"
	apierrors "k8s.io/apimachinery/pkg/api/errors"
	"k8s.io/apimachinery/pkg/runtime/schema"
	validationutils "k8s.io/apimachinery/pkg/util/validation"
	"k8s.io/apimachinery/pkg/util/validation/field"

	ctrl "sigs.k8s.io/controller-runtime"
	logf "sigs.k8s.io/controller-runtime/pkg/log"
	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"

	batchv1 "tutorial.kubebuilder.io/project/api/v1"
)

var cronjoblog = logf.Log.WithName("cronjob-resource")

// SetupCronJobWebhookWithManager registers the webhook for CronJob in the manager.
func SetupCronJobWebhookWithManager(mgr ctrl.Manager) error {
	return ctrl.NewWebhookManagedBy(mgr, &batchv1.CronJob{}).
		WithValidator(&CronJobValidator{}).
		WithDefaulter(&CronJobDefaulter{
			DefaultConcurrencyPolicy:          batchv1.AllowConcurrent,
			DefaultSuspend:                    false,
			DefaultSuccessfulJobsHistoryLimit: 3,
			DefaultFailedJobsHistoryLimit:     1,
		}).
		Complete()
}

// +kubebuilder:webhook:path=/mutate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=true,failurePolicy=fail,sideEffects=None,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=mcronjob-v1.kb.io,admissionReviewVersions=v1

// CronJobDefaulter struct is responsible for setting default values on the custom resource of the
// Kind CronJob when those are created or updated.
//
// NOTE: The +kubebuilder:object:generate=false marker prevents controller-gen from generating DeepCopy methods,
// as it is used only for temporary operations and does not need to be deeply copied.
type CronJobDefaulter struct {

	// Default values for various CronJob fields
	DefaultConcurrencyPolicy          batchv1.ConcurrencyPolicy
	DefaultSuspend                    bool
	DefaultSuccessfulJobsHistoryLimit int32
	DefaultFailedJobsHistoryLimit     int32
}

// Default implements admission.Defaulter so a webhook will be registered for the Kind CronJob.
func (d *CronJobDefaulter) Default(_ context.Context, obj *batchv1.CronJob) error {
	cronjoblog.Info("Defaulting for CronJob", "name", obj.GetName())

	// Set default values
	d.applyDefaults(obj)
	return nil
}

// applyDefaults applies default values to CronJob fields.
func (d *CronJobDefaulter) applyDefaults(cronJob *batchv1.CronJob) {
	if cronJob.Spec.ConcurrencyPolicy == "" {
		cronJob.Spec.ConcurrencyPolicy = d.DefaultConcurrencyPolicy
	}
	if cronJob.Spec.Suspend == nil {
		cronJob.Spec.Suspend = new(bool)
		*cronJob.Spec.Suspend = d.DefaultSuspend
	}
	if cronJob.Spec.SuccessfulJobsHistoryLimit == nil {
		cronJob.Spec.SuccessfulJobsHistoryLimit = new(int32)
		*cronJob.Spec.SuccessfulJobsHistoryLimit = d.DefaultSuccessfulJobsHistoryLimit
	}
	if cronJob.Spec.FailedJobsHistoryLimit == nil {
		cronJob.Spec.FailedJobsHistoryLimit = new(int32)
		*cronJob.Spec.FailedJobsHistoryLimit = d.DefaultFailedJobsHistoryLimit
	}
}

Remaining Webhook Code

// NOTE: If you want to customise the 'path', use the flags '--defaulting-path' or '--validation-path'.
// +kubebuilder:webhook:path=/validate-batch-tutorial-kubebuilder-io-v1-cronjob,mutating=false,failurePolicy=fail,sideEffects=None,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v1,name=vcronjob-v1.kb.io,admissionReviewVersions=v1

// CronJobValidator struct is responsible for validating the CronJob resource
// when it is created, updated, or deleted.
//
// NOTE: The +kubebuilder:object:generate=false marker prevents controller-gen from generating DeepCopy methods,
// as this struct is used only for temporary operations and does not need to be deeply copied.
type CronJobValidator struct {

	// TODO(user): Add more fields as needed for validation
}

// ValidateCreate implements admission.Validator so a webhook will be registered for the type CronJob.
func (v *CronJobValidator) ValidateCreate(_ context.Context, obj *batchv1.CronJob) (admission.Warnings, error) {
	cronjoblog.Info("Validation for CronJob upon creation", "name", obj.GetName())

	return nil, validateCronJob(obj)
}

// ValidateUpdate implements admission.Validator so a webhook will be registered for the type CronJob.
func (v *CronJobValidator) ValidateUpdate(_ context.Context, oldObj, newObj *batchv1.CronJob) (admission.Warnings, error) {
	cronjoblog.Info("Validation for CronJob upon update", "name", newObj.GetName())

	return nil, validateCronJob(newObj)
}

// ValidateDelete implements admission.Validator so a webhook will be registered for the type CronJob.
func (v *CronJobValidator) ValidateDelete(_ context.Context, obj *batchv1.CronJob) (admission.Warnings, error) {
	cronjoblog.Info("Validation for CronJob upon deletion", "name", obj.GetName())

	// TODO(user): fill in your validation logic upon object deletion.

	return nil, nil
}

// validateCronJob validates the fields of a CronJob object.
func validateCronJob(cronjob *batchv1.CronJob) error {
	var allErrs field.ErrorList
	if err := validateCronJobName(cronjob); err != nil {
		allErrs = append(allErrs, err)
	}
	if err := validateCronJobSpec(cronjob); err != nil {
		allErrs = append(allErrs, err)
	}
	if len(allErrs) == 0 {
		return nil
	}

	return apierrors.NewInvalid(
		schema.GroupKind{Group: "batch.tutorial.kubebuilder.io", Kind: "CronJob"},
		cronjob.Name, allErrs)
}

func validateCronJobSpec(cronjob *batchv1.CronJob) *field.Error {
	// The field helpers from the kubernetes API machinery help us return nicely
	// structured validation errors.
	return validateScheduleFormat(
		cronjob.Spec.Schedule,
		field.NewPath("spec").Child("schedule"))
}

func validateScheduleFormat(schedule string, fldPath *field.Path) *field.Error {
	if _, err := cron.ParseStandard(schedule); err != nil {
		return field.Invalid(fldPath, schedule, err.Error())
	}
	return nil
}

func validateCronJobName(cronjob *batchv1.CronJob) *field.Error {
	if len(cronjob.Name) > validationutils.DNS1035LabelMaxLength-11 {
		// The job name length is 63 characters like all Kubernetes objects
		// (which must fit in a DNS subdomain). The cronjob controller appends
		// a 11-character suffix to the cronjob (`-$TIMESTAMP`) when creating
		// a job. The job name length limit is 63 characters. Therefore cronjob
		// names must have length <= 63-11=52. If we don't validate this here,
		// then job creation will fail later.
		return field.Invalid(field.NewPath("metadata").Child("name"), cronjob.Name, "must be no more than 52 characters")
	}
	return nil
}

v2 的 Webhook 设置

v2 Webhook 为带有结构化 CronSchedule 类型的 v2 CronJob 格式提供校验与默认值。注意校验逻辑与 v1 不同——它从各个 schedule 字段构建 cron 表达式：

Apache License

http://www.apache.org/licenses/LICENSE-2.0

Imports

package v2

import (
	"context"
	"strings"

	"github.com/robfig/cron"
	apierrors "k8s.io/apimachinery/pkg/api/errors"
	"k8s.io/apimachinery/pkg/runtime/schema"
	validationutils "k8s.io/apimachinery/pkg/util/validation"
	"k8s.io/apimachinery/pkg/util/validation/field"

	ctrl "sigs.k8s.io/controller-runtime"
	logf "sigs.k8s.io/controller-runtime/pkg/log"
	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"

	batchv2 "tutorial.kubebuilder.io/project/api/v2"
)

Webhook Setup and Defaulting

// nolint:unused
// log is for logging in this package.
var cronjoblog = logf.Log.WithName("cronjob-resource")

// SetupCronJobWebhookWithManager registers the webhook for CronJob in the manager.
func SetupCronJobWebhookWithManager(mgr ctrl.Manager) error {
	return ctrl.NewWebhookManagedBy(mgr, &batchv2.CronJob{}).
		WithValidator(&CronJobValidator{}).
		WithDefaulter(&CronJobDefaulter{
			DefaultConcurrencyPolicy:          batchv2.AllowConcurrent,
			DefaultSuspend:                    false,
			DefaultSuccessfulJobsHistoryLimit: 3,
			DefaultFailedJobsHistoryLimit:     1,
		}).
		Complete()
}

// TODO(user): EDIT THIS FILE!  THIS IS SCAFFOLDING FOR YOU TO OWN!

// +kubebuilder:webhook:path=/mutate-batch-tutorial-kubebuilder-io-v2-cronjob,mutating=true,failurePolicy=fail,sideEffects=None,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v2,name=mcronjob-v2.kb.io,admissionReviewVersions=v1

// CronJobDefaulter struct is responsible for setting default values on the custom resource of the
// Kind CronJob when those are created or updated.
//
// NOTE: The +kubebuilder:object:generate=false marker prevents controller-gen from generating DeepCopy methods,
// as it is used only for temporary operations and does not need to be deeply copied.
type CronJobDefaulter struct {
	// Default values for various CronJob fields
	DefaultConcurrencyPolicy          batchv2.ConcurrencyPolicy
	DefaultSuspend                    bool
	DefaultSuccessfulJobsHistoryLimit int32
	DefaultFailedJobsHistoryLimit     int32
}

// Default implements admission.Defaulter so a webhook will be registered for the Kind CronJob.
func (d *CronJobDefaulter) Default(_ context.Context, obj *batchv2.CronJob) error {
	cronjoblog.Info("Defaulting for CronJob", "name", obj.GetName())

	// Set default values
	d.applyDefaults(obj)
	return nil

}

// TODO(user): change verbs to "verbs=create;update;delete" if you want to enable deletion validation.
// NOTE: If you want to customise the 'path', use the flags '--defaulting-path' or '--validation-path'.
// +kubebuilder:webhook:path=/validate-batch-tutorial-kubebuilder-io-v2-cronjob,mutating=false,failurePolicy=fail,sideEffects=None,groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=create;update,versions=v2,name=vcronjob-v2.kb.io,admissionReviewVersions=v1

// CronJobValidator struct is responsible for validating the CronJob resource
// when it is created, updated, or deleted.
//
// NOTE: The +kubebuilder:object:generate=false marker prevents controller-gen from generating DeepCopy methods,
// as this struct is used only for temporary operations and does not need to be deeply copied.
type CronJobValidator struct {
	// TODO(user): Add more fields as needed for validation
}

// ValidateCreate implements admission.Validator so a webhook will be registered for the type CronJob.
func (v *CronJobValidator) ValidateCreate(_ context.Context, obj *batchv2.CronJob) (admission.Warnings, error) {
	cronjoblog.Info("Validation for CronJob upon creation", "name", obj.GetName())

	return nil, validateCronJob(obj)
}

// ValidateUpdate implements admission.Validator so a webhook will be registered for the type CronJob.
func (v *CronJobValidator) ValidateUpdate(_ context.Context, oldObj, newObj *batchv2.CronJob) (admission.Warnings, error) {
	cronjoblog.Info("Validation for CronJob upon update", "name", newObj.GetName())

	return nil, validateCronJob(newObj)
}

// ValidateDelete implements admission.Validator so a webhook will be registered for the type CronJob.
func (v *CronJobValidator) ValidateDelete(_ context.Context, obj *batchv2.CronJob) (admission.Warnings, error) {
	cronjoblog.Info("Validation for CronJob upon deletion", "name", obj.GetName())

	// TODO(user): fill in your validation logic upon object deletion.

	return nil, nil
}

// applyDefaults applies default values to CronJob fields.
func (d *CronJobDefaulter) applyDefaults(cronJob *batchv2.CronJob) {
	if cronJob.Spec.ConcurrencyPolicy == "" {
		cronJob.Spec.ConcurrencyPolicy = d.DefaultConcurrencyPolicy
	}
	if cronJob.Spec.Suspend == nil {
		cronJob.Spec.Suspend = new(bool)
		*cronJob.Spec.Suspend = d.DefaultSuspend
	}
	if cronJob.Spec.SuccessfulJobsHistoryLimit == nil {
		cronJob.Spec.SuccessfulJobsHistoryLimit = new(int32)
		*cronJob.Spec.SuccessfulJobsHistoryLimit = d.DefaultSuccessfulJobsHistoryLimit
	}
	if cronJob.Spec.FailedJobsHistoryLimit == nil {
		cronJob.Spec.FailedJobsHistoryLimit = new(int32)
		*cronJob.Spec.FailedJobsHistoryLimit = d.DefaultFailedJobsHistoryLimit
	}
}

// validateCronJob validates the fields of a CronJob object.
func validateCronJob(cronjob *batchv2.CronJob) error {
	var allErrs field.ErrorList
	if err := validateCronJobName(cronjob); err != nil {
		allErrs = append(allErrs, err)
	}
	if err := validateCronJobSpec(cronjob); err != nil {
		allErrs = append(allErrs, err)
	}
	if len(allErrs) == 0 {
		return nil
	}
	return apierrors.NewInvalid(schema.GroupKind{Group: "batch.tutorial.kubebuilder.io", Kind: "CronJob"}, cronjob.Name, allErrs)
}

func validateCronJobName(cronjob *batchv2.CronJob) *field.Error {
	if len(cronjob.Name) > validationutils.DNS1035LabelMaxLength-11 {
		return field.Invalid(field.NewPath("metadata").Child("name"), cronjob.Name, "must be no more than 52 characters")
	}
	return nil
}

// validateCronJobSpec validates the schedule format of the custom CronSchedule type
func validateCronJobSpec(cronjob *batchv2.CronJob) *field.Error {
	// Build cron expression from the parts
	parts := []string{"*", "*", "*", "*", "*"} // default parts for minute, hour, day of month, month, day of week
	if cronjob.Spec.Schedule.Minute != nil {
		parts[0] = string(*cronjob.Spec.Schedule.Minute) // Directly cast CronField (which is an alias of string) to string
	}
	if cronjob.Spec.Schedule.Hour != nil {
		parts[1] = string(*cronjob.Spec.Schedule.Hour)
	}
	if cronjob.Spec.Schedule.DayOfMonth != nil {
		parts[2] = string(*cronjob.Spec.Schedule.DayOfMonth)
	}
	if cronjob.Spec.Schedule.Month != nil {
		parts[3] = string(*cronjob.Spec.Schedule.Month)
	}
	if cronjob.Spec.Schedule.DayOfWeek != nil {
		parts[4] = string(*cronjob.Spec.Schedule.DayOfWeek)
	}

	// Join parts to form the full cron expression
	cronExpression := strings.Join(parts, " ")

	return validateScheduleFormat(
		cronExpression,
		field.NewPath("spec").Child("schedule"))
}

func validateScheduleFormat(schedule string, fldPath *field.Path) *field.Error {
	if _, err := cron.ParseStandard(schedule); err != nil {
		return field.Invalid(fldPath, schedule, "invalid cron schedule format: "+err.Error())
	}
	return nil
}

…和 main.go

同样，我们现有的主文件是足够的：

Apache License

http://www.apache.org/licenses/LICENSE-2.0

Imports

package main

import (
	"crypto/tls"
	"flag"
	"os"

	// 导入所有 Kubernetes 客户端身份验证插件（例如 Azure、GCP、OIDC 等）
	// 确保 exec-entrypoint 和 run 可以使用它们。
	_ "k8s.io/client-go/plugin/pkg/client/auth"

	kbatchv1 "k8s.io/api/batch/v1"
	"k8s.io/apimachinery/pkg/runtime"
	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
	clientgoscheme "k8s.io/client-go/kubernetes/scheme"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/healthz"
	"sigs.k8s.io/controller-runtime/pkg/log/zap"
	"sigs.k8s.io/controller-runtime/pkg/metrics/filters"
	metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
	"sigs.k8s.io/controller-runtime/pkg/webhook"

	batchv1 "tutorial.kubebuilder.io/project/api/v1"
	batchv2 "tutorial.kubebuilder.io/project/api/v2"
	"tutorial.kubebuilder.io/project/internal/controller"
	webhookv1 "tutorial.kubebuilder.io/project/internal/webhook/v1"
	webhookv2 "tutorial.kubebuilder.io/project/internal/webhook/v2"
	// +kubebuilder:scaffold:imports
)

existing setup

var (
	scheme   = runtime.NewScheme()
	setupLog = ctrl.Log.WithName("setup")
)

func init() {
	utilruntime.Must(clientgoscheme.AddToScheme(scheme))

	utilruntime.Must(kbatchv1.AddToScheme(scheme)) // we've added this ourselves
	utilruntime.Must(batchv1.AddToScheme(scheme))
	utilruntime.Must(batchv2.AddToScheme(scheme))
	// +kubebuilder:scaffold:scheme
}

// nolint:gocyclo
func main() {

Manager Setup

	var metricsAddr string
	var metricsCertPath, metricsCertName, metricsCertKey string
	var webhookCertPath, webhookCertName, webhookCertKey string
	var webhookPort int
	var enableLeaderElection bool
	var probeAddr string
	var secureMetrics bool
	var enableHTTP2 bool
	var tlsOpts []func(*tls.Config)
	flag.StringVar(&metricsAddr, "metrics-bind-address", "0", "The address the metrics endpoint binds to. "+
		"使用 :8443 进行 HTTPS，使用 :8080 进行 HTTP，或者保持为 0 以禁用指标服务。")
	flag.StringVar(&probeAddr, "health-probe-bind-address", ":8081", "The address the probe endpoint binds to.")
	flag.BoolVar(&enableLeaderElection, "leader-elect", false,
		"Enable leader election for controller manager. "+
			"启用此功能将确保只有一个活动的控制管理器。")
	flag.BoolVar(&secureMetrics, "metrics-secure", true,
		"如果设置，指标端点将通过 HTTPS 安全提供。请使用 --metrics-secure=false 以改为使用 HTTP。")
	flag.StringVar(&webhookCertPath, "webhook-cert-path", "", "The directory that contains the webhook certificate.")
	flag.StringVar(&webhookCertName, "webhook-cert-name", "tls.crt", "The name of the webhook certificate file.")
	flag.StringVar(&webhookCertKey, "webhook-cert-key", "tls.key", "The name of the webhook key file.")
	flag.IntVar(&webhookPort, "webhook-port", 9443, "Port the webhook server listens on. "+
		"Defaults to 9443. Set -1 to disable the webhook server.")
	flag.StringVar(&metricsCertPath, "metrics-cert-path", "",
		"The directory that contains the metrics server certificate.")
	flag.StringVar(&metricsCertName, "metrics-cert-name", "tls.crt", "The name of the metrics server certificate file.")
	flag.StringVar(&metricsCertKey, "metrics-cert-key", "tls.key", "The name of the metrics server key file.")
	flag.BoolVar(&enableHTTP2, "enable-http2", false,
		"If set, HTTP/2 will be enabled for the metrics and webhook servers")
	opts := zap.Options{
		Development: true,
	}
	opts.BindFlags(flag.CommandLine)
	flag.Parse()

	ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts)))

	// 如果 enable-http2 标志为 false（默认值），则应禁用 http/2
	// 由于其存在的漏洞。更具体地说，禁用 http/2 将
	// 防止受到 HTTP/2 流取消和
	// 快速重置 CVE 的漏洞影响。有关更多信息，请参见：
	// - https://github.com/advisories/GHSA-qppj-fm5r-hxr3
	// - https://github.com/advisories/GHSA-4374-p667-p6c8
	disableHTTP2 := func(c *tls.Config) {
		setupLog.Info("Disabling HTTP/2")
		c.NextProtos = []string{"http/1.1"}
	}

	if !enableHTTP2 {
		tlsOpts = append(tlsOpts, disableHTTP2)
	}

	// 初始Webhook TLS选项
	webhookTLSOpts := tlsOpts
	webhookServerOptions := webhook.Options{
		TLSOpts: webhookTLSOpts,
		Port:    webhookPort,
	}

	if len(webhookCertPath) > 0 {
		setupLog.Info("使用提供的证书初始化 Webhook 证书监视器",
			"webhook-cert-path", webhookCertPath, "webhook-cert-name", webhookCertName, "webhook-cert-key", webhookCertKey)

		webhookServerOptions.CertDir = webhookCertPath
		webhookServerOptions.CertName = webhookCertName
		webhookServerOptions.KeyName = webhookCertKey
	}

	webhookServer := webhook.NewServer(webhookServerOptions)

	// Metrics 端点已在 'config/default/kustomization.yaml'. Metrics 选项用于配置服务器。
	// 更多信息：
	// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.25.0/pkg/metrics/server
	// - https://book.kubebuilder.io/reference/metrics.html
	metricsServerOptions := metricsserver.Options{
		BindAddress:   metricsAddr,
		SecureServing: secureMetrics,
		TLSOpts:       tlsOpts,
	}

	if secureMetrics {
		// FilterProvider 用于通过认证/鉴权保护 metrics 端点。
		// These configurations ensure that only authorized users and service accounts
		// can access the metrics endpoint. The RBAC are configured in 'config/rbac/kustomization.yaml'. More info:
		// https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.25.0/pkg/metrics/filters#WithAuthenticationAndAuthorization
		metricsServerOptions.FilterProvider = filters.WithAuthenticationAndAuthorization
	}

	// 如果未指定证书，controller-runtime 将自动
	// 为指标服务器生成自签名证书。虽然对于开发和测试来说很方便，
	// 但这种设置不建议用于生产环境。
	//
	// TODO(用户)：如果您启用 certManager，请取消注释以下行：
	// - [METRICS-WITH-CERTS] 在 config/default/kustomization.yaml 中生成并使用
	// 由 cert-manager 管理的指标服务器证书。
	// - [PROMETHEUS-WITH-CERTS] 在 config/prometheus/kustomization.yaml 中用于 TLS 认证。
	if len(metricsCertPath) > 0 {
		setupLog.Info("使用提供的证书初始化指标证书监视器",
			"metrics-cert-path", metricsCertPath, "metrics-cert-name", metricsCertName, "metrics-cert-key", metricsCertKey)

		metricsServerOptions.CertDir = metricsCertPath
		metricsServerOptions.CertName = metricsCertName
		metricsServerOptions.KeyName = metricsCertKey
	}

	mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
		Scheme:                 scheme,
		Metrics:                metricsServerOptions,
		WebhookServer:          webhookServer,
		HealthProbeBindAddress: probeAddr,
		LeaderElection:         enableLeaderElection,
		LeaderElectionID:       "80807133.tutorial.kubebuilder.io",
		// LeaderElectionReleaseOnCancel 定义了当管理器结束时，领导者是否应自愿辞职
		// 当管理器停止时，这要求二进制文件立即结束，否则这个设置是不安全的。设置这个可以显著
		// 加快自愿领导者的过渡，因为新的领导者不必首先等待
		// LeaseDuration 时间。
		//
		// 在提供的默认脚手架中，程序会在
		// 管理器停止后立即结束，因此启用此选项是可以的。不过，
		// 如果您正在进行或打算在管理器停止后执行任何操作，如执行清理，
		// 那么使用它可能是不安全的。
		// LeaderElectionReleaseOnCancel: true,
	})
	if err != nil {
		setupLog.Error(err, "Failed to start manager")
		os.Exit(1)
	}

	if err := (&controller.CronJobReconciler{
		Client: mgr.GetClient(),
		Scheme: mgr.GetScheme(),
	}).SetupWithManager(mgr); err != nil {
		setupLog.Error(err, "Failed to create controller", "controller", "cronjob")
		os.Exit(1)
	}

	// nolint:goconst
	if os.Getenv("ENABLE_WEBHOOKS") != "false" {
		if err := webhookv1.SetupCronJobWebhookWithManager(mgr); err != nil {
			setupLog.Error(err, "Failed to create webhook", "webhook", "CronJob")
			os.Exit(1)
		}
	}
	// nolint:goconst
	if os.Getenv("ENABLE_WEBHOOKS") != "false" {
		if err := webhookv2.SetupCronJobWebhookWithManager(mgr); err != nil {
			setupLog.Error(err, "Failed to create webhook", "webhook", "CronJob")
			os.Exit(1)
		}
	}
	// +kubebuilder:scaffold:builder

	if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
		setupLog.Error(err, "Failed to set up health check")
		os.Exit(1)
	}
	if err := mgr.AddReadyzCheck("readyz", healthz.Ping); err != nil {
		setupLog.Error(err, "Failed to set up ready check")
		os.Exit(1)
	}

	setupLog.Info("Starting manager")
	if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
		setupLog.Error(err, "Failed to run manager")
		os.Exit(1)
	}
}

一切都已经准备好！现在剩下的就是测试我们的网络钩子了。

部署与测试

在我们测试转换之前，我们需要在我们的 CRD 中启用它们：

Kubebuilder 在 config 目录下生成 Kubernetes 清单，默认情况下禁用了 webhook 部分。要启用它们，我们需要：

• 在 config/crd/kustomization.yaml 文件中启用 patches/webhook_in_<kind>.yaml 和 patches/cainjection_in_<kind>.yaml。

• 在 config/default/kustomization.yaml 文件的 bases 部分启用 ../certmanager 和 ../webhook 目录。

• 启用 config/default/kustomization.yaml 文件中 CERTMANAGER 部分下的所有变量。

另外，如果在我们的 Makefile 中存在，我们需要将 CRD_OPTIONS 变量设置为 "crd"，移除 trivialVersions 选项（这确保我们实际上为每个版本[生成验证](/reference/generating-crd.md#multiple-versions “生成CRDs：多个版本”），而不是告诉 Kubernetes 它们是相同的）：

CRD_OPTIONS ?= "crd"

现在我们已经完成了所有的代码更改和清单，接下来将其部署到集群并进行测试。

除非你有其他证书管理解决方案，否则你需要安装 cert-manager（版本 0.9.0+）。Kubebuilder 团队已经在 0.9.0-alpha.0 版本中测试了本教程中的指令。

一旦我们的证书准备齐全，我们可以像往常一样运行 make install deploy 来将所有组件（CRD 和控制器管理器部署）部署到集群上。

测试

一旦集群中所有位都启动并运行并启用了转换功能，我们就可以通过请求不同版本来测试我们的转换。

基于 v1 版本制作 v2 版本（放在 config/samples 下）

apiVersion: batch.tutorial.kubebuilder.io/v2
kind: CronJob
metadata:
  labels:
    app.kubernetes.io/name: project
    app.kubernetes.io/managed-by: kustomize
  name: cron作业示例
spec:
  日程安排:
    分钟: "*/1"
  启动截止时间（秒）: 60
  并发策略: 允许 # 显式指定，但允许也是默认值。
  工作模板:
    spec:
      template:
        spec:
          安全上下文:
            以非root用户身份运行: true
            以用户身份运行: 1000
            seccompProfile:
              type: RuntimeDefault
          容器:
          - name: 你好
            image: busybox
            args:
            - /bin/sh
            - -c
            - 日期; 在Kubernetes集群中打招呼。
            安全上下文:
              allowPrivilegeEscalation: false
              capabilities:
                drop:
                - ALL
              readOnlyRootFilesystem: false
          重启策略: 失败时

然后，我们可以在集群上创建它：

kubectl apply -f config/samples/batch_v2_cronjob.yaml

如果我们一切都做对了，它应该会成功创建，我们应该能够通过 v2 资源来获取它。

kubectl get cronjobs.v2.batch.tutorial.kubebuilder.io -o yaml

apiVersion: batch.tutorial.kubebuilder.io/v2
kind: CronJob
metadata:
  labels:
    app.kubernetes.io/name: project
    app.kubernetes.io/managed-by: kustomize
  name: cron作业示例
spec:
  日程安排:
    分钟: "*/1"
  启动截止时间（秒）: 60
  并发策略: 允许 # 显式指定，但允许也是默认值。
  工作模板:
    spec:
      template:
        spec:
          安全上下文:
            以非root用户身份运行: true
            以用户身份运行: 1000
            seccompProfile:
              type: RuntimeDefault
          容器:
          - name: 你好
            image: busybox
            args:
            - /bin/sh
            - -c
            - 日期; 在Kubernetes集群中打招呼。
            安全上下文:
              allowPrivilegeEscalation: false
              capabilities:
                drop:
                - ALL
              readOnlyRootFilesystem: false
          重启策略: 失败时

和 v1 资源

kubectl get cronjobs.v1.batch.tutorial.kubebuilder.io -o yaml

apiVersion: batch.tutorial.kubebuilder.io/v1
kind: CronJob
metadata:
  labels:
    app.kubernetes.io/name: project
    app.kubernetes.io/managed-by: kustomize
  name: cron作业示例
spec:
  日程安排: "*/1 * * * *"
  启动截止时间（秒）: 60
  并发策略: 允许 # 显式指定，但允许也是默认值。
  工作模板:
    spec:
      template:
        spec:
          安全上下文:
            以非root用户身份运行: true
            以用户身份运行: 1000
            seccompProfile:
              type: RuntimeDefault
          容器:
          - name: 你好
            image: busybox
            args:
            - /bin/sh
            - -c
            - 日期; 在Kubernetes集群中打招呼。
            安全上下文:
              allowPrivilegeEscalation: false
              capabilities:
                drop:
                - ALL
              readOnlyRootFilesystem: false
          重启策略: 失败时
  

两者都应该填写，并且看起来与我们的 v2 和 v1 示例各自相当。请注意，每个都有不同的 API 版本。

最后，如果我们等一会儿，我们应该注意到我们的 CronJob 继续进行调整，尽管我们的控制器是针对我们的 v1 API 版本编写的。

迁移

将 Kubebuilder 项目升级到最新版本，可获得新功能、缺陷修复与生态改进。建议让项目与生态变更保持同步。

迁移可能包括升级到更新的插件版本（例如从 3.x 发行版的 go.kubebuilder.io/v3 到 4.x 的 go.kubebuilder.io/v4），或在同一插件下跨 CLI 发行版更新脚手架（例如从 v4.9.0 到 v4.10.1）。

Kubebuilder 提供多种迁移路径以适应不同工作流。请选择最适合您的方式。

迁移选项

[!TIP] 推荐： 启用 AutoUpdate 插件（GitHub Actions）以减少工作量。也可在本地运行 alpha update——两者使用相同的更新逻辑。其他选项主要用于 PROJECT 文件中尚无 cliVersion 的旧项目，作为一次性步骤升级到受支持版本；之后再用上述工作流进行后续更新（更旧版本无法使用这些自动化功能）。

（推荐） AutoUpdate/GitHub Action：通过带有 PR 链接的 Issue 获知新的 Kubebuilder 发行版，以便审阅与升级

AutoUpdate 插件 会脚手架一个 Action：自动监控新的 Kubebuilder 发行版，并在有更新时打开带有 Pull Request 对比链接的 GitHub Issue。适合以最少人工工作保持项目最新。

该插件提供类似 GitHub Dependabot 的机制，为遵循标准脚手架的项目提供带 AI 辅助的持续更新。

kubebuilder edit --plugins="autoupdate/v1-alpha"

完整说明见 AutoUpdate 插件文档。

（推荐） 使用 alpha update 升级且不丢失自定义内容（即 AutoUpdate/GitHub Action 背后的逻辑）

若希望在本地运行更新而不依赖 GitHub Actions，可在命令行直接使用与 AutoUpdate 插件 相同的逻辑。

kubebuilder alpha update

该命令与 AutoUpdate 插件使用相同底层机制。您可以迁移项目、按需解决冲突，然后从本地环境推送 Pull Request。

全部选项与标志见 alpha update 命令参考。

借助工具重新生成并手动合并

kubebuilder alpha generate 会根据 PROJECT 文件配置重新脚手架整个项目，之后可手动对比并合并自定义代码。例如，可在升级 Kubebuilder CLI 后用它重新生成项目，再用 IDE 或 git diff 手动将变更合并回现有代码库，确保自定义内容落在新脚手架上。

该方法适用于大量自定义脚手架、或其他迁移方式不可用的项目。通常只需用一次以建立基线，供后续自动化更新使用。

kubebuilder alpha generate

详见 alpha generate 命令参考。

完全手动迁移

若需要完全掌控，可手动迁移：用最新 Kubebuilder 创建新项目，再把代码移植过去。

该过程中，需从头运行全部命令创建新项目、API、控制器、Webhook 及其他资源，再把旧项目中的业务逻辑与自定义内容手动复制到新项目。

为简化这一次性迁移，已提供 AI 迁移助手 以自动化重复任务。

完整分步说明（含 AI 助手）见手动迁移流程指南。

手动迁移流程

请确保你已按照安装指南安装所需组件，并且所需版本的 Kubebuilder CLI 已位于你的 PATH 中。

本指南概述了将现有 Kubebuilder 项目迁移到较新版本 Kubebuilder 框架的手动步骤。此过程包括重新搭建项目脚手架，并手动移植你的自定义代码和配置。

从 Kubebuilder v3.0.0 起，Kubebuilder 使用的所有输入都会记录在 PROJECT 文件中。请检查当前项目中的该文件，以核对已记录的配置和元数据。请参阅 PROJECT 文件文档 以更好地理解。

另外，在开始之前，建议查阅基础项目包含什么？，以便更好地理解项目布局和结构。

阶段 1：Reorganize to New Layout (Required only for Legacy Layouts)

仅在以下任一条件为真时需要：

• 控制器不在 internal/controller/ 中
• Webhook 不在 internal/webhook/ 中
• main 不在 cmd/ 中

如果你的项目已使用 internal/controller/、internal/webhook/ 和 cmd/main.go，可跳过此阶段。

1.1 创建重组分支

git checkout -b reorganize

1.2 重组文件位置

将文件移到新布局：

# If you have controllers/ directory
mkdir -p internal/controller
mv controllers/* internal/controller/
rmdir controllers

# OR if you have pkg/controllers/ directory
mkdir -p internal/controller
mv pkg/controllers/* internal/controller/

# If you have webhooks in api/v1/ or apis/v1/
mkdir -p internal/webhook/v1
mv api/v1/*_webhook* internal/webhook/v1/ 2>/dev/null || mv apis/v1/*_webhook* internal/webhook/v1/ 2>/dev/null || echo "未找到可移动的 webhook 文件（如果项目没有 webhook，这是预期行为）"

# If main.go is in root
mkdir -p cmd
mv main.go cmd/

1.3 更新 package 声明

移动文件后，更新 package 声明：

控制器： 在所有 *_controller.go 和 *_controller_test.go 文件中，将 package controllers → package controller。

Webhook： 保持版本作为包名（例如，在 internal/webhook/v1/ 中 package v1 仍为 package v1）。

1.4 更新 import 路径

查找并更新所有 import：

grep -r "pkg/controllers\|/controllers\"" --include="*.go"

在找到的每个文件中更新：

• 导入：<module>/controllers 或 <module>/pkg/controllers → <module>/internal/controller
• 引用：controllers.TypeName → controller.TypeName

1.5 更新 Dockerfile（如需要）

如果你的 Dockerfile 对已移动路径有显式 COPY 语句，请更新它们以反映新结构，或简化为 COPY . . 并使用 .dockerignore 排除不需要的文件。

1.6 验证并提交

构建并测试重组后的项目：

make generate manifests
make build && make test

如果成功，提交布局更改。你的项目现在使用新布局。继续进入阶段 2。

阶段 2：Migrate to Latest Version

步骤 1：Prepare Your Current Project

1.1 创建迁移分支

从当前代码库创建分支：

git checkout -b migration

1.2 创建备份

mkdir ../migration-backup
cp -r . ../migration-backup/

1.3 清理项目目录

删除除 .git 外的所有文件：

find . -not -path './.git*' -not -name '.' -not -name '..' -delete

步骤 2：Initialize the New Project

关于 PROJECT 文件： 从 v3.0.0+ 起，PROJECT 文件跟踪所有脚手架元数据。如果你有该文件且所有资源都通过 CLI 创建，请先尝试 kubebuilder alpha generate。否则，按下面的手动步骤识别并重新搭建所有资源的脚手架。

2.1 识别你的 module 与 domain

从备份中识别初始化所需的信息。

Module 路径 - 检查备份中的 go.mod 文件：

cat ../migration-backup/go.mod

查找 module 行：

module tutorial.kubebuilder.io/migration-project

Domain - 检查备份的 PROJECT 文件：

cat ../migration-backup/PROJECT

查找 domain 行：

domain: tutorial.kubebuilder.io

如果你没有 PROJECT 文件（版本 < v3.0.0），请检查 config/crd/bases/ 下的 CRD 文件，或查看 API group 名称。domain 是 API group 中 group 名称之后的部分。

2.2 初始化 Go module

使用原项目中相同的 module 路径初始化新的 Go module：

go mod init tutorial.kubebuilder.io/migration-project

将 tutorial.kubebuilder.io/migration-project 替换为你的实际 module 路径。

2.3 初始化 Kubebuilder 项目

使用 Kubebuilder 初始化项目：

kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/migration-project

替换为你的实际 domain 和 repository（module 路径）。

2.4 启用多 group 支持（如需要）

多 group 项目将 API 组织到不同的 group 中，每个 group 位于自己的目录。当你有用于不同目的或领域的 API 时，这很有用。

通过检查备份的目录结构，确认项目是否使用多 group 布局：

• 单 group 布局： 所有 API 在一个 group 中

  • api/v1/cronjob_types.go
  • api/v1/job_types.go
  • api/v2/cronjob_types.go

• 多 group 布局： API 按 group 组织

  • api/batch/v1/cronjob_types.go
  • api/crew/v1/captain_types.go
  • api/sea/v1/ship_types.go

你也可以在备份的 PROJECT 文件中检查是否有 multigroup: true。

如果你的项目使用多 group 布局，请在创建 API 之前启用它：

kubebuilder edit --multigroup=true

按本指南操作时，你会自动获得新布局，因为你是用最新版本创建全新项目，并将代码移植进去。

步骤 3：Re-scaffold APIs and Controllers

对原项目中的每个 API 资源，在新项目中重新搭建脚手架。

3.1 识别你的全部 API

查看备份项目（../migration-backup/）以识别所有 API。无论是否有 PROJECT 文件，都建议检查备份目录，因为并非所有资源都可能通过 CLI 创建。

检查备份中的目录结构，确保不会遗漏任何手动创建的资源：

• 在 api/ 目录（或较旧 Kubebuilder 版本生成的项目中的 apis/）中查找 *_types.go 文件：

  • 单 group：api/v1/cronjob_types.go - 提取：version v1，kind CronJob，group 来自导入
  • 多 group：api/batch/v1/cronjob_types.go - 提取：group batch，version v1，kind CronJob

• 在这些位置检查控制器：

  • 当前： internal/controller/cronjob_controller.go 或 internal/controller/<group>/cronjob_controller.go
  • 旧版： controllers/cronjob_controller.go 或 pkg/controllers/cronjob_controller.go

如果你从 Kubebuilder v3.0.0+ 起使用 CLI 创建了所有 API，它们应出现在 PROJECT 文件的 resources 部分，例如：

resources:
  - api:
      crdVersion: v1
      namespaced: true
    controller: true
    group: batch
    kind: CronJob
    version: v1

3.2 创建每个 API 和控制器

对步骤 3.1 中识别的每个 API，重新搭建脚手架：

kubebuilder create api --group batch --version v1 --kind CronJob

出现提示时：

• 对 “Create Resource [y/n]” 回答 yes 以生成 API 类型
• 如果你的原项目对此 API 有控制器，对 “Create Controller [y/n]” 回答 yes

创建每个 API 后，更新生成的清单和代码：

make manifests  # Generate CRD, RBAC, and other config files
make generate   # Generate code (e.g., DeepCopy methods)

然后验证一切可以编译：

make build

这些步骤确保新搭建的 API 正确集成。有关 API 创建工作流的详细演练，请参见快速开始指南。

对项目中的所有 API 重复此过程。

创建所有资源后，重新生成清单：

make manifests
make generate

3.3 重新脚手架生成 Webhook（如适用）

如果原项目有 webhook，你需要重新搭建它们的脚手架。

识别备份项目中的 Webhook：

1. 从目录结构查找 webhook 文件：

   • 旧位置（v3 及更早）：api/v1/<kind>_webhook.go 或 api/<group>/<version>/<kind>_webhook.go
   • 当前位置（单 group）：internal/webhook/<version>/<kind>_webhook.go
   • 当前位置（多 group）：internal/webhook/<group>/<version>/<kind>_webhook.go

2. 从 PROJECT 文件（如可用）检查每个资源的 webhooks 部分：

resources:
  - api:
      ...
    webhooks:
      defaulting: true
      validation: true
      webhookVersion: v1

重新脚手架生成 Webhook：

对每个带有 Webhook 的资源运行：

kubebuilder create webhook --group batch --version v1 --kind CronJob --defaulting --programmatic-validation

Webhook 选项：

• --defaulting - 创建默认值 Webhook（设置默认值）
• --programmatic-validation - 创建校验 Webhook（校验创建/更新/删除操作）
• --conversion - 创建转换 Webhook（用于多版本 API，见下一节）

3.4 重新脚手架生成转换 Webhook（如适用）

如果你的项目有带 conversion webhook 的多版本 API，需要设置 hub-spoke 转换模式。

设置转换 Webhook：

为 hub 版本创建 conversion webhook，并使用 --spoke 标志指定 spoke 版本。

注意： 下面示例中使用 v1 作为 hub 仅作说明。请选择项目中应作为中心转换点的版本——通常是功能最完整且稳定的存储版本，不一定是最旧或最新的版本。

kubebuilder create webhook --group batch --version v1 --kind CronJob --conversion --spoke v2

该命令：

• 为作为 hub 版本的 v1 创建 conversion webhook
• 将 v2 配置为与 hub v1 相互转换的 spoke
• 生成带有转换方法存根的 *_conversion.go 文件

对于多个 spoke，将它们指定为逗号分隔的列表：

kubebuilder create webhook --group batch --version v1 --kind CronJob --conversion --spoke v2,v1alpha1

这将 v1 设为 hub，并将 v2 和 v1alpha1 都设为 spoke。

你需要实现的内容：

该命令会生成方法存根，你将在步骤 4 中填写：

• Hub 版本：实现 Hub() 方法（通常只是一个标记）
• Spoke 版本：实现带有转换逻辑的 ConvertTo(hub) 和 ConvertFrom(hub) 方法

有关实现转换逻辑的全面指导，请参见多版本教程。

搭建所有 webhook 脚手架后，验证一切可以编译：

make manifests && make build

步骤 4：Port Your Custom Code

将自定义业务逻辑和配置从备份手动移植到新项目。

4.1 移植 API 定义

比较并合并备份项目中的自定义 API 字段和标记。

需要对比的文件：

• 单 group： api/v1/<kind>_types.go
• 多 group： api/<group>/<version>/<kind>_types.go

需要移植的内容：

1. Spec 与 Status 结构体中的自定义字段
2. 验证标记 - 例如 +kubebuilder:validation:Minimum=0、+kubebuilder:validation:Pattern=...
3. CRD 生成标记 - 例如 +kubebuilder:printcolumn、+kubebuilder:resource:scope=Cluster
4. 子资源（SubResources） - 例如 +kubebuilder:subresource:status、+kubebuilder:subresource:scale
5. 文档注释 - 用于 CRD 描述

有关所有可用标记，请参见 CRD 生成、CRD 验证 和标记。

如果你的 API 引用了父包（例如 scheduling.GroupName），请移植它：

mkdir -p api/<group>/
cp ../migration-backup/apis/<group>/groupversion_info.go api/<group>/

移植 API 定义后，重新生成并验证：

make manifests  # Generate CRD manifests from your types
make generate   # Generate DeepCopy methods

这可确保在继续之前正确生成 API 类型和 CRD 清单。

4.2 移植控制器逻辑

需要对比的文件：

• 当前单 group： internal/controller/<kind>_controller.go
• 当前多 group： internal/controller/<group>/<kind>_controller.go

需要移植的内容：

1. Reconcile 函数实现 - 你的核心业务逻辑
2. 辅助函数 - 控制器文件中的任何额外函数
3. RBAC 标记 - +kubebuilder:rbac:groups=...,resources=...,verbs=...
4. 额外的 watch - SetupWithManager 中的自定义 watch 配置
5. 导入 - 控制器需要的任何额外包
6. 结构体字段 - 添加到 Reconciler 结构体的自定义字段

有关权限标记的详细信息，请参见 RBAC 标记。

移植控制器逻辑后，重新生成清单并验证编译：

make generate
make manifests
make build

4.3 移植 Webhook 实现

Webhook 在不同 Kubebuilder 版本之间位置有变化。请注意路径差异：

旧版 webhook 位置（Kubebuilder v3 及更早）：

• api/v1/<kind>_webhook.go
• api/<group>/<version>/<kind>_webhook.go

当前 Webhook 位置：

• 单 group：internal/webhook/<version>/<kind>_webhook.go
• 多 group：internal/webhook/<group>/<version>/<kind>_webhook.go

需要移植的内容：

1. Defaulting webhook - Default() 方法实现
2. Validation webhook - ValidateCreate()、ValidateUpdate()、ValidateDelete() 方法
3. Conversion webhook - ConvertTo() 和 ConvertFrom() 方法（用于多版本 API）
4. 辅助函数 - 任何验证或默认值辅助函数
5. Webhook 标记 - 通常自动生成，但请验证它们符合你的需求

有关详细信息，请参见 Webhook 概览、准入 Webhook 和多版本教程。

针对转换 Webhook：

如果你有 conversion webhook，请确保在步骤 3.4 中使用了 create webhook --conversion --spoke <version> 命令。这会自动设置 hub-spoke 基础设施。你只需在 spoke 版本的 ConvertTo() 和 ConvertFrom() 方法以及 hub 版本的 Hub() 方法中填写转换逻辑。

该命令会创建所有必要的样板代码——你只需实现版本之间字段转换的业务逻辑。

移植 Webhook 后，重新生成并验证：

make generate
make manifests
make build

4.4 移植 main.go 自定义内容（如有）

文件： cmd/main.go

大多数项目不需要自定义 main.go，因为 Kubebuilder 会自动处理所有标准设置（注册 API、设置控制器和 webhook、Manager 初始化、metrics 等）。

仅移植不属于标准脚手架的自定义内容。将备份的 main.go 与新搭建的文件比较，识别你添加的任何自定义逻辑。

4.5 配置 Kustomize 清单

config/ 目录包含用于部署 operator 的 Kustomize 清单。与备份比较，确保所有配置都已正确设置。

审查并更新这些目录：

1. config/default/kustomization.yaml - 主 kustomization 文件

   • 如果你有 webhook，确保启用了 webhook 配置（取消注释与 webhook 相关的 patches）
   • 如果使用 webhook，确保启用了 cert-manager（取消注释 certmanager 资源）
   • 根据原始配置启用或禁用 metrics 端点
   • 审查命名空间与名称前缀设置

2. config/manager/ - 控制器 Manager 部署

   • 除非有自定义，通常无需更改。如有自定义，请将资源 limits 和 requests 与备份比较，并检查环境变量

3. config/rbac/ - RBAC 配置

   • 通常由标记自动生成——无需手动更改
   • 仅在有标记未覆盖的自定义 role binding 或 service account 配置时检查

4. config/webhook/ - Webhook 配置（如适用）

   • 通常自动生成 - 无需手动更改
   • 仅在有自定义 webhook service 或证书配置时检查

5. config/samples/ - 示例 CR 清单

   • 从备份复制你的示例资源

配置 Kustomize 后，验证清单能正确构建：

make all
make build-installer

4.6 移植额外自定义内容

从备份移植任何额外的包、依赖和自定义内容：

额外包（例如 pkg/util）：

cp -r ../migration-backup/pkg/<package-name> pkg/
# 更新导入路径（适用于 macOS 和 Linux）
find pkg/ -name "*.go" -exec sed -i.bak 's|<module>/apis/|<module>/api/|g' {} \;
find pkg/ -name "*.go.bak" -delete

对于依赖，运行 go mod tidy，或对复杂项目从备份复制 go.mod/go.sum。

检查其他自定义内容（Makefile、Dockerfile、测试文件）。使用 diff 工具与备份比较，识别遗漏的文件。

移植所有自定义内容后，验证一切可以构建：

make all

步骤 5：Test and Verify

与备份比较，确保所有自定义内容都已正确移植，例如：

diff -r --brief ../migration-backup/ . | grep "Only in ../migration-backup"

运行测试并验证功能：

make test && make lint-fix

部署到测试集群（例如 kind）并验证更改（即验证预期行为、运行回归检查、确认完整 CI 流水线仍能通过，并执行 e2e 测试）。

其他资源

• 迁移概览 - 所有迁移选项的概览
• PROJECT 文件参考 - 理解 PROJECT 文件
• 基础项目包含什么？ - 理解项目结构
• Alpha Generate 命令 - 自动重新搭建脚手架
• Alpha Update 命令 - 自动迁移
• 使用外部类型 - 针对非本项目定义类型的控制器
• CRD 生成 - 从 Go 类型生成 CRD
• CRD 验证 - 为 API 添加验证
• 标记 - 代码生成的所有可用标记
• RBAC 标记 - 生成 RBAC 清单
• Webhook 概览 - 理解 webhook
• 准入 Webhook - 实现准入 webhook
• 多版本教程 - 处理多个 API 版本
• 部署 cert-manager - webhook 所需
• 配置 EnvTest - 使用 EnvTest 进行测试

使用 AI 将项目从任意版本迁移到最新版本

AI 可以通过减少重复工作并帮助解决破坏性变更来协助手动迁移。它不会取代手动迁移流程，但可以帮助减少工作量并达成目标。

工作流与 AI 辅助步骤

步骤 1：重组到新布局（仅旧布局需要）

AI 帮助确保项目按新布局组织（main.go 在 cmd/ 下，控制器和 webhook 在 internal/ 内）。审阅并验证重组，然后运行 make build 确保仍能编译。

参见步骤 1：重组到新布局

步骤 2：用于重新脚手架的发现 CLI 命令

AI 分析你的项目并生成使用最新版本完全重新搭建脚手架所需的所有 Kubebuilder CLI 命令。创建备份（mkdir ../migration-backup && cp -r . ../migration-backup/），然后执行生成的命令以搭建全新项目。

参见步骤 2：发现 CLI 命令

步骤 3：移植自定义代码

AI 帮助将自定义代码从备份移植到新搭建的项目。仔细审阅所有更改，确保业务逻辑正确转移。

参见 步骤 3：移植自定义代码

步骤 4：验证

运行 make generate && make manifests && make build，然后运行 make test 验证所有测试通过。部署到测试集群并验证你的方案仍能完成相同的工作。

完整详情请参见手动迁移流程。

步骤 1：Reorganize to New Layout (Required only for Legacy Layouts)

如果你的项目是用 Kubebuilder v3.0.0 之前的版本构建的，你可能需要此步骤。

重组文件以匹配新的目录布局。

检查是否需要此步骤（若以下任一为真，则需要）：

• 控制器不在 internal/controller/ 中
• Webhook 不在 internal/webhook/ 中
• main 不在 cmd/ 中

如果全部已在新布局中，跳到步骤 2

提供给 AI 助手的说明

将这些说明复制并粘贴给你的 AI 助手：

Reorganize Kubebuilder project files to match new directory layout.

CONTEXT:
- Project location: . (current directory - your existing project)
- Goal: Move files to new layout WITHOUT changing code or versions
- Keep project functional after reorganization

STEP 1 - Check which files need to move:
- Controllers in controllers/ or pkg/controllers/: needs move
- Controllers in internal/controller/ or internal/controller/<group>/ (multi-group): already correct
- Webhooks in api/v1/ or apis/<group>/v1/: needs move
- Webhooks in internal/webhook/v1/ or internal/webhook/<group>/v1/ (multi-group): already correct
- Main in root (main.go): needs move
- Main in cmd/ (cmd/main.go or cmd/*/main.go): already correct

STEP 2 - Reorganize file locations:

a. Move controllers if needed:
   - If controllers/ directory exists:
     mkdir -p internal/controller
     mv controllers/* internal/controller/
     rmdir controllers
   - If pkg/controllers/ directory exists:
     mkdir -p internal/controller
     mv pkg/controllers/* internal/controller/

b. Move webhooks if needed:
   - If api/v1/ or apis/v1/ contains *_webhook.go files:
     mkdir -p internal/webhook/v1
     mv api/v1/*_webhook* internal/webhook/v1/ 2>/dev/null || mv apis/v1/*_webhook* internal/webhook/v1/ 2>/dev/null || true
   - If api/<group>/v1/ or apis/<group>/v1/ contains webhooks (multi-group):
     mkdir -p internal/webhook/<group>/v1
     mv api/<group>/v1/*_webhook* internal/webhook/<group>/v1/ 2>/dev/null || mv apis/<group>/v1/*_webhook* internal/webhook/<group>/v1/ 2>/dev/null || true

c. Move main.go if needed:
   - If main.go exists in root:
     mkdir -p cmd
     mv main.go cmd/

STEP 3 - Update import paths in ALL files:

After moving files, imports will break. Fix them systematically:

a. In cmd/main.go (or cmd/*/main.go, cmd/*/*.go):
   - Find: import "your-module/controllers"
   - Replace with: import "your-module/internal/controller"
   - Find: import "your-module/pkg/controllers"
   - Replace with: import "your-module/internal/controller"
   - Find: &controllers.SomeReconciler or controllers.NewController
   - Replace with: &controller.SomeReconciler or controller.NewController
   - API imports (api/v1, apis/v1alpha1) - NO CHANGE needed

b. In internal/controller/*.go files:
   - Check package declaration is still: package controller (not controllers)
   - API imports stay same - NO CHANGE needed
   - If you had controller-to-controller imports, update paths

c. In internal/webhook/v1/*.go files:
   - Check package declaration: should be package v1
   - API imports stay same - NO CHANGE needed
   - Webhook imports in main.go may need updating

STEP 4 - Update Dockerfile (if using explicit COPY):

Check Dockerfile for explicit COPY statements. If found, update:

Old pattern:
    COPY cmd/main.go cmd/main.go
    COPY api/ api/
    COPY internal/controller/ internal/controller/

Option 1 - Simplify (recommended):
    COPY . .

Ensure .dockerignore has:
    **
    !go.mod
    !go.sum
    !**/*.go
    **/*_test.go

Note: Podman does not honor the !**/*.go re-include
(https://github.com/containers/buildah/issues/6417). If the project is built
with Podman, also re-include the source directories by name:
    !cmd
    !api
    !internal

Option 2 - Update explicit paths:
    COPY cmd/ cmd/
    COPY api/ api/
    COPY internal/ internal/

STEP 5 - Verify reorganization:

- Run: go mod tidy
- Run: make generate
- Run: make manifests
- Run: make build
- Run: make test

If errors, fix import paths.

Success: new layout, make build succeeds, make test passes, project functional

作用说明

AI 将会：

1. 移动文件到新布局（controllers/ 到 internal/controller/，webhooks 到 internal/webhook/，main.go 到 cmd/）
2. 移动后在所有文件中修复 import 路径
3. 验证重组后的项目能够构建且测试通过

完成此步骤后，你的项目使用新布局（相同代码，新位置），使迁移简单得多！

后续步骤

AI 重组之后：

1. 验证：make build && make test（在当前项目中）
2. 如果成功，备份并继续到步骤 2：发现 CLI 命令
3. 如有错误，先审查并修复再继续

步骤 2：Discovery CLI Commands

使用 AI 分析你（现已重组）的 Kubebuilder 项目，并生成用最新版本重建它所需的所有 CLI 命令。

提供给 AI 助手的说明

将这些说明复制并粘贴给你的 AI 助手（Cursor、Claude、GitHub Copilot 等）：

Analyze this Kubebuilder project and generate all CLI commands to recreate it.

CONTEXT:
Kubebuilder projects have these components:

APIs (Custom Resources):
- Location: api/ or apis/ directory
- Recognition: Look for Go structs with marker: // +kubebuilder:object:root=true
- Pattern: type <Name> struct with metav1.TypeMeta and metav1.ObjectMeta fields
- Example: type Captain struct { metav1.TypeMeta; metav1.ObjectMeta; Spec CaptainSpec; Status CaptainStatus }

Controllers:
- Location: controllers/, internal/controller/, or pkg/controllers/
- Recognition: Look for Reconcile() function signature
- Pattern: func (r *<Name>Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
- Struct embeds: client.Client
- Has function: SetupWithManager(mgr ctrl.Manager) error

Webhooks:
- Location: api/v1/ or internal/webhook/v1/
- Recognition: Look for webhook method signatures
- Defaulting pattern: func Default() or func Default(ctx context.Context, obj *<Type>) error
- Validation pattern: func ValidateCreate() error or func ValidateCreate(ctx context.Context, obj *<Type>) (admission.Warnings, error)
- Conversion pattern: func Hub() or func ConvertTo() or func ConvertFrom()

CLI Command Formats:
- kubebuilder init --domain <domain> --repo <module>
- kubebuilder edit --multigroup=true (if multi-group layout)
- kubebuilder create api --group <group> --version <version> --kind <Kind> --controller=<bool> --resource=<bool>
  * --controller=true: create controller
  * --resource=true: create API definition
  * --resource=false: controller only (for external types like Deployment, Pod)
- kubebuilder create webhook --group <group> --version <version> --kind <Kind> [flags]
  * --defaulting: sets default values
  * --programmatic-validation: validates create/update/delete
  * --conversion --spoke <versions>: for multi-version APIs (hub-spoke pattern)
    - Hub version: Usually oldest stable version (e.g., v1) - command runs on this version
    - Spoke versions: Newer versions that convert to/from hub (e.g., v2, v3) - specified with --spoke
    - Example: --group crew --version v1 --kind Captain --conversion --spoke v2
      (v1 is hub, v2 is spoke)
- External types (k8s.io/api/*): use --resource=false --controller=true

Project structure patterns:
- Single-group: api/v1/, api/v2/ (versions directly under api/)
- Multi-group: api/<group>/v1/, api/<group>/v2/ (group subdirectories)
- Multi-group detection: Check PROJECT file for "multigroup: true" OR check if api/ has group subdirectories

Files to IGNORE:
- zz_generated.*.go (auto-generated code)
- groupversion_info.go (just group registration)
- config/crd/bases/*.yaml (auto-generated from code)
- config/rbac/*.yaml (auto-generated from markers)

References:
- Kubebuilder Book: ../introduction.md
- controller-runtime: https://github.com/kubernetes-sigs/controller-runtime
- controller-tools: https://github.com/kubernetes-sigs/controller-tools

ANALYZE PROJECT:

1. Extract module path from go.mod (line 1: "module <path>")
2. Extract domain from PROJECT file (domain: <value>) OR api/*/groupversion_info.go (// +groupName=<group>.<domain>)
3. Detect multi-group: api/ has api/<group>/v1/ structure? (yes/no)

4. Scan api/ or apis/ directory - Find ALL your own APIs:
   - Find all *_types.go files OR types.go (exclude groupversion_info.go, zz_generated.deepcopy.go)
   - For each file, find: type <Kind> struct with // +kubebuilder:object:root=true above it
   - Extract: Kind name, group (from groupversion_info.go +groupName comment), version (from directory)
   - Check controller: look for controllers/<lowercaseKind>_controller.go OR internal/controller/<lowercaseKind>_controller.go OR pkg/controllers/<lowercaseKind>_controller.go
   - Check webhooks: look for api/v1/<lowercaseKind>_webhook.go OR internal/webhook/v1/<lowercaseKind>_webhook.go
   - If webhook file found, scan for methods:
     * "func (r *<Kind>) Default()": has --defaulting
     * "func (r *<Kind>) ValidateCreate()": has --programmatic-validation
     * "func (*<Kind>) Hub()": this version is conversion hub
     * "func (r *<Kind>) ConvertTo(": this version is a spoke

5. Scan internal/controller/, controllers/, or pkg/controllers/ - Find controllers for external types:
   - For each *_controller.go file, check imports NOT from your module
   - Look for: k8s.io/api/apps/v1, k8s.io/api/core/v1, github.com/cert-manager/cert-manager/pkg/apis/*
   - Extract type from: type <Kind>Reconciler struct OR Reconcile signature
   - This is a controller-only resource (use --controller=true --resource=false)

6. Scan internal/webhook/ - Find webhooks for external types:
   - For each *_webhook.go file in internal/webhook/v1/ (or other versions)
   - Check if the Kind type is imported (not defined in your api/)
   - If imported from k8s.io/api/* or external package: external type webhook
   - Scan for Default() and ValidateCreate() methods to determine flags

OUTPUT FORMAT (bash script):

#!/bin/bash
# Module: <module-path>
# Domain: <domain>
# Multi-group: <yes/no>

set -e
kubebuilder init --domain <domain> --repo <module-path>
kubebuilder edit --multigroup=true  # only if multi-group

# External type controllers (--resource=false)
kubebuilder create api --group cert-manager --version v1 --kind Certificate \
  --controller=true --resource=false \
  --external-api-path=<path> --external-api-domain=<domain> --external-api-module=<module>

# Your own APIs (--resource=true)
kubebuilder create api --group crew --version v1 --kind Captain --controller=true --resource=true
kubebuilder create api --group crew --version v2 --kind FirstMate --controller=false --resource=true

# Webhooks for your own APIs
kubebuilder create webhook --group crew --version v1 --kind Captain --defaulting --programmatic-validation
kubebuilder create webhook --group crew --version v1 --kind FirstMate --conversion --spoke v2

# Webhooks for external/core types (no create api needed)
kubebuilder create webhook --group apps --version v1 --kind Deployment --defaulting --programmatic-validation
kubebuilder create webhook --group core --version v1 --kind Pod --defaulting

make manifests && make generate && make build

RULES:
- Combine ALL webhook types in ONE command: --defaulting --programmatic-validation together
- Conversion webhooks: use hub version and list ALL spokes: --conversion --spoke v2,v3
- List EVERY Kind found in source code, not just what is in PROJECT file
- External type controllers: use --controller=true --resource=false
- Webhooks for external/core types: just create webhook (no create api needed)
- Order: external controllers first, then your APIs, then all webhooks

理解输出

AI 将分析你的项目并输出一个 bash 脚本。脚本将按此顺序包含命令：

1. kubebuilder init - 初始化项目
2. kubebuilder edit --multigroup=true - If multi-group detected
3. kubebuilder create api - 用于外部类型控制器（带 --resource=false）
4. kubebuilder create api - 用于你自己的 API（带 --resource=true）
5. kubebuilder create webhook - 用于所有 Webhook
6. make manifests && make generate && make build - Verify

示例输出

以下是 AI 说明生成内容的真实示例：

示例 1：简单多 group 项目

已分析：kubernetes-sigs/scheduler-plugins

#!/bin/bash
# Module: sigs.k8s.io/scheduler-plugins
# Domain: scheduling.x-k8s.io
# Multi-group: YES

set -e
kubebuilder init --domain scheduling.x-k8s.io --repo sigs.k8s.io/scheduler-plugins
kubebuilder edit --multigroup=true

kubebuilder create api --group scheduling --version v1alpha1 --kind ElasticQuota --controller=true --resource=true
kubebuilder create api --group scheduling --version v1alpha1 --kind PodGroup --controller=true --resource=true

make manifests && make generate && make build

已发现： 2 个 API，多 group，无 Webhook

示例 2：带 webhook 的单 group（go/v3 迁移）

已分析：project-v3

#!/bin/bash
# Module: sigs.k8s.io/kubebuilder/testdata/project-v3
# Domain: testproject.org
# Multi-group: NO

set -e
kubebuilder init --domain testproject.org --repo sigs.k8s.io/kubebuilder/testdata/project-v3

kubebuilder create api --group crew --version v1 --kind Captain --controller=true --resource=true
kubebuilder create api --group crew --version v1 --kind FirstMate --controller=true --resource=true
kubebuilder create api --group crew --version v1 --kind Admiral --controller=true --resource=true

kubebuilder create webhook --group crew --version v1 --kind Captain --defaulting --programmatic-validation
kubebuilder create webhook --group crew --version v1 --kind Admiral --defaulting

make manifests && make generate && make build

已发现： 3 个 API，单 group，带 defaulting 和 validation 的 webhook

示例 3：带外部类型的复杂多 group

已分析：testdata/project-v4-multigroup

#!/bin/bash
# Module: sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup
# Domain: testproject.org
# Multi-group: YES

set -e
kubebuilder init --domain testproject.org --repo sigs.k8s.io/kubebuilder/testdata/project-v4-multigroup
kubebuilder edit --multigroup=true

# External type controllers
kubebuilder create api --group cert-manager --version v1 --kind Certificate \
  --controller=true --resource=false \
  --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 \
  --external-api-domain=io \
  --external-api-module=github.com/cert-manager/cert-manager@v1.19.2
kubebuilder create api --group apps --version v1 --kind Deployment --controller=true --resource=false

# APIs - Group: crew
kubebuilder create api --group crew --version v1 --kind Captain --controller=true --resource=true

# APIs - Group: ship
kubebuilder create api --group ship --version v1beta1 --kind Frigate --controller=true --resource=true
kubebuilder create api --group ship --version v1 --kind Destroyer --controller=true --resource=true
kubebuilder create api --group ship --version v2alpha1 --kind Cruiser --controller=true --resource=true

# APIs - Group: sea-creatures
kubebuilder create api --group sea-creatures --version v1beta1 --kind Kraken --controller=true --resource=true
kubebuilder create api --group sea-creatures --version v1beta2 --kind Leviathan --controller=true --resource=true

# APIs - Group: foo.policy
kubebuilder create api --group foo.policy --version v1 --kind HealthCheckPolicy --controller=true --resource=true

# APIs - Group: foo
kubebuilder create api --group foo --version v1 --kind Bar --controller=true --resource=true

# APIs - Group: fiz
kubebuilder create api --group fiz --version v1 --kind Bar --controller=true --resource=true

# APIs - Group: example.com
kubebuilder create api --group example.com --version v1alpha1 --kind Memcached --controller=true --resource=true
kubebuilder create api --group example.com --version v1alpha1 --kind Busybox --controller=true --resource=true
kubebuilder create api --group example.com --version v1 --kind Wordpress --controller=true --resource=true
kubebuilder create api --group example.com --version v2 --kind Wordpress --controller=false --resource=true

# Webhooks for your APIs
kubebuilder create webhook --group crew --version v1 --kind Captain --defaulting --programmatic-validation
kubebuilder create webhook --group ship --version v1 --kind Destroyer --defaulting
kubebuilder create webhook --group ship --version v2alpha1 --kind Cruiser --programmatic-validation
kubebuilder create webhook --group example.com --version v1alpha1 --kind Memcached --programmatic-validation
kubebuilder create webhook --group example.com --version v1 --kind Wordpress --conversion --spoke v2

# Webhooks for external types
kubebuilder create webhook --group cert-manager --version v1 --kind Issuer --defaulting
kubebuilder create webhook --group core --version v1 --kind Pod --programmatic-validation
kubebuilder create webhook --group apps --version v1 --kind Deployment --defaulting --programmatic-validation

make manifests && make generate && make build

已发现： 跨 6 个 group 的 12 个 API、conversion webhook、外部控制器、外部 webhook

接下来做什么

1. 仔细审阅生成的脚本，确保它与你的项目结构匹配。
2. 将其保存为 migration-commands.sh 并使其可执行：chmod +x migration-commands.sh
3. 按手动迁移流程操作：
   • 将项目备份到其他位置
   • 在项目根目录为空时执行此脚本中的命令
   • 在获得完全重新搭建脚手架的项目后，你需要把所有代码重新加回去
   • 移植你的自定义代码

步骤 3：Port Custom Code

在重组项目（步骤 1）并执行发现步骤中的脚手架命令（步骤 2）之后，使用 AI 将自定义代码移植到新项目。

提供给 AI 助手的说明

将这些说明复制并粘贴给你的 AI 助手：

Port custom code from Kubebuilder project backup to new scaffolded project.

CONTEXT:
What is scaffold vs custom:
- Scaffold: Auto-generated boilerplate by Kubebuilder (has "// TODO(user):" comments)
- Custom: Your business logic that replaces TODOs

Backup location: ../migration-backup/ (your old project with custom code)
New project: . (newly scaffolded project with TODOs to replace)

How to recognize each file type (by content, not just name):

API files (typically *_types.go):
- Have marker: // +kubebuilder:object:root=true
- Have structs: type <Name> struct with metav1.TypeMeta, metav1.ObjectMeta
- Have: <Name>Spec struct (desired state)
- Have: <Name>Status struct (observed state)
- Markers like: // +kubebuilder:validation:...

Controller files (typically *_controller.go):
- Have struct: type <Name>Reconciler struct { client.Client; Scheme *runtime.Scheme }
- Have function: func (r *<Name>Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
- Have function: func (r *<Name>Reconciler) SetupWithManager(mgr ctrl.Manager) error
- May have: // +kubebuilder:rbac markers before Reconcile

Webhook files (typically *_webhook.go):
- OLD pattern: func (r *<Name>) Default(), func (r *<Name>) ValidateCreate() error
- NEW pattern: type <Name>Defaulter struct, func (d *<Name>Defaulter) Default(ctx context.Context, obj *<Name>) error
- Conversion: func (*<Name>) Hub(), func (r *<Name>) ConvertTo(...), func (r *<Name>) ConvertFrom(...)

Main file:
- Has: func main()
- Has: ctrl.NewManager(...)
- Registers controllers and webhooks

File paths after Step 1:
- APIs in: api/v1/ or api/<group>/v1/
- Controllers in: internal/controller/ or internal/controller/<group>/
- Webhooks in: internal/webhook/v1/ or internal/webhook/<group>/v1/
- Main: cmd/main.go

Files to NEVER edit (auto-generated):
- config/crd/bases/*.yaml (generated from make manifests)
- config/rbac/role.yaml (generated from make manifests)
- config/webhook/manifests.yaml (generated from make manifests)
- **/zz_generated.*.go (generated from make generate)
- PROJECT file (managed by CLI)

Critical markers to NEVER remove:
- // +kubebuilder:scaffold:* (Kubebuilder injects code here)

Make command sequence:
- After editing APIs or markers: make generate && make manifests
- After editing Go code: make build
- After all changes: make lint-fix && make generate && make manifests && make all && make test

Common markers in API files:
- // +kubebuilder:validation:Required
- // +kubebuilder:validation:Minimum=1
- // +kubebuilder:validation:Pattern="^[a-z]+$"
- // +kubebuilder:printcolumn:name="Status",type=string,JSONPath=...

RBAC markers in controller files:
- // +kubebuilder:rbac:groups=<group>,resources=<resource>,verbs=get;list;watch;create;update;patch;delete
- // +kubebuilder:rbac:groups=<group>,resources=<resource>/status,verbs=get;update;patch
- // +kubebuilder:rbac:groups=<group>,resources=<resource>/finalizers,verbs=update

References:
- Kubebuilder Book: ../introduction.md
- Markers Reference: ../reference/markers.md
- controller-runtime: https://github.com/kubernetes-sigs/controller-runtime
- controller-tools: https://github.com/kubernetes-sigs/controller-tools

PORT CUSTOM CODE (in this order):

1. Port go.mod dependencies FIRST:

   Compare ../migration-backup/go.mod with current go.mod

   a. For packages in backup but NOT in new (exclude k8s.io/*, sigs.k8s.io/controller-*):
      - Run: go get <package>@<version>

   b. For packages in BOTH with different versions:
      - Keep the HIGHER (newer) version
      - If backup has newer version: go get <package>@<newer-version>
      - If new scaffold has newer version: keep it (do not downgrade)
      - NOTE: Old projects can have newer versions than scaffold

   After ALL: run go mod tidy

2. Port API type definitions:

   For each *_types.go in backup to new (paths match after Step 1):
   Backup: ../migration-backup/api/v1/<kind>_types.go
   New: api/v1/<kind>_types.go

   Port:
   - Custom fields in Spec and Status structs
   - ALL +kubebuilder markers (validation, printcolumn, resource, etc.)
   - Documentation comments
   - Custom types (enums, type aliases)
   - REMOVE "// TODO(user):" comments when adding fields

   NEVER remove: // +kubebuilder:scaffold:* or // +kubebuilder:object:root=true

   After each: go mod tidy && make generate && make manifests

3. Port controller implementations:

   For each controller (paths match after Step 1):
   Backup: ../migration-backup/internal/controller/<kind>_controller.go
   New: internal/controller/<kind>_controller.go

   Port in order:
   a. Additional imports (ADD to existing)
   b. Custom constants, variables, types, interfaces (before Reconciler struct)
   c. Custom fields in <Kind>Reconciler struct
   d. ALL +kubebuilder:rbac markers (place before Reconcile)
   e. Reconcile() body (REMOVE "// TODO(user):" and paste custom logic)
   f. ALL helper functions (closures and standalone)
   g. SetupWithManager customizations (if any beyond default .For().Named().Complete())

   After each: go mod tidy && make generate && make manifests && make build

4. Port webhooks:

   CRITICAL: Code pattern depends on controller-runtime version!

   Webhooks (paths match after Step 1):
   Backup: ../migration-backup/internal/webhook/v1/<kind>_webhook.go
   New: internal/webhook/v1/<kind>_webhook.go

   Detect pattern by reading backup file:
   - Has "func (r *<Kind>) Default() {": OLD pattern (needs adaptation)
   - Has "func (d *<Kind>Defaulter) Default(ctx": NEW pattern (direct copy)

   IF OLD pattern - ADAPT:
   - Default(): Extract logic, paste after type assertion, change 'r.' to '<kind>.', add return nil, REMOVE TODO
   - Validate*(): Extract logic, paste after assertion, change 'r.' to '<kind>.', change return types, REMOVE TODO
   - Conversion: Copy Hub/ConvertTo/ConvertFrom directly (no change needed)

   IF NEW pattern - DIRECT COPY:
   - Copy Defaulter/Validator structs and all methods
   - Copy helper functions and imports

   After each: go mod tidy && make manifests && make build

5. Port main.go customizations:

   Backup: ../migration-backup/cmd/main.go
   New: cmd/main.go

   Compare and port ONLY custom additions:
   - Custom manager options
   - Custom command-line flags
   - Custom initialization before mgr.Start()
   - Additional scheme registrations

   DO NOT port standard scaffold (controller/webhook setup, manager config)

   After: make build

6. Port config settings (ADAPT, do not copy):

   a. config/default/kustomization.yaml - Compare and adapt:
      - Uncomment webhook/certmanager if you have webhooks
      - Update namespace/namePrefix if custom
      - Match metrics configuration
      - Add custom patches/resources
      DO NOT copy entire file

   b. Other config/*/kustomization.yaml - Check for custom patches, adapt if needed

   c. Custom config dirs - Copy any additional dirs: config/dev/, config/prod/, etc.

   After: make build-installer

7. Port config samples and customizations:
   - Sample CRs: Copy ../migration-backup/config/samples/*.yaml to config/samples/
   - Makefile: Copy custom targets from backup (preserve scaffolded targets)
   - Dockerfile: Apply custom build steps from backup

8. Port ALL tests:
   - Controller tests: Copy *_controller_test.go from backup
   - Webhook tests: Copy *_webhook_test.go (adapt if pattern changed)
   - E2E tests: Copy test/e2e/* if exist
   - Integration tests: Copy test/integration/* if exist

9. Port additional files:
   - README: Port custom sections (do not replace entire file)
   - Additional dirs: Copy docs/, scripts/, examples/, charts/, testdata/ if exist
   - Root files: Copy .env, VERSION, CHANGELOG.md, CONTRIBUTING.md if exist
   - .github workflows: Copy custom workflows

   DO NOT port: dist/, bin/, vendor/

10. Verify nothing missed:
   - Run: diff -r --brief ../migration-backup/ . | grep "Only in ../migration-backup"
   - Port any custom files found (ignore: .git/, bin/, vendor/, dist/, zz_generated.*, go.sum, auto-gen configs)
   - Verify key files have custom code (APIs, controllers, webhooks)

11. Final verification:
   - Run: go mod tidy
   - Run: make lint-fix
   - Run: make generate
   - Run: make manifests
   - Run: make build
   - Run: make build-installer
   - Run: make test

   Success: no errors, tests pass, functionally identical to backup

IMPORTANT REMINDERS:
- NEVER edit auto-generated files (already listed in CONTEXT above)
- NEVER remove // +kubebuilder:scaffold:* comments
- REMOVE "// TODO(user):" when replacing with custom code
- ADAPT config YAML files, do not copy entire files
- Port EVERYTHING except: .git/, bin/, vendor/, dist/, zz_generated.*, go.sum
- Follow make command sequence from CONTEXT above

AI 将做什么

AI 将会：

1. 检测布局 — 比较新旧项目结构
2. 移植 API 定义 — 自定义字段、markers、文档
3. 移植 controller 逻辑 — Imports、类型、Reconcile()、helpers、RBAC、SetupWithManager
4. 适配 webhooks — 必要时处理模式变更，移植全部逻辑与 helpers
5. 移植 main.go — 仅自定义初始化、flags 与 manager 选项
6. 移植配置 — kustomization.yaml、samples、Makefile、Dockerfile
7. 移植依赖 — 向 go.mod 添加包，运行 go mod tidy
8. 移植测试 — Controller 测试、webhook 测试、e2e 测试、集成测试
9. 移植其他文件 — README、docs/、scripts/、.github/ 及任何自定义目录
10. 完整验证 — 运行 lint-fix、generate、manifests、build、test

AI 完成后

关键：请仔细审查！

示例：会移植哪些内容

API 自定义字段

来自备份（api/v1/captain_types.go）：

type CaptainSpec struct {
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=100
    Replicas int32 `json:"replicas"`

    // +kubebuilder:validation:Pattern=`^[a-z]+$`
    Name string `json:"name"`
}

到新项目（TODO 已移除，自定义字段已添加）：

type CaptainSpec struct {
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=100
    Replicas int32 `json:"replicas"`

    // +kubebuilder:validation:Pattern=`^[a-z]+$`
    Name string `json:"name"`
}

控制器协调逻辑

来自备份（Reconcile 函数体）：

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

    // Your custom reconciliation logic here
    var captain crewv1.Captain
    if err := r.Get(ctx, req.NamespacedName, &captain); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // Custom business logic...

    return ctrl.Result{}, nil
}

到新项目（TODO 已移除，自定义逻辑已添加）：

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

    // Custom reconciliation logic from backup
    var captain crewv1.Captain
    if err := r.Get(ctx, req.NamespacedName, &captain); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // Custom business logic...

    return ctrl.Result{}, nil
}

Webhook 适配（v3 到 v4）

来自 go/v3 备份：

func (r *Captain) Default() {
    if r.Spec.Replicas == 0 {
        r.Spec.Replicas = 1
    }
}

到 go/v4 新项目：

func (d *CaptainDefaulter) Default(ctx context.Context, obj *crewv1.Captain) error {
    // 已移植并适配的逻辑（obj 是类型安全的，无需断言）：
    if obj.Spec.Replicas == 0 {
        obj.Spec.Replicas = 1
    }

    return nil
}

后续步骤

AI 移植你的代码后：

1. 检查是否有遗漏、损坏或错误移植
2. 部署到测试集群 - 验证行为

单组到多组

Kubebuilder 默认脚手架单 group 项目以保持简单，因为多数项目不需要多个 API groups。但需要时，可将现有单 group 项目转换为多 group 布局。这会将 API 与 controllers 重组到按 group 划分的目录中。

此设计决策的理由见设计文档。

理解布局

从单 group 到多 group 时会发生这些变化：

单 group 布局（默认）：

api/<version>/*_types.go                  All your CRD schemas in one place
internal/controller/*                     All your controllers together
internal/webhook/<version>/*              Webhooks organized by version (if you have any)

多 group 布局：

api/<group>/<version>/*_types.go          CRD schemas organized by group
internal/controller/<group>/*             Controllers organized by group
internal/webhook/<group>/<version>/*      Webhooks organized by group and version (if you have any)

可通过检查 PROJECT 文件中的 multigroup: true 判断当前布局。

迁移

下列步骤将 CronJob 示例 从单 group 迁移到多 group 布局。

步骤 1：Enable multi-group mode

首先，告诉 Kubebuilder 你要使用多 group 布局：

kubebuilder edit --multigroup=true

该命令通过添加 multigroup: true 更新 PROJECT 文件。此变更之后：

• 你创建的新 API 将自动使用多 group 结构（api/<group>/<version>/）
• 现有 API 仍在当前位置，必须手动迁移（见下面步骤 3–9）

步骤 2：Identify your group name

查看 api/v1/groupversion_info.go 以找到 group 名称：

// +组名=batch.tutorial.kubebuilder.io
package v1

Group 名称是点号前的第一部分（本例中为 batch）。

步骤 3：Move your APIs

为 group 创建目录并移动 version 目录：

mkdir -p api/batch
mv api/v1 api/batch/

若有多个版本（如 v1、v2 等），全部移动：

mv api/v2 api/batch/

步骤 4：Move your controllers

创建 group 目录并移动所有 controller 文件：

mkdir -p internal/controller/batch
mv internal/controller/*.go internal/controller/batch/

这会将包括 suite_test.go 在内的所有 controller 文件移入 group 目录。每个 group 需要自己的测试套件。

步骤 5：Move your webhooks (if you have any)

若项目有 webhooks（检查是否有 internal/webhook/ 目录），添加 group 目录：

mkdir -p internal/webhook/batch
mv internal/webhook/v1 internal/webhook/batch/
mv internal/webhook/v2 internal/webhook/batch/  # if v2 exists

如果您没有 webhook，可以跳过这一部分。

步骤 6：Update import paths

将所有 import 语句更新为指向新位置。

以前如下所示：

import (
    batchv1 "tutorial.kubebuilder.io/project/api/v1"
    "tutorial.kubebuilder.io/project/internal/controller"
)

现在应如下所示：

import (
    batchv1 "tutorial.kubebuilder.io/project/api/batch/v1"
    batchcontroller "tutorial.kubebuilder.io/project/internal/controller/batch"
)

若有 webhooks，还需要更新这些 imports：

// Before
webhookv1 "tutorial.kubebuilder.io/project/internal/webhook/v1"

// After
webhookbatchv1 "tutorial.kubebuilder.io/project/internal/webhook/batch/v1"

需要检查并更新的文件：

• cmd/main.go
• internal/controller/batch/*.go
• internal/webhook/batch/v1/*.go（若有 Webhook）
• api/batch/v1/*_test.go

提示：在整个项目中使用 IDE 的 “Find and Replace” 功能。

步骤 7：Update the PROJECT file

kubebuilder edit --multigroup=true 命令会在 PROJECT 文件中设置 multigroup: true，但不会更新现有 API 的路径。你需要手动更新每个资源的 path 字段。

验证你的 PROJECT 文件包含这些变更：

1. 检查已设置 multigroup: true（在顶层）：

layout:
- go.kubebuilder.io/v4
多组: true  # Must be true
projectName: project

2. 为每个资源更新 path 字段：

Before:

resources:
- api:
    crdVersion: v1
    namespaced: true
  controller: true
  group: batch
  kind: CronJob
  path: tutorial.kubebuilder.io/project/api/v1  # 旧路径
  version: v1

After:

resources:
- api:
    crdVersion: v1
    namespaced: true
  controller: true
  group: batch
  kind: CronJob
  path: tutorial.kubebuilder.io/project/api/batch/v1  # 带 group 的新路径
  version: v1

对 PROJECT 文件中的所有资源重复此操作。

步骤 8：Update test suite CRD paths

更新测试套件中的 CRD 目录路径。由于文件下移了一层，路径需再加一层 ".."。

在 internal/controller/batch/suite_test.go 中：

之前（位于 internal/controller/suite_test.go）：

testEnv = &envtest.Environment{
    CRDDirectoryPaths: []string{filepath.Join("..", "..", "config", "crd", "bases")},
}

之后（现位于 internal/controller/batch/suite_test.go）：

testEnv = &envtest.Environment{
    CRDDirectoryPaths: []string{filepath.Join("..", "..", "..", "config", "crd", "bases")},
}

若有 webhooks，更新 internal/webhook/batch/v1/webhook_suite_test.go：

之前（位于 internal/webhook/v1/webhook_suite_test.go）：

testEnv = &envtest.Environment{
    CRDDirectoryPaths: []string{filepath.Join("..", "..", "..", "config", "crd", "bases")},
}

之后（现位于 internal/webhook/batch/v1/webhook_suite_test.go）：

testEnv = &envtest.Environment{
    CRDDirectoryPaths: []string{filepath.Join("..", "..", "..", "..", "config", "crd", "bases")},
}

步骤 9：Verify the migration

运行下列命令验证一切正常：

make manifests      # Regenerate CRDs and RBAC
make generate       # Regenerate code
make test           # Run tests
make build          # Build the project

AI 辅助迁移

若使用 AI 编码助手（Cursor、GitHub Copilot 等），可自动化大部分迁移步骤。

迁移到命名空间作用域 Manager

本指南介绍如何将现有集群作用域项目转换为 Namespace 作用域部署。

默认情况下，Kubebuilder 脚手架集群作用域的 managers，可监视并管理所有 namespaces 中的资源。本指南说明如何将现有集群作用域项目转换为 Namespace 作用域部署，使 manager 仅监视特定 namespace(s)。

何时使用命名空间作用域

在以下情况使用命名空间作用域：

• 在多租户集群中构建租户专用 managers
• 安全策略要求最小权限（无集群范围权限）
• 需要在不同 namespaces 中运行多个 manager 实例
• 仅管理 Namespace 作用域资源（Deployments、Services、ConfigMaps 等）

在以下情况使用集群作用域（默认）：

• 管理集群作用域资源（Nodes、ClusterRoles、Namespaces 等）
• 单个 manager 实例管理所有 namespaces 中的资源

迁移

快速摘要：

1. 运行 kubebuilder edit --namespaced --force — 脚手架 Role/RoleBinding 并更新 manager.yaml
2. 更新 cmd/main.go 以配置 Namespace 作用域缓存
3. 在现有 controller 文件的 RBAC markers 中添加 namespace= 参数
4. 运行 make manifests — 根据更新后的 markers 重新生成 RBAC
5. 验证并部署

详细步骤

1. 启用命名空间作用域模式

kubebuilder edit --namespaced --force

该命令会自动：

• 在 PROJECT 文件中设置 namespaced: true
• 脚手架 kind: Role（Namespace 作用域）的 config/rbac/role.yaml
• 脚手架 kind: RoleBinding 的 config/rbac/role_binding.yaml
• 重新生成带有 WATCH_NAMESPACE 环境变量的 config/manager/manager.yaml
• 为所有现有 API 重新生成 kind: Role（Namespace 作用域）的 admin/editor/viewer roles

注意： --force 标志会重新生成 config/manager/manager.yaml。不带 --force 时，必须手动添加 WATCH_NAMESPACE（见下文）。

2. 更新 cmd/main.go（必需的手动步骤）

edit 命令无法自动更新 cmd/main.go。你必须手动添加 Namespace 作用域配置。

a. 添加 import：

import (
    // ... 现有导入 ...
    "sigs.k8s.io/controller-runtime/pkg/cache"
)

b. 添加辅助函数（在 init() 之后、main() 之前）：

// getWatchNamespace 返回 Manager 应监视变更的命名空间。
// 它从 WATCH_NAMESPACE 环境变量读取该值。
func getWatchNamespace() (string, error) {
    watchNamespaceEnvVar := "WATCH_NAMESPACE"
    ns, found := os.LookupEnv(watchNamespaceEnvVar)
    if !found {
        return "", fmt.Errorf("%s must be set", watchNamespaceEnvVar)
    }
    return ns, nil
}

// setupCacheNamespaces 配置缓存以监视特定命名空间。
func setupCacheNamespaces(namespaces string) cache.Options {
    defaultNamespaces := make(map[string]cache.Config)
    for _, ns := range strings.Split(namespaces, ",") {
        defaultNamespaces[strings.TrimSpace(ns)] = cache.Config{}
    }
    return cache.Options{
        DefaultNamespaces: defaultNamespaces,
    }
}

c. 在 main() 函数中，于 ctrl.NewManager() 之前添加：

// 从 WATCH_NAMESPACE 环境变量获取命名空间作用域模式的命名空间。
watchNamespace, err := getWatchNamespace()
if err != nil {
    setupLog.Error(err, "Unable to get WATCH_NAMESPACE")
    os.Exit(1)
}

d. 更新 manager 创建以使用 Namespace 作用域缓存：

mgrOptions := ctrl.Options{
    Scheme:                 scheme,
    Metrics:                metricsServerOptions,
    WebhookServer:          webhookServer,
    HealthProbeBindAddress: probeAddr,
    LeaderElection:         enableLeaderElection,
    LeaderElectionID:       "your-leader-election-id",
    // ... other existing options ...
}

// 配置缓存以监视 WATCH_NAMESPACE 中指定的命名空间
mgrOptions.Cache = setupCacheNamespaces(watchNamespace)
setupLog.Info("Watching namespace(s)", "namespaces", watchNamespace)

mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), mgrOptions)
if err != nil {
    setupLog.Error(err, "Failed to start manager")
    os.Exit(1)
}

3. 更新现有控制器中的 RBAC 标记

对每个现有 controller 文件，在 RBAC markers 中添加 namespace= 参数。

查找控制器文件：

• 查找包含 func (r *SomeReconciler) Reconcile( 的文件
• 常见位置：internal/controller/*_controller.go

在 internal/controller/cronjob_controller.go 中：

之前（集群作用域）：

// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs/finalizers,verbs=update

// Reconcile 是主 Kubernetes 协调循环的一部分
func (r *CronJobReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {

之后（命名空间作用域）：

// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,namespace=<project-name>-system,resources=cronjobs,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,namespace=<project-name>-system,resources=cronjobs/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,namespace=<project-name>-system,resources=cronjobs/finalizers,verbs=update

// Reconcile 是主 Kubernetes 协调循环的一部分
func (r *CronJobReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {

将 project-system 替换为你的 namespace（在 config/default/kustomization.yaml 的 namespace: 字段中）。

4. 重新生成 RBAC 清单

在步骤 3 更新 RBAC markers 后，重新生成 RBAC manifests：

make manifests      # Regenerate RBAC from updated controller markers

确认生成的文件显示 kind: Role 而非 kind: ClusterRole：

config/rbac/role.yaml:

kind: Role
metadata:
  name: manager-role
  # 注意：命名空间由 kustomize 在构建时添加，不在源文件中

**config/rbac/*_editor_role.yaml, _viewer_role.yaml, _admin_role.yaml:

kind: Role
metadata:
  name: cronjob-editor-role
  # 注意：命名空间由 kustomize 在构建时添加，不在源文件中

5. 验证并部署

运行测试以验证一切正常：

make generate       # Regenerate code
make test           # Run tests

部署并验证：

make deploy IMG=<your-image>

# Verify RBAC is namespace-scoped (not cluster-scoped)
kubectl get role,rolebinding -n <manager-namespace>

# Test: Create a resource in the manager's 命名空间 - 应被协调
kubectl apply -f config/samples/ -n <manager-namespace>

# 测试：在不同命名空间中创建资源 - 不应被协调
kubectl apply -f config/samples/ -n other-namespace

AI 辅助迁移

若使用 AI 编码助手（Cursor、GitHub Copilot 等），可自动化手动迁移步骤。

多命名空间支持

WATCH_NAMESPACE 环境变量支持逗号分隔的值，以监视多个特定 namespaces：

env:
- name: WATCH_NAMESPACE
  value: "namespace-1,namespace-2,namespace-3"

注意：需要在每个 namespace 中创建 Role/RoleBinding 才能有正确的 RBAC。

恢复为集群作用域

恢复为集群作用域：

kubebuilder edit --namespaced=false --force

该命令会自动：

• 在 PROJECT 文件中设置 namespaced: false
• 脚手架 kind: ClusterRole 的 config/rbac/role.yaml
• 脚手架 kind: ClusterRoleBinding 的 config/rbac/role_binding.yaml
• 使用 --force：重新生成不含 WATCH_NAMESPACE 环境变量的 config/manager/manager.yaml

需要手动执行的步骤：

1. 从所有 controller 文件的 RBAC markers 中移除 namespace= 参数
2. 运行 make manifests 重新生成集群作用域 RBAC
3. 从 cmd/main.go 中移除命名空间作用域代码：
   • 移除 getWatchNamespace() 函数
   • 移除 setupCacheNamespaces() 函数
   • 移除命名空间获取与缓存配置
   • 若别处未使用，移除新增的 imports（fmt、strings、cache）
4. 若未使用 --force，请手动从 config/manager/manager.yaml 移除 WATCH_NAMESPACE

重要说明

• 仅 controllers 需要更新 RBAC：只更新 controller 文件（含 Reconcile 函数的文件）中的 +kubebuilder:rbac markers。Webhook 文件不使用 RBAC markers——webhooks 使用基于证书的认证与 API server 通信。
• RBAC markers 控制作用域：controller RBAC markers 中的 namespace= 参数决定 controller-gen 生成 Role（Namespace 作用域）还是 ClusterRole（集群作用域）。没有 namespace= 参数时，controller-gen 始终生成 ClusterRole。
• Controller-gen 会重新生成 role.yaml：运行 make manifests 后，controller-gen 会根据 controller RBAC markers 重新生成 config/rbac/role.yaml。kubebuilder edit --namespaced=true 初始脚手架的 Role 作为模板，但实际内容由 controller-gen 管理。
• Namespace 参数格式：在 controller RBAC markers 中使用 namespace=<your-namespace>，通常为 namespace=<project-name>-system 以匹配部署 namespace。
• Metrics auth role 保持集群作用域：metrics-auth-role 使用集群作用域 API（TokenReview、SubjectAccessReview），正确地保持为无 namespace 参数的 ClusterRole。
• Webhooks 需要手动配置：目前 controller-gen 不支持 webhooks 的 namespaceSelector 或 objectSelector markers。详见上文 webhook 部分。

另见

• Manager 作用域 — Manager 作用域概念详解
• 项目配置 — PROJECT 文件配置参考

Alpha 命令

Kubebuilder 提供实验性的 alpha 命令，用于协助项目迁移和脚手架重新生成等高级操作。

这些命令通过自动化或部分自动化流程，简化了以往需要手动且易出错的任务。

目前可用的 alpha 命令如下：

• alpha generate — 使用已安装的 CLI 版本重新脚手架生成项目
• alpha update — 利用脚手架快照通过三方合并自动化迁移过程

更多信息见各命令的专用文档。

使用（alpha generate）重新生成你的项目

概述

kubebuilder alpha generate 命令使用当前已安装的 CLI 和插件版本重新生成项目脚手架。

它根据 PROJECT 文件中的配置重新生成完整脚手架。这样你可以应用较新 Kubebuilder 版本引入的最新布局变更、插件特性以及代码生成改进。

你可以选择就地重新生成项目（覆盖现有文件），或输出到单独目录以便基于 diff 检查并手动集成。

什么时候使用它？

当 Kubebuilder 引入新变更时，你可以使用 kubebuilder alpha generate 升级项目脚手架。这包括插件更新（例如 go.kubebuilder.io/v3 → go.kubebuilder.io/v4）或 CLI 版本更新（例如 4.3.1 → latest）。

在以下情况此命令很有用：

• 更新项目以使用最新布局或插件版本
• 重新生成项目脚手架以包含近期变更
• 将当前脚手架与最新版本对比并手动应用更新
• 创建干净脚手架以审查或测试变更

当你希望完全掌控升级过程时使用此命令。若项目由较旧 CLI 版本创建且不支持 alpha update，此命令也很有用。

这种方法可以让你对比当前分支与上游脚手架更新（例如来自主分支）之间的差异，并帮助你将自定义代码叠加上新脚手架。

如何使用它？

将当前项目升级到已安装的 CLI 版本（即最新脚手架）

kubebuilder alpha generate

运行此命令后，项目会就地重新生成脚手架。然后你可以对比本地变更与主分支，查看更新内容，并按需重新叠加自定义代码。

将脚手架生成到新目录

使用 --input-dir 和 --output-dir 标志指定输入与输出路径。

kubebuilder alpha generate \
  --input-dir=/path/to/existing/project \
  --output-dir=/path/to/new/project

运行命令后，可在指定输出目录中检查生成的脚手架。

旗帜

进一步的资源

• 工作原理视频演示
• 设计提案文档

使用（alpha update）更新你的项目

概述

kubebuilder alpha update 使用三方 Git 合并将项目脚手架升级到更新的 Kubebuilder 发行版。它为旧版与新版重建干净脚手架，将当前代码合并到新脚手架，并给出可审查的输出分支。它处理繁重工作，让你专注于审查与解决冲突，而非重新应用代码。

默认情况下，最终结果会在专用输出分支上压缩为单个提交。若希望保留完整历史（不 squash），请使用 --show-commits。

何时使用它

在以下情况使用此命令：

• 希望迁移到更新的 Kubebuilder 版本或插件布局
• 希望在单独分支上审查脚手架变更
• 希望专注于解决合并冲突（而非重新应用自定义代码）

它是如何工作的

你告知工具新版本以及项目所在分支。它会重建两套脚手架，用三方合并将你的代码合并到新脚手架中，并给出可安全审查与合并的输出分支。你可以选择单个干净提交、完整历史，或自动推送到远程。

步骤 1：Detect versions

• 它会查看你的 PROJECT 文件或你传入的标志。
• 通过读取 PROJECT 文件中的 cliVersion 字段（若可用）确定你来自哪个旧版本。
• 确定你想要的新版本（默认为最新发行版）。
• 选择包含当前代码的分支（默认为 main）。

步骤 2：Create scaffolds

该命令会创建三个临时分支：

• 祖先：来自旧版本的干净项目脚手架。
• 原始：你当前代码的快照。
• 升级：来自新版本的干净脚手架。

步骤 3：Do a 3-way merge

• 使用 Git 的三方合并将原始（你的代码）合并到升级（新脚手架）中。
• 在引入上游变更的同时保留你的自定义内容。
• 如果发生冲突：
  • 默认 → 停止并让你手动解决。
  • 使用 --force → 即使有冲突标记也继续并提交。（适合自动化）
• 运行 make manifests generate fmt vet lint-fix 进行整理。

步骤 4：Write the output branch

• 默认情况下，所有内容会在安全输出分支上压缩为单个提交：kubebuilder-update-from-<from-version>-to-<to-version>。
• 你可以更改行为：
  • --show-commits：保留完整历史。
  • --restore-path：在压缩模式下，从基线分支恢复特定文件（如 CI 配置）。
  • --output-branch：选择自定义分支名。
  • --merge-message：自定义干净合并时的提交信息。
  • --conflict-message：自定义发生冲突时的提交信息。
  • --push：自动将结果推送到 origin。
  • --git-config: sets git configurations.
  • --open-gh-issue：创建带有清单与对比链接的 GitHub issue（需要 gh）。

步骤 5：Cleanup

• 输出分支就绪后，所有临时工作分支将被删除。
• 最终得到一个干净分支，可测试、审查并合并回主分支。

如何使用（命令）

在项目根目录运行：

kubebuilder alpha update

固定版本与基线分支：

kubebuilder alpha update \
--from-version v4.5.2 \
--to-version   v4.6.0 \
--from-branch  main

适合自动化（即使有冲突也继续）：

kubebuilder alpha update --force

保留完整历史而非压缩：

kubebuilder alpha update --from-version v4.5.0 --to-version v4.7.0 --force --show-commits

默认压缩，但保留基线分支的 CI/工作流：

kubebuilder alpha update --force \
--restore-path .github/workflows \
--restore-path docs

使用自定义输出分支名：

kubebuilder alpha update --force \
--output-branch upgrade/kb-to-v4.7.0

运行更新并将结果推送到 origin：

kubebuilder alpha update --from-version v4.6.0 --to-version v4.7.0 --force --push

自定义提交信息：

kubebuilder alpha update --force \
--merge-message "chore: upgrade kubebuilder scaffold" \
--conflict-message "chore: upgrade with conflicts - manual review needed"

处理冲突（--force 与默认）

使用 --force 时，即使有冲突 Git 也会完成合并。提交将包含如下标记：

<<<<<<< HEAD
Your changes
=======
Incoming changes
>>>>>>> (original)

这允许你在 CI 或 cron 任务中运行该命令而无需人工干预。

• 不使用 --force：命令停在 merge 分支并打印指引；不创建提交。
• 使用 --force：合并会被提交（merge 或 output 分支）并包含标记。

修复冲突后，始终运行：

make manifests generate fmt vet lint-fix
# or
make all

与 GitHub Issues 一起使用（--open-gh-issue）

传入 --open-gh-issue 让命令在仓库中创建 GitHub Issue 以协助更新。

Examples

创建带有对比链接的 Issue：

kubebuilder alpha update --open-gh-issue

你将看到

该命令会打开一个链接到 diff 的 Issue，以便你创建 PR 并审查，例如：

Automation

这能与自动化良好集成。autoupdate.kubebuilder.io/v1-alpha 插件可生成按计划（例如每周）运行该命令的 GitHub Actions 工作流。当有新的 Kubebuilder 版本可用时，它会打开带有对比链接的 Issue，便于你创建 PR 并审查。

仅在运行期间更改额外 Git 配置（不修改你的 ~/.gitconfig）

默认情况下，kubebuilder alpha update 会应用安全的 Git 配置：merge.renameLimit=999999、diff.renameLimit=999999、merge.conflictStyle=merge。你可以追加更多配置，或禁用它们。

• 在默认值之上追加更多

kubebuilder alpha update \
  --git-config rerere.enabled=true

• 完全禁用默认值

kubebuilder alpha update --git-config disable

• 禁用默认值并设置你自己的

kubebuilder alpha update \
  --git-config disable \
  --git-config rerere.enabled=true

旗帜

Demonstration

进一步的资源

• 自动更新插件
• 更新自动化设计提案
• 项目配置参考

参考

• 生成 CRD

• 使用最终器 最终器是一种机制，用于在资源从 Kubernetes 集群中删除之前执行与该资源相关的任何自定义逻辑。

• 监控资源 监控 Kubernetes 集群中的资源，以便获取信息并对变更采取行动。

  • 观看二级资源拥有的内容
  • 观看未拥有的次级资源
  • 使用谓词来优化观察

• Kind 集群

• 什么是webhook？ Webhooks是HTTP回调，在k8s中有三种类型的webhook：1）准入webhook 2）CRD转换webhook 3）授权webhook

  • 接收Webhook 接收Webhook是在API服务器接收资源之前，对其进行变更或验证的HTTP回调。

• 配置/代码生成的标记

  • CRD 生成
  • CRD 验证
  • Webhook
  • 对象/深拷贝
  • RBAC
  • 脚手架

• 使用 Pprof 进行监控

• controller-gen 命令行界面

• 您接受的训练数据截止至2023年10月。

• 文物

• 平台支持

• 子模块布局

• 使用外部资源 / API

• 指标

  • 参考

• CLI 插件

生成 CRD（自定义资源定义）

Kubebuilder 使用一个名为 controller-gen 的工具来生成实用代码和 Kubernetes 对象的 YAML，比如自定义资源定义（CustomResourceDefinitions）。

为此，它使用特殊的“标记注释“（以 // + 开头的注释）来指示有关字段、类型和包的附加信息。在自定义资源定义（CRD）的情况下，这些信息通常来自于你的 _types.go 文件。有关标记的更多信息，请参见 标记参考文档。

Kubebuilder 提供了一个 make 目标来运行 controller-gen 并生成 CRD：make manifests。

当你运行 make manifests 时，应该可以在 config/crd/bases 目录下看到生成的 CRD。make manifests 还可以生成许多其他的构件—更多细节请查看 标记参考文档。

验证

CRD 支持使用 validation 部分中的 OpenAPI v3 架构 进行 声明式验证.

一般来说，验证标记可以附加到字段或类型上。如果您在定义复杂的验证、需要重用验证或需要验证切片元素，通常最好定义一个新类型来描述您的验证。

例如：

type ToySpec struct {
	// +kubebuilder:validation:MaxLength=15
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name,omitempty"`

	// +kubebuilder:validation:MaxItems=500
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:UniqueItems=true
	Knights []string `json:"knights,omitempty"`

	Alias   Alias   `json:"alias,omitempty"`
	Rank    Rank    `json:"rank"`
}

// +kubebuilder:validation:Enum=狮子;狼;龙
type Alias string

// +kubebuilder:validation:最小值=1
// +kubebuilder:validation:最大值=3
// +kubebuilder:validation:排除最大值=false
type Rank int32

附加打印机列

从 Kubernetes 1.11 开始，kubectl get 可以向服务器请求显示哪些列。对于自定义资源定义（CRD），这可以用于提供有用的特定类型信息，类似于内置类型所提供的信息。

显示的信息可以通过您的 CRD 上的 additionalPrinterColumns 字段 进行控制，该字段由 CRD 的 Go 类型上的 +kubebuilder:printcolumn 标记控制。

例如，在以下示例中，我们添加字段以显示有关骑士的信息，以及来自验证示例的等级和别名字段：

// +kubebuilder:printcolumn:name="别名",type=string,JSONPath=`.spec.alias`
// +kubebuilder:printcolumn:name="等级",type=integer,JSONPath=`.spec.rank`
// +kubebuilder:printcolumn:name="勇敢逃跑",type=boolean,JSONPath=`.spec.knights[?(@ == "罗宾爵士")]`,description="当危险抬起丑陋的头颅时，他勇敢地转身逃跑",priority=10
// +kubebuilder:printcolumn:name="年龄",type="日期",JSONPath=".metadata.creationTimestamp"
type Toy struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   ToySpec   `json:"spec,omitempty"`
	Status ToyStatus `json:"status,omitempty"`
}

子资源

从 Kubernetes 1.13 开始，CRDs 可以选择实现 /status 和 /scale 子资源。

一般建议您在所有具有状态字段的资源中使用 /status 子资源。

两个子资源都有相应的 标记.

状态

通过 +kubebuilder:subresource:status 启用 status 子资源。启用后，对主资源的更新不会更改 status。同样，对 status 子资源的更新只能更改 status 字段。

例如：

// +kubebuilder:subresource:status
type Toy struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   ToySpec   `json:"spec,omitempty"`
	Status ToyStatus `json:"status,omitempty"`
}

规模

通过 +kubebuilder:subresource:scale 启用 scale 子资源。启用后，用户可以对你的资源使用 kubectl scale。若 selectorpath 参数指向标签选择器的字符串形式，HorizontalPodAutoscaler 即可自动扩缩你的资源。

例如：

type CustomSetSpec struct {
	Replicas *int32 `json:"replicas"`
}

type CustomSetStatus struct {
	Replicas int32 `json:"replicas"`
    Selector string `json:"selector"` // 这必须是选择器的字符串形式
}


// +kubebuilder:subresource:status
// +kubebuilder:subresource:scale:specpath=.spec.replicas,statuspath=.status.replicas,selectorpath=.status.selector
type CustomSet struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   CustomSetSpec   `json:"spec,omitempty"`
	Status CustomSetStatus `json:"status,omitempty"`
}

多个版本

从 Kubernetes 1.13 开始，您可以在 CRD 中定义多个版本的 Kind，并使用一个 webhook 在它们之间进行转换。

有关此过程的更多详细信息，请参见 多版本教程。

默认情况下，Kubebuilder 禁用了为 CRD 中的 Kind 不同版本生成不同的验证，以便与旧版本的 Kubernetes 兼容。

如果使用 v1beta CRD，您需要将 makefile 中的 CRD_OPTIONS ?= "crd:trivialVersions=true,preserveUnknownFields=false 这一行更改为 CRD_OPTIONS ?= crd:preserveUnknownFields=false；如果使用 v1（推荐），则更改为 CRD_OPTIONS ?= crd。

然后，您可以使用 +kubebuilder:storageversion 标记 来指示 API 服务器应该使用的用于存储数据的 GVK。

在内部实现上

Kubebuilder 自动生成用于运行 controller-gen 的 make 规则。该规则会使用 Go 模块通过 go install 自动安装 controller-gen，如果它不在您的路径中。

如果你想查看 controller-gen 的具体操作，也可以直接运行它。

每个 controller-gen 的“生成器“都由 controller-gen 的一个选项控制，使用与标记相同的语法。controller-gen 还支持不同的输出“规则“，以控制输出的方式和去向。请注意 manifests 制作规则（略微简化，仅生成 CRD）：

# 为 CRD 生成清单
manifests: controller-gen
	$(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases

它使用 output:crd:artifacts 输出规则来指示与 CRD 相关的配置（非代码）工件应最终放在 config/crd/bases 中，而不是 config/crd。

要查看包括生成器在内的所有 controller-gen 选项，请运行

$ controller-gen -h

或者，欲了解更多详情：

$ controller-gen -hhh

使用终结器

Finalizers 允许控制器实现异步删除前钩子。若为 API 类型的每个对象创建外部资源（如存储桶），并希望在从 Kubernetes 删除对象时删除关联的外部资源，请使用 Finalizer。

您可以在Kubernetes参考文档中阅读更多关于最终器的信息。下面的部分演示了如何在控制器的Reconcile方法中注册和触发预删除钩子。

需要注意的关键点是，最终处理器导致对象的“删除“变成“更新“，以设置删除时间戳。对象上存在删除时间戳表明该对象正在被删除。否则，如果没有最终处理器，删除会表现为一个调整过程，其中对象在缓存中丢失。

亮点：

• 如果对象没有被删除且没有注册终结器，则在 Kubernetes 中添加终结器并更新该对象。
• 如果对象正在被删除，并且最终器仍然在最终器列表中，那么请执行预删除逻辑，移除最终器并更新对象。
• 确保预删除逻辑是幂等的。

Apache License

http://www.apache.org/licenses/LICENSE-2.0

Imports

package controllers

import (
	"context"

	"k8s.io/kubernetes/pkg/apis/batch"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"

	batchv1 "tutorial.kubebuilder.io/project/api/v1"
)

// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=batch.tutorial.kubebuilder.io,resources=cronjobs/finalizers,verbs=update

func (r *CronJobReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	log := r.Log.WithValues("cronjob", req.NamespacedName)

	cronJob := &batchv1.CronJob{}
	if err := r.Get(ctx, req.NamespacedName, cronJob); err != nil {
		log.Error(err, "unable to fetch CronJob")
		// we'll ignore not-found errors, since they can't be fixed by an immediate
		// requeue (we'll need to wait for a new notification), and we can get them
		// on deleted requests.
		return ctrl.Result{}, client.IgnoreNotFound(err)
	}

	// name of our custom finalizer
	myFinalizerName := "batch.tutorial.kubebuilder.io/finalizer"

	// examine DeletionTimestamp to determine if object is under deletion
	if cronJob.ObjectMeta.DeletionTimestamp.IsZero() {
		// The object is not being deleted, so if it does not have our finalizer,
		// then let's add the finalizer and update the object. This is equivalent
		// to registering our finalizer.
		if !controllerutil.ContainsFinalizer(cronJob, myFinalizerName) {
			controllerutil.AddFinalizer(cronJob, myFinalizerName)
			if err := r.Update(ctx, cronJob); err != nil {
				return ctrl.Result{}, err
			}
		}
	} else {
		// The object is being deleted
		if controllerutil.ContainsFinalizer(cronJob, myFinalizerName) {
			// our finalizer is present, so let's handle any external dependency
			if err := r.deleteExternalResources(cronJob); err != nil {
				// if fail to delete the external dependency here, return with error
				// so that it can be retried.
				return ctrl.Result{}, err
			}

			// remove our finalizer from the list and update it.
			controllerutil.RemoveFinalizer(cronJob, myFinalizerName)
			if err := r.Update(ctx, cronJob); err != nil {
				return ctrl.Result{}, err
			}
		}

		// Stop reconciliation as the item is being deleted
		return ctrl.Result{}, nil
	}

	// Your reconcile logic

	return ctrl.Result{}, nil
}

func (r *Reconciler) deleteExternalResources(cronJob *batch.CronJob) error {
	//
	// delete any external resources associated with the cronJob
	//
	// Ensure that delete implementation is idempotent and safe to invoke
	// multiple times for same object.
}

良好实践

Operator 中的“协调（reconciliation）”是什么？

当你使用 Kubebuilder 创建一个项目时，可以查看在 cmd/main.go 中生成的代码。这段代码初始化了一个 Manager，项目依赖于 controller-runtime 框架。这个 Manager 管理着 Controllers，提供了一种调整功能，用于在集群内同步资源直到达到所需状态。

调整是一个持续的循环，执行必要的操作以保持期望的状态，遵循Kubernetes的原则，如控制循环。有关更多信息，请查阅Kubernetes的Operator模式文档，以更好地理解这些概念。

为什么重调应该是幂等的？

在开发运算符时，控制器的对账循环需要是幂等的。通过遵循 运算符模式，我们创建 控制器，这些控制器提供一个对账函数，负责在集群上同步资源，直到达到期望状态。开发幂等的解决方案将允许对账器正确响应通用或意外事件，轻松处理应用程序的启动或升级。更多相关解释可以参考 这里。

根据特定事件编写调整逻辑，会违反 Operator 模式的建议，并且违背了controller-runtime的设计原则。这可能导致不可预见的后果，例如资源被卡住，需要人工干预。

理解 Kubernetes API 和遵循 API 约定

构建操作器通常涉及扩展 Kubernetes API 本身。了解自定义资源定义（CRDs）如何与 Kubernetes API 交互是很有帮助的。此外，关于分组、版本和种类的 Kubebuilder 文档 也可能有助于更好地理解这些与操作器相关的概念。

此外，我们建议您查看 Kubernetes 上的 Operator 模式 文档，以更好地理解使用 KubeBuilder 构建的标准解决方案的目的。

为什么您应该遵循 Kubernetes API 的约定和标准

遵循 Kubernetes API 规范和标准 对于最大化应用程序和部署的潜力至关重要。通过遵循这些既定实践，您可以在多个方面受益。

首先，遵循标准确保了Kubernetes生态系统内的无缝互操作性。遵循约定使您的应用程序能够与其他组件和谐工作，从而减少兼容性问题并促进一致的用户体验。

其次，遵循API标准可以提高应用程序的可维护性和故障排除能力。采用熟悉的模式和结构使得调试和支持您的部署变得更加容易，从而提高了运营效率和快速问题解决的能力。

此外，利用Kubernetes API的惯例可以让您充分发挥平台的全部功能。通过在定义的框架内工作，您可以利用Kubernetes提供的丰富特性和资源，从而实现可扩展性、性能优化和弹性。

最后，遵循这些标准可以使您的本土解决方案具备未来适应能力。通过与不断发展的Kubernetes生态系统保持一致，您可以确保与未来更新、新功能以及活跃的Kubernetes社区引入的增强功能保持兼容。

总之，通过遵循Kubernetes API的约定和标准，您可以实现无缝集成、简化维护、优化性能和为未来做好准备的潜力，这些都为您的应用程序和部署的成功做出了贡献。

为什么应避免由单个 controller 负责管理多个 CRD（Custom Resource Definitions）的系统设计（例如 ‘install_all_controller.go’）？

避免采用一种设计方案，其中同一个控制器对账多个 Kind。将多个 Kind（如 CRD）都由同一个控制器管理，通常与 controller-runtime 提出的设计相悖。此外，这可能会损害封装性、单一职责原则和内聚性等概念。损害这些概念可能会导致意想不到的副作用，并增加扩展、重用或维护操作器的难度。在一个操作器中，由一个控制器管理多个自定义资源（CRs）可能会导致几个问题：

• 复杂性：单个控制器管理多个自定义资源（CR）可能会增加代码的复杂性，从而使其更难理解、维护和调试。
• 可扩展性：每个控制器通常管理一种类型的自定义资源（CR）以实现可扩展性。如果一个控制器处理多个CR，它可能成为瓶颈，从而降低系统的整体效率和响应速度。
• 单一职责原则：遵循软件工程中的这一原则，理想情况下每个控制器应该只有一个职责。这种方法简化了开发和调试，并使系统更加健壮。
• 错误隔离：如果一个控制器管理多个自定义资源（CR），并且发生错误，可能会影响它管理的所有 CR。为每个 CR 配置一个单独的控制器可以确保一个控制器或 CR 的问题不会直接影响其他资源。
• 并发与同步：一个单一的控制器管理多个自定义资源（CR）可能导致竞争条件，并需要复杂的同步，特别是当这些CR之间存在相互依赖时。

总之，虽然让一个控制器管理多个CR看起来效率较高，但这通常会导致更高的复杂性、较低的可扩展性以及潜在的稳定性问题。通常遵循单一职责原则更为合适，每个CR由其自己的控制器管理。

为什么你应该采用状态条件

按照 K8s API 约定 使用 Status Conditionals 管理你的方案，因为：

• 标准化：条件提供了一种标准化的方式来表示操作员自定义资源的状态，使用户和工具更容易理解和解释资源的状态。
• 可读性：通过使用多个条件的组合，条件可以清晰地表达复杂的状态，使用户更容易理解资源的当前状态和进展。
• 可扩展性：当新的功能或状态被添加到您的 Operator 时，可以轻松扩展条件以表示这些新状态，而无需对现有的 API 或结构进行重大更改。
• 可观察性：集群管理员和外部监控工具可以监视和跟踪状态条件，从而更好地了解由操作员管理的自定义资源的状态。
• 兼容性：通过采用在 Kubernetes API 中使用条件的常见模式，Operator 作者确保他们的自定义资源与更广泛的生态系统保持一致，这有助于用户在与集群中的多个 Operator 和资源交互时获得一致的体验。

你应采用 Kubernetes 的可观测与埋点约定

正确的日志记录对 Kubernetes 原生应用的可观测性至关重要。但需要根据代码上下文理解应采用哪套日志约定。

理解 Go 与 Kubernetes 日志约定的差异

使用 Go 开发时，你可能熟悉 Go Code Review Comments 指南：错误字符串不应大写开头，也不应以标点结尾。这些约定面向常被组合进更大上下文的错误消息：

// Go conventions (for general Go code, libraries, CLI tools)
return fmt.Errorf("something bad happened")  // lowercase, no period
log.Printf("failed to connect: %v", err)     // lowercase

但是，在开发运行于集群上的 Kubernetes 原生方案（controller、operator、webhook）时，应遵循 Kubernetes 日志约定，以获得更好的可观测性并与 Kubernetes 生态保持一致。

Kubernetes 日志约定

对于控制器、Operator 和 Webhook，遵循以下指南：

• 以大写字母开头。
• 不要以句号结束消息。
• 使用主动语态。有动作主体时使用完整句子（「A could not do B」）；若主体就是程序本身则可省略主体（「Could not do B」）。
• 使用过去时（用 “Could not delete B” 而非 “Cannot delete B”）
• 提及对象时，说明对象类型。（用 “Deleted Pod” 而非 “Deleted”）
• 使用带有成对键值的结构化日志。

Examples:

// Kubernetes conventions (for controllers, operators, webhooks)
log.Info("Starting reconciliation")                              // Capital letter, no period
log.Info("Creating Deployment", "name", name, "namespace", ns)   // Specify object type, structured logging
log.Info("Created Deployment", "name", deploy.Name)              // Past tense, specify type
log.Error(err, "Failed to create Pod", "name", name)             // Past tense, specify type
log.Info("Deployment could not create Pod", "deployment", name)  // Acting subject
log.Info("Could not delete Pod", "name", name)                   // Subject is the program itself

为何使用不同约定？

• Go 约定针对会被组合进更大上下文、并与其他文本内联显示的错误消息进行了优化
• Kubernetes 约定针对分布式系统中的结构化日志进行了优化，其中日志：
  • 从集群中的多个组件聚合而来
  • 由日志收集器解析（Fluentd、Fluentbit、Loki 等）
  • 显示在监控仪表盘与 UI 中
  • 用于生产环境中的告警与故障排查

遵循这些约定可确保日志与 Kubernetes 可观测性工具无缝集成，并为集群运维人员和 SRE 提供清晰、可操作的信息。

（Alpha）Server-Side Apply

--ssa 标志会脚手架生成带 Server-Side Apply 支持的 API，使多个参与者修改同一资源时字段管理更安全。

这将添加：

• 用于生成 ApplyConfiguration 的 API 标记（+genclient、+kubebuilder:ac:generate=true）
• Makefile 集成，在生成 CRD 与 RBAC 清单的同时生成类型安全的 ApplyConfiguration 类型

何时使用它

在以下情况使用 Server-Side Apply：

• 多个控制器或用户管理同一资源
• 用户用标签、注解或你的控制器不应覆盖的 spec 字段自定义 CR
• 你需要声明式字段所有权跟踪
• 其他 Operator 将管理你的 CR 实例（它们可导入你生成的 ApplyConfiguration 类型）

它是如何工作的

传统的 Update() 会覆盖整个对象。使用客户端 Apply 方法的 Server-Side Apply 只管理你指定的字段。

运行 make manifests 后，ApplyConfiguration 类型创建于：

api/<version>/applyconfiguration/api/<version>/          (single group)
api/<group>/<version>/applyconfiguration/<group>/<version>/  (multi-group)

导入方式如下（多 group 项目使用 example.com/myproject/api/<group>/v1/applyconfiguration/<group>/v1）：

appsv1apply "example.com/myproject/api/v1/applyconfiguration/api/v1"

混合使用 SSA 与非 SSA API

groupversion_info.go 中的 +kubebuilder:ac:generate=true marker 是包级的：它为该 group/version 启用 ApplyConfiguration 生成。每个 kind 再用自己的 +kubebuilder:ac:generate marker 选择加入或排除：用 --ssa 脚手架的 kind 为 =true，未使用的为 =false。当你用 --ssa 创建 API 时，该 group/version 中此前脚手架且没有此 marker 的 kind 会自动获得它。

要更改生成哪些 kind：

• 在 kind 上方设置 +kubebuilder:ac:generate=true 以包含它
• 在 kind 上方设置 +kubebuilder:ac:generate=false 以排除它

Usage

使用 --ssa 标志创建 API：

kubebuilder create api --group apps --version v1 --kind Application --ssa

在控制器中实现 Server-Side Apply：

import (
    "context"

    metav1apply "k8s.io/client-go/applyconfigurations/meta/v1"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/client"

    appsv1apply "example.com/myproject/api/v1/applyconfiguration/api/v1"
)

func (r *ApplicationReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    // Build desired state - specify only fields you manage
    app := appsv1apply.Application(req.Name, req.Namespace).
        WithStatus(appsv1apply.ApplicationStatus().
            WithConditions(metav1apply.Condition().
                WithType("Available").
                WithStatus("True").
                WithReason("Reconciled")))

    // Apply status, forcing ownership of the fields this controller manages
    if err := r.SubResource("status").Apply(ctx, app,
        client.FieldOwner("application-controller"), client.ForceOwnership); err != nil {
        return ctrl.Result{}, err
    }
    return ctrl.Result{}, nil
}

然后运行：

make generate manifests

最佳实践

• 始终指定 client.FieldOwner("controller-name") 以标识你的控制器
• Controller 应对所管理的字段传入 client.ForceOwnership；Kubernetes 建议 controller 始终强制解决冲突
• 使用 builder 模式仅指定你的控制器所管理的字段

其他资源

• Kubernetes Server-Side Apply 文档
• Apply Configuration 标记
• controller-gen 命令行界面

许可证头

这是什么？

Kubebuilder 会在 hack/boilerplate.go.txt 创建包含许可证头的文件。该头会自动添加到所有生成的 Go 文件中。

样板文件由以下使用：

• Kubebuilder 在创建新文件时（create api、create webhook 等）
• controller-gen when generating code (DeepCopy methods, etc.)
• make generate and make manifests commands

默认情况下，Kubebuilder 使用 Apache 2.0 许可证。

如何自定义

选项 1：Use built-in licenses

在初始化时或更新现有项目时使用 --license 标志：

# During initialization
kubebuilder init --domain example.com --license apache2 --owner "Your Name"

# After initialization (update existing project)
kubebuilder edit --license apache2 --owner "Your Company"

可用的许可证值：

• apache2 - Apache 2.0 License (default)
• copyright - Copyright notice only (no license text)
• none - No license header

选项 2：Use a custom license file

从文件提供你自己的许可证头。Kubebuilder 会读取文件内容并复制到 hack/boilerplate.go.txt：

# During initialization
kubebuilder init --domain example.com --license-file ./my-header.txt

# After initialization
kubebuilder edit --license-file ./my-header.txt

工作原理：

1. Kubebuilder 读取你的自定义许可证文件（可为任意路径）
2. 将内容复制到 hack/boilerplate.go.txt

在以下情况使用：

• 内置模板中没有的许可证
• 特定公司许可证格式
• 自定义版权声明

选项 3：Edit the file directly

初始化后，你可以直接编辑 hack/boilerplate.go.txt：

vim hack/boilerplate.go.txt

自定义许可证文件格式

你的自定义许可证文件必须包含 Go 注释定界符（/* 和 */）。

示例（my-license-header.txt）：

/*
Copyright YEAR Your Company Name.

Licensed under the MIT License.
See LICENSE file in the project root for full license text.
*/

将许可证变更应用到现有文件

更新 hack/boilerplate.go.txt 后，选择如何应用变更：

重新生成已生成的代码（推荐）：

make generate  # Update DeepCopy methods
make manifests # Update CRDs, RBAC, webhooks

这会更新生成的代码，但保持手写文件不变。

重新生成整个项目：

kubebuilder alpha generate

仅新文件： 新文件将自动使用更新后的模板：

kubebuilder create api --group myapp --version v1 --kind MyNewKind

手动更新： 对于手写文件，以 hack/boilerplate.go.txt 为参考手动更新页眉。

如何使用

生成或重新生成文件时会使用 hack/boilerplate.go.txt：

• kubebuilder create api 与 create webhook - 新文件
• make generate - DeepCopy methods, etc.
• make manifests - CRDs, RBAC, webhooks
• kubebuilder alpha generate - entire project

所有工具自动引用 hack/boilerplate.go.txt。Makefile 已配置好——无需更改。

Examples

示例 1：Apache 2.0 许可证（默认）

使用内置的 Apache 2.0 许可证：

kubebuilder init --domain example.com --license apache2 --owner "Your Company"

这将生成：

/*
 版权 2025 The Kubernetes authors.
 根据 Apache 许可证，版本 2.0（"许可证"）授权；
 您只能在遵守该许可证的情况下使用此文件。
 您可以在以下地址获得该许可证的副本：

   http://www.apache.org/licenses/LICENSE-2.0 

 除非适用法律要求或书面同意，否则根据该许可证分发的软件
 是按"原样"基础分发的，
 不提供任何形式的担保或条件，无论是明示还是否明示。
有关许可证下的具体权限和限制，请参见许可证。
*/

示例 2：仅版权声明

使用内置的 copyright 许可证仅生成版权声明：

kubebuilder init --domain example.com --license copyright --owner "Your Company"

这将生成：

/*
Copyright YEAR Your Company.
*/

示例 3：自定义许可证（MIT）

对于非内置许可证，创建自定义文件 mit-header.txt：

/*
Copyright YEAR Your Name.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/

然后初始化你的项目：

kubebuilder init --domain example.com --license-file ./mit-header.txt

会发生什么：

1. Kubebuilder 从 ./mit-header.txt 读取内容
2. 用该内容创建 hack/boilerplate.go.txt
3. hack/boilerplate.go.txt 成为所有生成文件的权威来源

Related

• 良好实践 - 项目结构最佳实践
• 生成 CRD - 如何带页眉生成 CRD
• controller-gen CLI - 代码生成详情

创建活动

在控制器的 Reconcile 函数中发布 Event 对象通常是非常有用的，因为它们允许用户或任何自动化过程了解特定对象的状态并做出相应的响应。

可以通过运行 $ kubectl describe <资源类型> <资源名称> 来查看对象的最近事件。也可以通过运行 $ kubectl get events 来检查事件。

观看资源

在扩展 Kubernetes API 时，我们的目标是确保我们的解决方案与 Kubernetes 本身的行为一致。例如，考虑一个由控制器管理的 Deployment 资源。这个控制器负责响应集群中的变化——例如，当 Deployment 被创建、更新或删除时——通过触发调整以确保资源的状态与期望状态相匹配。

同样，在开发 controller 时，请监视对你的方案至关重要的资源上的相关变更。这些变更——无论是创建、更新还是删除——都应触发对账循环以采取适当操作，并在集群中保持一致性。

controller-runtime 库提供了多种方式来监视和管理资源。

主要资源

主要资源是你的控制器负责管理的资源。例如，如果你为 MyApp 创建了一个自定义资源定义（CRD），那么相应的控制器负责管理 MyApp 的实例。

在这种情况下，MyApp 是该控制器的 主资源，您的控制器的调整循环专注于确保这些主资源的期望状态得以维护。

当你使用 Kubebuilder 创建一个新的 API 时，以下默认代码会被生成，确保控制器监视所有相关事件——例如创建、更新和删除——以便于新的 API。

此设置确保每当你创建、更新或删除 API 实例时，系统都会触发对账循环：

// 监视主要资源（例如，MyApp）的创建、更新、删除事件
if err := ctrl.NewControllerManagedBy(mgr).
   For(&<YourAPISpec>{}). <-- See there that the Controller is For this API
   Complete(r); err != nil {
   return err
}

次要资源

您的控制器可能还需要管理辅助资源，这是集群中支持主要资源所需的资源。

对这些次级资源的更改可能会直接影响主要资源，因此控制者必须相应地监控和调整这些资源。

由控制者拥有的。

这些辅助资源，例如 Services、ConfigMaps 或 Deployments，在被控制器拥有时，由特定控制器创建和管理，并通过 OwnerReferences 与主资源相关联。

例如，如果我们在集群中有一个控制器来管理 MyApp 类型的自定义资源（CR），这代表了我们的应用解决方案，那么确保 MyApp 以所需实例数正常运行所需的所有资源将被称为 次要资源。负责创建、删除和更新这些资源的代码将是 MyApp 控制器的一部分。我们将使用 controllerutil.SetControllerReference 函数添加适当的 OwnerReferences 以指示这些资源由相同的控制器所拥有，该控制器负责管理 MyApp 实例，这些实例将由 MyAppReconciler 进行调整。

此外，如果删除了主要资源，Kubernetes 的垃圾回收机制将确保所有关联的次要资源以层级方式自动删除。

哪些不是由控制器“拥有“的？

请注意，辅助资源可以是您项目中定义的 API/CRD，也可以是与 主要资源 相关的其他项目中的 API/CRD，但特定控制器并不负责创建或管理这些资源。

例如，如果我们有一个表示备份解决方案（即 MyBackup）的自定义资源定义（CRD），用于我们的 MyApp，它可能需要监视 MyApp 资源的变化，以便在 MyBackup 中触发对账，确保达到期望的状态。同样，MyApp 的行为也可能受到其他项目中定义的 CRD/API 的影响。

在这两种情况下，这些资源都被视为次级资源，即使它们不是由MyAppController“拥有”（即没有被创建或管理）。

在 Kubebuilder 中，未在项目中定义且不是 核心类型（即未在 Kubernetes API 中定义的类型）的资源称为 外部类型。

外部类型是指在您的项目中未定义但您需要监视和响应的资源。例如，如果操作员 A管理一个用于应用程序部署的 MyApp CRD，而操作员 B处理备份，那么操作员 B可以将 MyApp CRD 视为外部类型，以便根据 MyApp 的变化触发备份操作。

在此场景中，Operator B 可以定义依赖 MyApp 状态的 BackupConfig CRD。通过将 MyApp 视为次要资源（Secondary Resource），Operator B 可以监视并对账 Operator A 的 MyApp 变更，确保你在更新或扩缩 MyApp 时 controller 启动备份流程。

观看资源的一般概念

无论资源是在您的项目内定义的还是来自外部项目，主要资源和次要资源的概念始终是相同的：

• 主要资源是控制器主要负责管理的资源。
• 次级资源是指为了确保主要资源按预期工作而必需的资源。

因此，无论资源由你的项目还是其他项目定义，你的 controller 都可以按需监视、对账并管理这些资源的变更。

观看二级资源有什么重要性？

在构建 Kubernetes 控制器时，关注 主要资源 是至关重要的，但同样重要的是监控 次要资源。未能跟踪这些资源可能导致您的控制器行为和整个集群状态的不一致。

次级资源可能并不直接由您的控制器管理，但对这些资源的更改仍然会对主资源和您的控制器的功能产生重大影响。以下是关注这些资源的重要原因：

• 确保一致性：

  • 二级资源（例如，子对象或外部依赖）可能与其预期状态发生偏离。例如，二级资源可能被修改或删除，从而导致系统不同步。
  • 观察辅助资源确保任何变化都能立即被检测到，这使得控制器能够对账并恢复所需状态。

• 避免随机自我修复：

  • 在没有查看二级资源的情况下，控制器可能只在重启后或在触发特定事件时“自我恢复“。这可能导致对问题的反应不可预测或延迟。
  • 监控二级资源可以确保及时处理不一致性，而不是等待控制器重启或外部事件来触发调整。

• 有效的生命周期管理:

  • 次要资源可能并不直接由控制者拥有，但它们的状态仍然会影响主要资源的行为。如果不对这些进行监控，就可能导致孤儿资源或过时资源的存在。
  • 观看非拥有的二级资源使控制器能够对可能影响主资源的生命周期事件（创建、更新、删除）作出响应，从而确保系统行为的一致性。

请参阅观看未拥有的次级资源以获取示例。

为什么不在所有场景中都使用 RequeueAfter X 而不是监听资源呢？

Kubernetes 控制器本质上是 事件驱动 的。在创建控制器时，调整循环 通常是由对资源的 create、update 或 delete 操作等 事件 触发的。这种事件驱动的方法相比于不断重新排队或轮询资源使用 RequeueAfter 更加高效和响应迅速。这确保了系统只在必要时采取行动，从而保持性能和效率。

在许多情况下，监视资源是确保Kubernetes资源保持在所需状态的首选方法。它更高效、更灵敏，并且与Kubernetes的事件驱动架构相一致。然而，在某些场景中，RequeueAfter是合适且必要的，特别是在管理不发出事件的外部系统或处理需要时间才能收敛的资源时，例如长时间运行的过程。仅依赖RequeueAfter处理所有场景可能导致不必要的开销和反应延迟。因此，至关重要的是优先考虑事件驱动的调整，通过在可能的情况下配置控制器以监视资源，并将RequeueAfter保留用于需要定期检查的情况。

RequeueAfter X 何时有用

虽然 RequeueAfter 不是触发调整的主要方法，但在某些特定情况下是必要的，例如：

• 观察外部系统：在处理不生成事件的外部资源（例如，外部数据库或第三方服务）时，RequeueAfter 允许控制器定期检查这些资源的状态。
• 基于时间的操作：一些任务，例如旋转密钥或更新证书，必须在特定的时间间隔内执行。RequeueAfter 确保这些操作按计划进行，即使没有其他更改发生。
• 处理错误或延迟：在管理遇到错误或需要时间自我修复的资源时，RequeueAfter 确保控制器在再次检查资源状态之前等待指定的时间，从而避免不断尝试进行调整。

谓词的使用

对于更复杂的使用场景，可以使用 谓词 来精确调整您的控制器何时应该触发状态同步。谓词允许您根据特定条件筛选事件，例如对特定字段、标签或注释的更改，从而确保您的控制器仅对相关事件做出响应，并高效地运行。

查看控制器“拥有“的二级资源

在 Kubernetes 控制器中，通常会同时管理 主资源 和 次资源。主资源 是控制器负责的主要资源，而 次资源 是由控制器创建和管理，以支持 主资源。

本节说明如何管理由 controller Owned 的次要资源（Secondary Resources）。本示例展示如何：

• 在主要资源（Busybox）和次要资源（Deployment）之间设置所有者引用，以确保正确的生命周期管理。
• 将控制器配置为在 SetupWithManager() 中使用 Owns() 监视次要资源。可以看到 Deployment 由 Busybox 控制器拥有，因为它将由该控制器创建和管理。

设置拥有者引用

要将次级资源（Deployment）的生命周期与主资源（Busybox）连接起来，我们需要在次级资源上设置一个 所有者引用。这确保了 Kubernetes 会自动处理层叠删除：如果主资源被删除，次级资源也会被删除。

Controller-runtime 提供了 controllerutil.SetControllerReference 函数，您可以使用它来设置资源之间的关系。

设置拥有者引用

下面，我们创建 Deployment 并使用 controllerutil.SetControllerReference() 在 Busybox 自定义资源和 Deployment 之间设置 Owner 引用。

// deploymentForBusybox 返回一个 Busybox 的 Deployment 对象
func (r *BusyboxReconciler) deploymentForBusybox(busybox *examplecomv1alpha1.Busybox) *appsv1.Deployment {
    replicas := busybox.Spec.Size

    dep := &appsv1.Deployment{
        ObjectMeta: metav1.ObjectMeta{
            Name:      busybox.Name,
            Namespace: busybox.Namespace,
        },
        Spec: appsv1.DeploymentSpec{
            Replicas: &replicas,
            Selector: &metav1.LabelSelector{
                MatchLabels: map[string]string{"app": busybox.Name},
            },
            Template: metav1.PodTemplateSpec{
                ObjectMeta: metav1.ObjectMeta{
                    Labels: map[string]string{"app": busybox.Name},
                },
                Spec: corev1.PodSpec{
                    Containers: []corev1.Container{
                        {
                            Name:  "busybox",
                            Image: "busybox:latest",
                        },
                    },
                },
            },
        },
    }

    // 设置 Deployment 的 ownerRef，确保在删除 Busybox CR 时，Deployment 也会被删除。
    controllerutil.SetControllerReference(busybox, dep, r.Scheme)
    return dep
}

Explanation

通过设置 OwnerReference，如果 Busybox 资源被删除，Kubernetes 会自动删除 Deployment。这还允许控制器监视 Deployment 的变化，并确保维护所需的状态（例如副本数）。

例如，如果有人修改了 Deployment，将副本数更改为 3，而 Busybox CR 定义的期望状态为 1 个副本，控制器将进行调整，确保 Deployment 缩减回 1 个副本。

对账函数示例

// Reconcile 处理 Busybox 和 Deployment 的主要调整循环。
func (r *BusyboxReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    log := logf.FromContext(ctx)

    // 获取 Busybox 实例
    busybox := &examplecomv1alpha1.Busybox{}
    if err := r.Get(ctx, req.NamespacedName, busybox); err != nil {
        if apierrors.IsNotFound(err) {
            log.Info("Busybox resource not found. Ignoring since it must be deleted")
            return ctrl.Result{}, nil
        }
        log.Error(err, "Failed to get Busybox")
        return ctrl.Result{}, err
    }

    // 检查部署是否已经存在，如果不存在则创建一个新的。
    found := &appsv1.Deployment{}
    err := r.Get(ctx, types.NamespacedName{Name: busybox.Name, Namespace: busybox.Namespace}, found)
    if err != nil && apierrors.IsNotFound(err) {
        // 定义一个新的部署
        dep := r.deploymentForBusybox(busybox)
        log.Info("Creating a new Deployment", "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
        if err := r.Create(ctx, dep); err != nil {
            log.Error(err, "无法创建新的部署", "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
            return ctrl.Result{}, err
        }
        // 重新排队请求以确保创建部署
        return ctrl.Result{RequeueAfter: time.Minute}, nil
    } else if err != nil {
        log.Error(err, "Failed to get Deployment")
        return ctrl.Result{}, err
    }

    // 确保部署大小与期望状态匹配
    size := busybox.Spec.Size
    if *found.Spec.Replicas != size {
        found.Spec.Replicas = &size
        if err := r.Update(ctx, found); err != nil {
            log.Error(err, "Failed to update Deployment size", "Deployment.Namespace", found.Namespace, "Deployment.Name", found.Name)
            return ctrl.Result{}, err
        }
        // 重新排队请求以确保达到正确的状态
        return ctrl.Result{RequeueAfter: time.Minute}, nil
    }

    // 更新 Busybox 状态以反映该部署可用
    busybox.Status.AvailableReplicas = found.Status.AvailableReplicas
    if err := r.Status().Update(ctx, busybox); err != nil {
        log.Error(err, "Failed to update Busybox status")
        return ctrl.Result{}, err
    }

    return ctrl.Result{}, nil
}

观看辅助资源

为了确保对次要资源（例如 Deployment）的更改能够触发对主要资源（Busybox）的对账，我们配置控制器以监视这两个资源。

Owns() 方法允许您指定控制器应该监控的辅助资源。这样，控制器将在辅助资源发生变化（例如，被更新或删除）时自动调整主资源。

示例：配置 SetupWithManager 以监视辅助资源

// SetupWithManager 使用 Manager 设置控制器。
// 控制器将同时监视 Busybox 主资源和 Deployment 次资源。
func (r *BusyboxReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&examplecomv1alpha1.Busybox{}).  // 观看主要资源
        Owns(&appsv1.Deployment{}).          // 监视次要资源（部署）
        Complete(r)
}

确保正确的权限

Kubebuilder 使用 标记 来定义控制器所需的 RBAC 权限。为了使控制器能够正确监视和管理主资源（Busybox）和次资源（Deployment），必须授予其适当的权限；即对这些资源具有 watch、get、list、create、update 和 delete 权限。

示例：RBAC 标记

在 Reconcile 方法之前，我们需要定义适当的 RBAC 标记。这些标记将由 controller-gen 在您运行 make manifests 时，用于生成所需的角色和权限。

// +kubebuilder:rbac:groups=example.com,resources=busyboxes,verbs=获取;列表;观察;创建;更新;补丁;删除
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=获取;列表;观察;创建;更新;补丁;删除

• 第一个标记授予控制器管理 Busybox 自定义资源（主要资源）的权限。
• 第二个标记授予控制器管理 Deployment 资源（次要资源）的权限。

请注意，我们正在授予对资源的 watch 权限。

观看未“拥有“的辅助资源

在某些情况下，控制器可能需要监视并响应它并不“拥有“的资源的变化，这意味着这些资源是由另一个控制器创建和管理的。

以下示例演示了控制器如何监控和对账它不直接管理的资源。这适用于任何不是由控制器“拥有“的资源，包括由其他控制器或项目管理的核心类型或自定义资源，并在单独的流程中进行对账。

例如，考虑两个自定义资源——Busybox 和 BackupBusybox。如果对 Busybox 的更改应该触发 BackupBusybox 控制器的调整，我们可以配置 BackupBusybox 控制器来监视 Busybox 的更新。

示例：监视未拥有的 Busybox 资源以重新调整 BackupBusybox

考虑一个控制器，它管理一个自定义资源 BackupBusybox，同时需要监控整个集群中 Busybox 资源的变化。我们只希望在 Busybox 实例启用备份功能时触发对其的调整。

• 为什么观看二次资源？
  • BackupBusybox 控制器并不负责创建或拥有 Busybox 资源，但这些资源的变化（例如更新或删除）会直接影响主要资源（BackupBusybox）。
  • 通过监视具有特定标签的 Busybox 实例，控制器确保只有相关资源触发必要的操作（例如备份）。

配置示例

以下是如何配置 BackupBusyboxReconciler 以监视 Busybox 资源的更改并触发 BackupBusybox 的对账：

// SetupWithManager 用于设置控制器与管理器。
// 控制器将监视 BackupBusybox 主要资源和 Busybox 资源。
func (r *BackupBusyboxReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&examplecomv1alpha1.BackupBusybox{}).  // 观察主要资源（BackupBusybox）
        Watches(
            &examplecomv1alpha1.Busybox{},  // 观察 Busybox CR
            handler.EnqueueRequestsFromMapFunc(func(ctx context.Context, obj client.Object) []reconcile.Request {
                // 在同一命名空间中触发 BackupBusybox 的同步
                return []reconcile.Request{
                    {
                        NamespacedName: types.NamespacedName{
                            Name:      "backupbusybox",  // 对关联的 BackupBusybox 资源进行调整
                            Namespace: obj.GetNamespace(),  // 使用已更改的 Busybox 命名空间
                        },
                    },
                }
            }),
        ).  // 当 Busybox 资源发生变化时触发调整。
        Complete(r)
}

以下是我们如何配置控制器，以仅过滤和监视具有特定标签的 Busybox 资源的变化：

// SetupWithManager 用于将控制器与管理器进行设置。
// 控制器将监视 BackupBusybox 主要资源和 Busybox 资源，并按标签进行过滤。
func (r *BackupBusyboxReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&examplecomv1alpha1.BackupBusybox{}).  // 观察主要资源（BackupBusybox）
        Watches(
            &examplecomv1alpha1.Busybox{},  // 观察 Busybox CR
            handler.EnqueueRequestsFromMapFunc(func(ctx context.Context, obj client.Object) []reconcile.Request {
                // 检查 Busybox 资源是否有标签 'backup-needed: "true"' 
                if val, ok := obj.GetLabels()["backup-enable"]; ok && val == "true" {
                    // 如果标签存在并设置为"true"，则触发 BackupBusybox 的对账
                    return []reconcile.Request{
                        {
                            NamespacedName: types.NamespacedName{
                                Name:      "backupbusybox",  // 对关联的 BackupBusybox 资源进行调整
                                Namespace: obj.GetNamespace(),  // 使用已更改的 Busybox 命名空间
                            },
                        },
                    }
                }
                // 如果标签不存在或不匹配，则不触发和解
                return []reconcile.Request{}
            }),
        ).  // 当标记的 Busybox 资源发生变化时触发重对账
        Complete(r)
}

使用谓词来优化手表

在使用控制器时，使用 谓词 来过滤事件和控制何时触发调整循环通常是有益的。

谓词 允许您基于事件（例如创建、更新或删除）和资源字段（例如标签、注释或状态字段）定义条件。通过使用 谓词，您可以细化控制器的行为，使其仅对所观察资源的特定变化做出响应。

这在你想要细化哪些资源的变化应该触发对账时尤其有用。通过使用谓词，你可以避免不必要的对账，并确保控制器仅对相关变化做出反应。

何时使用谓词

谓词在以下情况下很有用：

• 您想忽略某些更改，例如那些不影响控制器关注的字段的更新。
• 您只想对具有特定标签或注释的资源触发调整。
• 您希望监视外部资源，并仅对特定更改做出反应。

示例：使用谓词过滤更新事件

假设 BackupBusybox controller 仅应在 Busybox 资源的某些字段变更时对账，例如 spec.size 字段变更，而应忽略所有其他变更（如 status 更新）。

定义谓词

在下面的示例中，我们定义了一个谓词，仅在对 Busybox 资源有重要更新时才允许对账：

import (
    "sigs.k8s.io/controller-runtime/pkg/predicate"
    "sigs.k8s.io/controller-runtime/pkg/event"
)

// 仅在 Busybox 规格的大小变化时触发重新调整的谓词
updatePred := predicate.Funcs{
    // 仅在 Busybox 资源的 spec.size 发生变化时允许更新
    UpdateFunc: func(e event.UpdateEvent) bool {
        oldObj := e.ObjectOld.(*examplecomv1alpha1.Busybox)
        newObj := e.ObjectNew.(*examplecomv1alpha1.Busybox)

        // 仅在 spec.size 字段发生变化时触发重新对账
        return oldObj.Spec.Size != newObj.Spec.Size
    },

    // 允许创建事件
    CreateFunc: func(e event.CreateEvent) bool {
        return true
    },

    // 允许删除事件
    DeleteFunc: func(e event.DeleteEvent) bool {
        return true
    },

    // 允许通用事件（例如，外部触发）
    GenericFunc: func(e event.GenericEvent) bool {
        return true
    },
}

Explanation

在这个例子中：

• UpdateFunc 仅在 spec.size 字段在旧对象和新对象之间发生变化时返回 true，这意味着在 spec 中的其他所有更改（例如注释或其他字段）将被忽略。
• CreateFunc、DeleteFunc 和 GenericFunc 返回 true，意味着创建、删除和通用事件仍然被处理，从而允许这些事件类型的调整发生。

这确保了只有在特定字段 spec.size 被修改时，控制器才会进行调整，而忽略 spec 中与您的逻辑无关的其他修改。

示例：在Watches中使用谓词

现在，我们将这个谓词应用在 BackupBusyboxReconciler 的 Watches() 方法中，以便仅针对相关事件触发重新对账：

// SetupWithManager 使用 Manager 设置控制器。
// 控制器将同时监视 BackupBusybox 主要资源和 Busybox 资源，并使用谓词。
func (r *BackupBusyboxReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&examplecomv1alpha1.BackupBusybox{}).  // 观察主要资源（BackupBusybox）
        Watches(
            &examplecomv1alpha1.Busybox{},  // 观察 Busybox CR
            handler.EnqueueRequestsFromMapFunc(func(ctx context.Context, obj client.Object) []reconcile.Request {
                return []reconcile.Request{
                    {
                        NamespacedName: types.NamespacedName{
                            Name:      "backupbusybox",  // 对关联的 BackupBusybox 资源进行调整
                            Namespace: obj.GetNamespace(),  // 使用已更改的 Busybox 命名空间
                        },
                    },
                }
            }),
            builder.WithPredicates(updatePred),  // 应用谓词
        ).  // 当 Busybox 资源发生变化时触发调整（如果符合谓词条件）
        Complete(r)
}

Explanation

• builder.WithPredicates(updatePred)：此方法应用谓词，确保只有在 Busybox 中 spec.size 字段发生变化时才会进行调解。
• 其他事件：控制器仍将在 创建、删除 和 通用 事件上触发调整。

使用 Kind 进行开发目的和持续集成（CI）

为什么使用 Kind

• 快速设置： 在一分钟内在本地启动一个多节点的Kubernetes集群。
• 快速拆解： 仅需几秒钟即可拆解集群，简化您的开发工作流程。
• 本地镜像使用： 可以直接部署您的容器镜像，无需推送到远程注册中心。
• 轻量高效： Kind 是一个极简的 Kubernetes 发行版，非常适合本地开发和 CI/CD 流程。

这仅涵盖了使用 kind 集群的基础知识。您可以在 kind 文档 中找到更多详细信息。

安装

按照 kind 安装说明 安装 kind。

创建一个集群

您可以通过以下方式简单地创建一个 kind 集群：

kind create cluster

要自定义您的集群，您可以提供额外的配置。例如，以下是一个示例 kind 配置。

kind: 集群
apiVersion: kind.x-k8s.io/v1alpha4
节点:
  - 角色: 控制平面
  - 角色: 工人
  - 角色: 工人
  - 角色: 工人

使用上述配置，运行以下命令将为您提供一个包含 1 个控制平面节点和 3 个工作节点的 k8s v1.17.2 集群。

kind create cluster --config hack/kind-config.yaml --image=kindest/node:v1.17.2

您可以使用 --image 参数指定您想要的集群版本，例如 --image=kindest/node:v1.17.2，支持的版本可以在 这里 查看。

将 Docker 镜像加载到集群中

在使用本地 kind 集群进行开发时，将 Docker 镜像加载到集群中是一个非常有用的功能。您可以避免使用容器注册表。

kind load docker-image your-image-name:your-tag

请参阅 将本地镜像加载到 kind 集群 以获取更多信息。

删除集群

kind delete cluster

Webhook（网络钩子）

Webhooks 是以阻塞方式发送的信息请求。实现 Webhook 的 web 应用程序会在某个事件发生时向其他应用程序发送 HTTP 请求。

在Kubernetes世界中，有三种类型的Webhook：准入Webhook、授权Webhook和CRD转换Webhook。

在 controller-runtime 库中，我们支持准入 webhook 和 CRD 转换 webhook。

Kubernetes 从 1.9 版本开始支持这些动态 Admission Webhooks（当时该功能进入 beta 阶段）。

Kubernetes 从 1.15 版本开始支持转换 Webhook（该功能在此时进入测试版）。

禁用 Webhook 服务器

设置 --webhook-port=-1 以禁用 Webhook 服务器：

./bin/manager --webhook-port=-1

controller-runtime 会记录 Webhook server is disabled 且不监听任何端口。这需要 controller-runtime v0.25.0 或更高版本。旧版本会将 -1 视为默认的 9443。

仅在没有 webhook 配置或 CRD conversion 指向该 manager 时禁用服务器。否则 API 服务器无法到达 webhook，并会拒绝它们所守护的请求。

使用 make run 在本地运行 manager 时若要跳过 Webhook 注册，请设置 ENABLE_WEBHOOKS=false。

入场webhook

Admission Webhooks 是接收入场请求的 HTTP 回调，处理这些请求并返回入场响应。

Kubernetes 提供以下类型的准入 webhook：

• 变更Admission Webhook：这些Webhook可以在对象创建或更新时对其进行变更，在对象被存储之前。它可以用于在资源请求中设置字段的默认值，例如，在用户未指定的Deployment字段中。还可以用于注入边车容器。

• 验证入场 Webhook：这些可以在对象被创建或更新时进行验证，确保其在存储之前有效。它允许比纯基于模式的验证更复杂的验证，例如跨字段验证和容器镜像白名单。

默认情况下，apiserver 并不会对 webhook 进行身份验证。然而，如果您想要对客户端进行身份验证，您可以配置 apiserver 使用基本身份验证、令牌或证书来对 webhook 进行身份验证。您可以在这里找到详细步骤。

Custom webhook paths

默认情况下，Kubebuilder 根据资源的 group、version 和 kind 生成 Webhook 路径。例如：

• batch/v1/CronJob 的变更 Webhook：/mutate-batch-v1-cronjob
• batch/v1/CronJob 的校验 Webhook：/validate-batch-v1-cronjob

你可以使用专用标志为 Webhook 指定自定义路径：

# Custom path for defaulting webhook
kubebuilder create webhook --group batch --version v1 --kind CronJob \
  --defaulting --defaulting-path=/my-custom-mutate-path

# Custom path for validation webhook
kubebuilder create webhook --group batch --version v1 --kind CronJob \
  --programmatic-validation --validation-path=/my-custom-validate-path

# Both webhooks with different custom paths
kubebuilder create webhook --group batch --version v1 --kind CronJob \
  --defaulting --programmatic-validation \
  --defaulting-path=/custom-mutate --validation-path=/custom-validate

在入场Webhook中处理资源状态

理解原因：

变异 admission Webhooks

变更的 Admission Webhooks 主要旨在拦截和修改与对象的创建、修改或删除相关的请求。尽管它们具备修改对象规格的能力，但直接更改对象的状态并不被视为标准做法，通常会导致意外结果。

// MutatingWebhookConfiguration 允许对对象进行修改。
// 然而，直接修改状态可能会导致意外行为。
type MutatingWebhookConfiguration struct {
    ...
}

设置初始状态

对于那些深入研究自定义资源的自定义控制器的人来说，了解设置初始状态的概念是至关重要的。这个初始化通常在控制器内部进行。当控制器通过监视机制识别到其管理资源的新实例时，它有权为该资源分配一个初始状态。

// 自定义控制器的调整函数可能看起来像这样：
func (r *ReconcileMyResource) Reconcile(request reconcile.Request) (reconcile.Result, error) {
    // ...
    // 在发现新实例时，设置初始状态
    instance.Status = SomeInitialStatus
    // ...
}

状态子资源

深入研究 Kubernetes 自定义资源时，可以明确区分 spec（描述期望状态）和 status（展示观察到的状态）。为自定义资源定义（CRD）启用 /status 子资源，将 status 和 spec 分开，各自分配给相应的 API 端点。这样的分离确保了用户引入的变更，例如修改 spec，以及系统驱动的更新，如状态变化，能够保持明确的区分。在修改 spec 操作期间利用变更的 webhook 来调整状态，可能无法如预期那样顺利进行，这要归功于这种隔离。

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myresources.mygroup.mydomain
spec:
  ...
  subresources:
    status: {} # 启用 /status 子资源

结论

虽然某些边缘场景可能允许变更的 webhook 无缝地修改状态，但走这条道路并不是普遍认可或推荐的策略。将状态更新的责任交给控制器逻辑仍然是最被提倡的方法。

Webhook 引导问题

问题所在

当你为核心 Kubernetes 类型（Pod、Deployment、Job 等）创建 webhook 时，该 webhook 可能阻塞其自身 controller Pod 的启动，导致部署死锁。

示例命令：

kubebuilder create webhook --group core --version v1 --kind Pod --programmatic-validation

示例场景：

1. 你为 Pod 创建校验 Webhook
2. 你部署控制器（以 Pod 运行）
3. Kubernetes 尝试创建你的控制器 Pod
4. 你的 Webhook 会拦截此次 Pod 创建
5. Webhook 服务器尚未就绪（它位于正在创建的 Pod 内）
6. Pod 创建会挂起，等待 Webhook 校验
7. 由于 Pod 被阻塞，Webhook 永远无法启动

结果： 死锁。你的部署失败。

这种情况何时发生？

核心 Kubernetes 类型

为内置 Kubernetes 资源创建 Webhook 时会出现引导问题：

• core group: Pod, Service, Namespace, ConfigMap, Secret
• apps group: Deployment, StatefulSet, DaemonSet, ReplicaSet
• batch group: Job, CronJob
• 其他内置类型

为什么？ 你的 webhook 验证的资源类型，正是 controller 部署所创建的类型（通常是 Pod 或 Deployment）。

自定义 CRD

自定义资源 Webhook 不会出现引导问题：

• 你的 Webhook 校验 MyResource 对象
• 你的控制器以 Pod 运行
• Pod 与 MyResource 是不同类型
• 无循环依赖

如何修复

使用 namespaceSelector 或 objectSelector 配置 Webhook 跳过校验自身资源。

选项 1：namespaceSelector (recommended)

排除你的 Webhook 运行所在的整个命名空间。

步骤 1： 在 config/manager/manager.yaml 中为 Namespace 添加标签：

apiVersion: v1
kind: Namespace
metadata:
  labels:
    控制平面: 控制器管理器
    app.kubernetes.io/name: my-project
    app.kubernetes.io/managed-by: kustomize
    webhook-excluded: "true"
  name: system

步骤 2： 创建补丁文件 config/webhook/namespaceselector_patch.yaml：

# For mutating webhooks (--defaulting)
- op: add
  path: /webhooks/0/namespaceSelector
  value:
    匹配表达式:
    - key: webhook-excluded
      操作员: DoesNotExist

对于 validating webhook（--programmatic-validation），创建类似补丁并指向 ValidatingWebhookConfiguration。

步骤 3： 将补丁添加到 config/webhook/kustomization.yaml：

resources:
- manifests.yaml
- service.yaml

贴片:
- path: namespaceselector_patch.yaml
  目标:
    group: admissionregistration.k8s.io
    version: v1
    kind: 变更Webhook配置
    name: mutating-webhook-configuration

步骤 4： 部署：

make deploy IMG=<your-image>

选项 2：objectSelector

将带特定标签的 Pod 排除在 Webhook 校验之外。

步骤 1： 在 config/manager/manager.yaml 中为 Pod 添加标签：

spec:
  template:
    metadata:
      annotations:
        kubectl.kubernetes.io/default-container: manager
      labels:
        控制平面: 控制器管理器
        app.kubernetes.io/name: my-project
        webhook-excluded: "true"

步骤 2-4： 与选项 1 相同，但在补丁文件中使用 objectSelector 而非 namespaceSelector。

多个 Webhook

如果为多个核心类型（例如 Pod 和 Deployment）创建了 Webhook，你会有多个 Webhook 条目。

检查 Webhook 数量：

make manifests
grep "  name: m" config/webhook/manifests.yaml  # Count mutating webhooks
grep "  name: v" config/webhook/manifests.yaml  # Count validating webhooks

示例输出：

  name: mpod-v1.kb.io         # Index 0
  name: mdeployment-v1.kb.io  # Index 1

在补丁文件中为所有索引添加补丁：

- op: add
  path: /webhooks/0/namespaceSelector
  value:
    匹配表达式:
    - key: webhook-excluded
      操作员: DoesNotExist
- op: add
  path: /webhooks/1/namespaceSelector
  value:
    匹配表达式:
    - key: webhook-excluded
      操作员: DoesNotExist

混合 Webhook（CRD + 核心类型）

如果你同时有自定义 CRD Webhook 和核心类型 Webhook：

• CRD Webhook 在配置中首先出现
• 核心类型 Webhook 出现在之后
• 统计全部 Webhook，并为你的核心类型 Webhook 索引添加补丁

示例： 若有 1 个 CRD Webhook（索引 0）和 1 个核心类型 Webhook（索引 1），补丁应针对索引 1：

- op: add
  path: /webhooks/1/namespaceSelector
  value:
    匹配表达式:
    - key: webhook-excluded
      操作员: DoesNotExist

在 namespaceSelector 与 objectSelector 之间选择

建议： 除非需要细粒度控制，否则使用 namespaceSelector。

References

• Kubernetes Admission Webhook 最佳实践
• namespaceSelector API 参考
• objectSelector API 参考

配置/代码生成标记

Kubebuilder 使用一个名为 controller-gen 的工具来生成实用代码和 Kubernetes YAML。此代码和配置的生成是通过在 Go 代码中添加特殊的“标记注释“来控制的。

标记是以加号开头的单行注释，后面跟着标记名称，后面可以选择性地跟上一些标记特定配置：

// +kubebuilder:validation:可选
// +kubebuilder:validation:最大项数=2
// +kubebuilder:printcolumn:JSONPath=".status.replicas",name=副本数,type=string

请查看每个子部分以获取有关不同类型代码和 YAML 生成的信息。

在 Kubebuilder 中生成代码和工件

Kubebuilder 项目有两个 make 目标，用于使用 controller-gen：

• make manifests 生成 Kubernetes 对象 YAML，如 CustomResourceDefinitions、WebhookConfigurations 和 RBAC roles。启用 Server-Side Apply 时，还会生成 ApplyConfiguration 类型。

• make generate 生成代码，例如 runtime.Object/DeepCopy 实现。

请查看生成 CRD以获取全面概述。

标记语法

确切的语法在 controller-tools 的文档 中进行了描述。

通常，标记可以是：

• 空 (+kubebuilder:validation:Optional): 空标记就像命令行上的布尔标志 -- 仅仅指定它们就可以启用某些行为。

• 匿名 (+kubebuilder:validation:MaxItems=2): 匿名标记的参数只能接受一个值。

• 多选项 (+kubebuilder:printcolumn:JSONPath=".status.replicas",name=Replicas,type=string): 多选项标记可以接受一个或多个命名参数。 第一个参数通过冒号与名称分隔，后续参数用逗号分隔。 参数的顺序没有关系。 某些参数可能是可选的。

标记参数可以是字符串、整数、布尔值、切片或它们的映射。字符串、整数和布尔值遵循它们的 Go 语法：

// +kubebuilder:validation:ExclusiveMaximum=false
// +kubebuilder:validation:Format="date-time"
// +kubebuilder:validation:Maximum=42

为了方便，对于简单情况，可以省略字符串中的引号，但不鼓励在单词字符串以外的其他情况下这样做：

// +kubebuilder:validation:Type=string

切片可以通过用大括号包围并用逗号分隔来指定：

// +kubebuilder:webhooks:Enum={"饼干, 龟兔赛跑, 我们忘记带饼干了!","连温斯莱代尔奶酪都没有吗?"}

或在简单情况下，用分号分隔：

// +kubebuilder:validation:Enum=华莱士;格罗米特;鸡

映射使用字符串键和任何类型的值指定（实际上是 map[string]interface{}）。映射用大括号（{}）包围，每个键和值之间用冒号（:）分隔，每对键值对之间用逗号分隔：

// +kubebuilder:default={magic: {numero: 42, stringified: 四十二}}

CRD 生成

这些标记描述了如何根据一系列 Go 类型和包构建自定义资源定义。实际验证模式的生成由验证标记描述。

请参见生成 CRD以获取示例。

CRD 验证

这些标记会修改 CRD 验证模式在其修改的类型和字段上的生成方式。每个标记大致对应于一个 OpenAPI/JSON 模式选项。

请参阅 生成 CRD 以获取示例。

CRD处理

这些标记有助于控制 Kubernetes API 服务器如何处理涉及您的自定义资源的 API 请求。

请参阅 生成 CRD 以获取示例。

Webhook（网络钩子）

这些标记描述了如何生成 webhook 配置。使用这些标记可以让您的 webhook 描述与实现它们的代码保持紧密关联。

对象/深拷贝

这些标记控制何时生成 DeepCopy 和 runtime.Object 实现方法。

Apply Configuration

这些 markers 控制何时为包中的 kind 生成 ApplyConfiguration 类型。这些类型为构建 Server-Side Apply 补丁提供了类型安全的方式。

关于 --ssa 标志如何启用此生成，以及如何使用生成类型的示例，请参阅 Server-Side Apply 参考。

RBAC

这些标记会生成一个 RBAC ClusterRole。这使您能够在使用这些权限的代码旁边描述您的控制器所需的权限。