简单包学习

第一阶段：打通 YAML 与 Go 代码的“次元壁”

在 K8s 中，所有的资源（Pod、Deployment、以及你自己定义的 CRD）在代码里都是一个 Struct（结构体）。

核心包的职责分工

你需要关注的包只有这两个：

• k8s.io/apimachinery/pkg/apis/meta/v1 (通常别名为 metav1)：

  • 职责：定义“元数据”。不管你是 Pod 还是自定义资源，只要在 K8s 里，就必须有名字、标签这些通用的属性。

• k8s.io/api/... (如 core/v1 或 apps/v1)：

  • 职责：定义“具体零件”。比如 Pod 的容器镜像、端口号等具体业务字段。

K8s 对象的“标准四部曲”

几乎所有的 K8s Go 结构体都由这四个部分组成。请看这个对照表，这是最核心的映射关系：

YAML 字段	Go 结构体中的字段	类型	说明
apiVersion / kind	TypeMeta	metav1.TypeMeta	定义这是什么资源（如 v1 版的 Pod）。
metadata	ObjectMeta	metav1.ObjectMeta	重点： 包含 Name, Namespace, Labels。
spec	Spec	自定义结构体	重点： 用户的“期望”。你想要什么样？
status	Status	自定义结构体	重点： 集群的“现实”。现在变成了什么样？

深度拆解：ObjectMeta（你最常操作的部分）

当你创建一个 Operator 时，你经常需要读取或修改 metadata。在 Go 代码里，它对应 metav1.ObjectMeta 结构体。

最常用的字段：

• Name: 资源的名称。

• Namespace: 所属命名空间。

• Labels: 一个 map[string]string，用于过滤和关联资源。

• Annotations: 存储额外信息（通常不作为搜索条件）。

• OwnerReferences: 一个数组。Operator 极其关键的字段，用来实现“父子绑定”。删除了父资源，K8s 会根据这个字段自动删除关联的子资源。

第二阶段：玩转“增删改查”（CRUD）

在第一阶段你学会了如何定义资源，现在你要学习如何通过代码去“操控”它们。这是 Operator 逻辑中最核心的部分。在 Kubebuilder 中，我们主要使用 sigs.k8s.io/controller-runtime/pkg/client 这个包提供的 Client 接口。

核心工具：client.Client

为什么不用 client-go 的原生接口？ 因为 Kubebuilder 提供的这个 Client 做了极强的封装：

• 读操作： 默认从本地缓存（Informer）读，速度极快。当你执行 Get 或 List 时，它默认是从本地内存（Informer 维护的缓存）读取，而不是每次都冲向 API Server，这极大减轻了集群压力。

• 写操作： 直接写向 API Server。

• 智能： 它能根据你传入的结构体自动判断去调哪个 API 路径。

获取资源：Get (查单个)

这是你写 Reconcile 函数的第一步：先拿到你要处理的那个对象。

• 关键点： 需要 types.NamespacedName（包含 Name 和 Namespace）。

• 必须关注： 错误处理。如果资源不存在，API 会返回一个错误，你需要判断它是“真出错了”还是“资源被删除了”。

import (
    "context"
    "sigs.k8s.io/controller-runtime/pkg/client"
    corev1 "k8s.io/api/core/v1" // 核心资源包
    "k8s.io/apimachinery/pkg/types" // 新包：定义 K8s 基础类型，如 NamespacedName
    "k8s.io/apimachinery/pkg/api/errors" // 错误识别。专门用来判断“这个报错是不是因为资源没找到？”或者是“是不是权限不足？”。
)

func (r *MyReconciler) DemoGet(ctx context.Context) {
    // 1. 定义一个 NamespacedName，它是 Get 方法的“地址卡”
    // 为什么：K8s 里的资源是通过 命名空间+名字 唯一确定的
    objKey := types.NamespacedName{
        Namespace: "default",
        Name:      "my-pod",
    }

    // 2. 声明一个结构体变量来接收结果
    // 为什么：Get 方法需要一个“容器”来存放从集群拿回来的数据
    pod := &corev1.Pod{}
	
    // 3. 执行 Get
    // 参数说明：
    // - ctx: 控制超时和取消
    // - objKey: 告诉客户端查哪个
    // - pod: 传入指针，查询结果会填充到这个变量里
    err := r.Get(ctx, objKey, pod)
    if errors.IsNotFound(err) { // 资源被删除了，这时候直接返回，不需要报 error，否则会触发无效重试 
    return ctrl.Result{}, nil 
    } // 其他读取错误（如网络问题、RBAC 权限不足），需要返回 error 让 K8s 重试 
    return ctrl.Result{}, err
}
    if err != nil {
        // 返回错误的处理：如果报错是因为“没找到”，通常代表资源被删了
        return
    }
}

获取列表：List (查一批)

场景：你想知道当前命名空间下有多少个 Pod。

• 关键点： 使用 client.InNamespace 或 client.MatchingLabels 进行过滤。

func (r *MyReconciler) DemoList(ctx context.Context) {
    // 1. 声明一个 List 类型的“容器”
    podList := &corev1.PodList{}

    // 2. 设定过滤条件（可选）
    // 目的：如果不加条件，会把整个 Namespace 下的所有 Pod 都捞出来
    listOpts := []client.ListOption{
        client.InNamespace("default"),
        client.MatchingLabels{"app": "nginx"}, // 只找带 app=nginx 标签的
    }

    // 3. 执行 List
    err := r.List(ctx, podList, listOpts...)
    
    // podList.Items 就是最终的 Pod 数组
}

创建资源：Create (增)

• 关键点： 必须先手动填好 ObjectMeta（名字和空间）。

• 重要细节： 在第二阶段，如果你创建的是子资源（比如你的 CR 创建了一个 Deployment），必须建立父子关系（这属于第五阶段提前剧透，但这里必须提，否则删不掉）。

func (r *MyReconciler) DemoCreate(ctx context.Context) {
    newPod := &corev1.Pod{
        // 记得第一阶段学的吗？必须填 TypeMeta 和 ObjectMeta
        ObjectMeta: metav1.ObjectMeta{
            Name:      "new-pod",
            Namespace: "default",
        },
        Spec: corev1.PodSpec{
            Containers: []corev1.Container{
                {Name: "nginx", Image: "nginx"},
            },
        },
    }

    // 执行创建
    // 返回值：err 如果不为空，可能是权限不足或名字冲突
    err := r.Create(ctx, newPod)
}

修改资源：Update 与 Status().Update() (改)

这是初学者最容易掉坑的地方！

• 普通 Update： 修改 Spec、Labels、Annotations 等。

• Status().Update()： 专门修改 Status 部分。K8s 建议将 Spec 和 Status 分开更新，因为 Status 是由控制器计算出来的，不是用户填写的。

// 1. 修改 Spec (用户期望)
instance.Spec.Replicas = 5
err := r.Update(ctx, instance)

// 2. 修改 Status (当前现实) —— 必须用 .Status() 
instance.Status.ReadyReplicas = 3
err := r.Status().Update(ctx, instance)

删除资源：Delete (删)

相对简单，直接传入对象即可。

err := r.Delete(ctx, instance)

第二阶段的高级“性价比”知识点

冲突处理：RetryOnConflict

当你执行 Update 时，如果此时有别人也在改这个资源，K8s 会报 Conflict 错误导致更新失败。 最快应对方案： 使用 k8s.io/client-go/util/retry 包。

import "k8s.io/client-go/util/retry"

err := retry.RetryOnConflict(retry.DefaultRetry, func() error {
    // 1. 重新 Get 一次最新数据（必做！）
    latest := &webv1.MyWebApp{}
    if err := r.Get(ctx, req.NamespacedName, latest); err != nil {
        return err
    }
    // 2. 做你的修改
    latest.Spec.Replicas = 10
    // 3. 返回 Update 结果
    return r.Update(ctx, latest)
})

所有的调用都要传 ctx (Context)

你会发现每个方法第一个参数都是 ctx。这是为了控制超时和取消。在 Reconcile 函数开头传入的那个 ctx 直接透传给 client 即可。

永远传递指针

不管是 Get 还是 Update，传入的资源对象必须是指针（例如 &instance），因为 client 需要修改该对象的内容。

零值处理： 在修改资源并 Update 时，确保你没有无意中把某些字段改成了零值（如把副本数改成了 0），这会导致集群状态发生非预期的剧烈波动。

添加权限

别忘了 RBAC 权限： 你在代码里写了 r.Create(pod)，但如果你没在 controller.go 的注释里加上 // +kubebuilder:rbac:groups=core,resources=pods,verbs=create，你的 Operator 运行起来就会报 Forbidden。

数据读取逻辑

读数据默认是“过时的”： 记住，r.Get 读的是 Cache（内存缓存）。如果你刚刚 Create 了一个 Pod，下一行立即 Get，可能拿不到。这是分布式系统的最终一致性。不要为此写死循环等待，而要依靠下一次 Reconcile。

第三阶段：控制“大脑”——深度理解 Reconcile（调解）循环与幂等性设计

核心概念：什么是幂等性（Idempotency）？

在分布式系统中，网络会抖动，进程会崩溃。Reconcile 函数可能会因为各种原因被反复调用（比如一分钟调用 100 次）。 幂等性要求： 无论 Reconcile 被调用 1 次还是 100 次，最终对集群产生的结果必须是一样的。

大脑的逻辑公式： 期望状态 (Spec) - 实际状态 (Actual) = 动作 (Action)。

核心包介绍

• sigs.k8s.io/controller-runtime/pkg/reconcile

  • 作用：定义了调解循环的输入（Request）和输出（Result）。

  • 核心结构：Request 仅包含资源的名称和命名空间；Result 决定了下一次调解什么时候发生。

• sigs.k8s.io/controller-runtime/pkg/log

  • 作用：提供结构化日志（基于 zap）。

  • 重要性：在 Operator 中不要使用 fmt.Println，因为结构化日志可以自动带上控制器名称和请求上下文，方便排查大规模集群中的问题。

• reflect (Go 标准库)

  • 作用：用于深度比较两个对象是否相等。

  • 场景：判断“现在的 Deployment 配置”是否真的需要更新，避免无效的 API 调用。

最佳实践代码演示：一个完整的调解逻辑

我们以一个管理 Deployment 的自定义资源为例。这段代码展示了如何处理：检测 -> 创建 -> 比对规格 -> 更新状态。

import (
	"context"
	"reflect"
	"time"

	appsv1 "k8s.io/api/apps/v1"
	corev1 "k8s.io/api/core/v1"
	"k8s.io/apimachinery/pkg/api/errors"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/log"
	"sigs.k8s.io/controller-runtime/pkg/reconcile"
)

// Reconcile 是 Operator 的灵魂：它观察现状，并尝试向期望状态靠拢
func (r *MyReconciler) Reconcile(ctx context.Context, req reconcile.Request) (reconcile.Result, error) {
	// 1. 初始化结构化日志
	// 目的：让日志自动带上正在处理的资源名称 [Name/Namespace]
	logger := log.FromContext(ctx)

	// 2. 获取期望状态 (获取你的自定义资源 CR)
	var myApp webv1.MyWebApp
	if err := r.Get(ctx, req.NamespacedName, &myApp); err != nil {
		if errors.IsNotFound(err) {
			// 目的：处理资源被删除的情况
			// 如果没找到，说明 CR 被删除了，此时子资源（设置了 OwnerReference 的）会被 K8s 自动清理
			return reconcile.Result{}, nil
		}
		return reconcile.Result{}, err
	}

	// 3. 观察实际状态：查找集群中是否已经存在对应的 Deployment
	foundDeployment := &appsv1.Deployment{}
	err := r.Get(ctx, client.ObjectKey{Name: myApp.Name, Namespace: myApp.Namespace}, foundDeployment)

	// 逻辑分支 A：如果 Deployment 不存在 -> 创建它
	if err != nil && errors.IsNotFound(err) {
		// 定义一个新的 Deployment
		dep := r.deploymentForMyApp(&myApp)
		logger.Info("正在创建新的 Deployment", "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
		
		if err := r.Create(ctx, dep); err != nil {
			logger.Error(err, "创建 Deployment 失败")
			return reconcile.Result{}, err
		}
		// 创建成功后，通常建议 Requeue，以便进入下一轮检查状态
		return reconcile.Result{Requeue: true}, nil
	} else if err != nil {
		return reconcile.Result{}, err
	}

	// 逻辑分支 B：如果 Deployment 已存在 -> 检查规格是否一致 (幂等性核心)
	// 目的：如果用户修改了 CR 的镜像，我们必须同步更新 Deployment
	expectedSize := myApp.Spec.Size
	if *foundDeployment.Spec.Replicas != expectedSize {
		logger.Info("副本数不一致，正在更新", "当前", *foundDeployment.Spec.Replicas, "期望", expectedSize)
		foundDeployment.Spec.Replicas = &expectedSize
		
		if err := r.Update(ctx, foundDeployment); err != nil {
			return reconcile.Result{}, err
		}
		// 更新后立即返回，等待下一次触发
		return reconcile.Result{}, nil
	}

	// 4. 更新 Status（实际状态反馈）
	// 目的：让用户通过 kubectl get myapp 就能看到有多少 Pod 真正运行了
	if myApp.Status.AvailableReplicas != foundDeployment.Status.AvailableReplicas {
		myApp.Status.AvailableReplicas = foundDeployment.Status.AvailableReplicas
		if err := r.Status().Update(ctx, &myApp); err != nil {
			logger.Error(err, "更新 Status 失败")
			return reconcile.Result{}, err
		}
	}

	// 5. 周期性检查 (可选)
	// 目的：即使没有事件触发，我也想每 1 分钟检查一次（预防某些外部因素导致的偏移）
	return reconcile.Result{RequeueAfter: time.Minute}, nil
}

深度解析：返回值与参数的奥秘

reconcile.Request 为什么只传名字不传对象？

原因： 当 Reconcile 被调用时，对象在缓存中可能已经变了。传名字要求你每次都从 r.Get 获取最新的快照。这保证了你的决策是基于当前真实数据的，而不是几秒前的过时数据。

reconcile.Result 的三种返回姿势：

1. Result{}, nil：

   • 含义：我做完了，且很成功。

   • 目的：停止调解。直到这个资源再次被修改（如用户改了 YAML），我才会被再次叫醒。

2. Result{Requeue: true}, nil：

   • 含义：我刚刚做了一个动作（比如创建了 Pod），我想立刻再检查一遍。

   • 目的：快速进入下一轮循环。

3. Result{RequeueAfter: time.Minute}, nil：

   • 含义：现在没事了，但 1 分钟后请务必再叫醒我。

   • 目的：用于处理那些不是由 K8s 资源触发的变化（比如你的 Operator 正在监控一个外部 API 接口的状态）。

第三阶段核心避坑指南（重要信息）

1. 禁止在循环中做长时阻塞动作： Reconcile 是并发执行的，但如果你在里面 time.Sleep(10 * time.Minute)，会占死 Worker 线程，导致你的 Operator 响应变得极慢。

2. 永远假设资源可能不存在： 在操作任何资源前，先判断 if err != nil && errors.IsNotFound(err)。

3. 避免“写冲突”导致的死循环： 如果你在 Reconcile 里不停地修改 Spec，而 K8s 发现 Spec 变了又去调用 Reconcile，你就创造了一个永不停歇的“死循环”，这会消耗大量 CPU。规则：只有用户能改 Spec，Operator 尽量只改 Status。

第四阶段：掌控生死——血缘绑定（OwnerReference）与善后处理（Finalizer）

在前面的阶段，你学会了如何让 Operator “思考”和“行动”。但这里有一个致命问题：如果你把自定义资源（CR）删了，它创建出来的那些 Pod 和 Deployment 还在集群里“流浪”怎么办？

核心包介绍

• sigs.k8s.io/controller-runtime/pkg/controller/controllerutil

  • 作用：这是处理资源关系的“工具箱”。

  • 核心功能：

    • SetControllerReference：建立父子关系，实现自动垃圾回收。

    • AddFinalizer / RemoveFinalizer：管理“终结器”，处理自定义删除逻辑。

• k8s.io/apimachinery/pkg/runtime

  • 作用：定义了 K8s 的对象转换协议。

  • 重要性：在建立父子关系时，代码需要知道当前集群的 Scheme（架构方案），以便确认父资源和子资源的版本是否匹配。

最佳实践：父子绑定（自动垃圾回收）

目的：当用户删除 MyWebApp 时，Kubernetes 的 Garbage Collector (GC) 会自动识别并删除所有关联的 Deployment。

// 这是一个内部辅助函数，用于构建子资源
func (r *MyReconciler) deploymentForMyApp(myApp *webv1.MyWebApp) (*appsv1.Deployment, error) {
	dep := &appsv1.Deployment{
		ObjectMeta: metav1.ObjectMeta{
			Name:      myApp.Name,
			Namespace: myApp.Namespace,
		},
		Spec: appsv1.DeploymentSpec{ /* ... 省略具体配置 ... */ },
	}

	// 【核心动作】：建立血缘关系
	// 参数说明：
	// 1. myApp: 父资源（Owner）
	// 2. dep: 子资源（Controlled）
	// 3. r.Scheme: 告诉 K8s 如何识别这两个对象的类型
	// 目的：在 dep 的 metadata 中注入 OwnerReference 字段
	if err := controllerutil.SetControllerReference(myApp, dep, r.Scheme); err != nil {
		return nil, err
	}

	return dep, nil
}

最佳实践：终结器（Finalizer）处理逻辑

场景：如果你的 Operator 在外部（如阿里云、腾讯云）创建了一个负载均衡器。仅仅删除 K8s 里的 CR 是不够的，你必须在它消失前，先调用云 API 把负载均衡器删了。

原理：只要对象中存在 finalizers 列表，K8s 就不允许彻底删除它，只会给它打上 DeletionTimestamp 标记。

func (r *MyReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	myApp := &webv1.MyWebApp{}
	if err := r.Get(ctx, req.NamespacedName, myApp); err != nil {
		return ctrl.Result{}, client.IgnoreNotFound(err)
	}

	// 定义一个唯一的 Finalizer 名字（通常格式为：域名/名字）
	myFinalizerName := "web.example.com/finalizer"

	// 检查资源是否正在被删除
	if myApp.ObjectMeta.DeletionTimestamp.IsZero() {
		// 情况 A：资源还没有被标记删除
		// 如果它还没有我们的 Finalizer，就把它加上
		if !controllerutil.ContainsFinalizer(myApp, myFinalizerName) {
			controllerutil.AddFinalizer(myApp, myFinalizerName)
			if err := r.Update(ctx, myApp); err != nil {
				return ctrl.Result{}, err
			}
		}
	} else {
		// 情况 B：资源正在被删除（用户点了删除按钮）
		if controllerutil.ContainsFinalizer(myApp, myFinalizerName) {
			// 【执行自定义清理逻辑】：比如调用外部 API 销毁资源
			if err := r.deleteExternalResources(myApp); err != nil {
				// 如果清理失败，直接返回错误，K8s 会重试，资源不会被真正删除
				return ctrl.Result{}, err
			}

			// 清理成功后，移除 Finalizer
			// 一旦 Finalizer 列表为空，K8s 就会真正把资源从 etcd 里抹掉
			controllerutil.RemoveFinalizer(myApp, myFinalizerName)
			if err := r.Update(ctx, myApp); err != nil {
				return ctrl.Result{}, err
			}
		}
		// 正在删除过程中，逻辑处理完后直接返回
		return ctrl.Result{}, nil
	}

	// 正常的 Reconcile 逻辑继续...
	return ctrl.Result{}, nil
}

深度解析：为什么要这样做？

Q: 为什么有了 SetControllerReference 还需要 Finalizer？

• SetControllerReference 只能管 K8s 内部 的资源（如：删了 CR 自动删 Pod）。

• Finalizer 专门管 K8s 外部 的资产（如：数据库账号、云端 LB、磁盘卷）。

Q: 为什么 SetControllerReference 需要传递 r.Scheme？

Scheme 是 K8s 的“户口登记表”。如果你想让 MyWebApp 做 Deployment 的父亲，代码需要通过 Scheme 查到 MyWebApp 属于哪个 GroupVersion（比如 web.example.com/v1），这样生成的 OwnerReference 才是合法的。

Q: 如果 deleteExternalResources 一直失败会怎样？

你的 CR 会一直卡在 Terminating 状态，删不掉。这虽然痛苦，但它是安全的——它防止了“对象没了，但云端资源还在计费”的情况发生。

第四阶段核心避坑指南（重要信息）

1. Finalizer 必须幂等： 由于 Reconcile 会多次触发，你的清理逻辑（如 deleteExternalResources）可能会被调用多次。一定要确保即使资源已经删过了，代码也不会报错挂掉。

2. 更新冲突： 在 AddFinalizer 或 RemoveFinalizer 时，如果 r.Update 报了 Conflict，说明资源刚好被别人改了。最佳实践： 捕获冲突并重试，或者直接返回错误让整个 Reconcile 重来。

3. 循环依赖陷阱： 千万不要在 Finalizer 逻辑里又去创建一个依赖于父资源的子资源，这会导致你的对象永远无法被删除。

速查表

阶段	核心包	主要用途	关键函数/结构
1. 定义	metav1 (apimachinery)	定义元数据（名字、标签、血缘）	ObjectMeta, TypeMeta
2. 操控	client (controller-runtime)	与 API Server 通信（增删改查）	Get, List, Update, Status()
3. 逻辑	reconcile / log	处理触发事件、控制重试、打日志	Request, Result, FromContext
4. 生命周期	controllerutil	建立父子关系、处理删除前后的清理	SetControllerReference, Finalizer

核心包深度解析

1. k8s.io/apimachinery/pkg/apis/meta/v1 (别名 metav1)

• 它是干什么的：所有 K8s 资源的“公共身份证”。

• 重点字段：

  • Name, Namespace: 资源的唯一坐标。

  • OwnerReferences: 极其重要。这是一个数组，记录了“谁是我的父亲”。设置了它，父亲被删，儿子自动被 GC（垃圾回收）。

• 为什么要这么用：为了让 K8s 引擎知道资源之间的逻辑隶属关系，防止资源泄漏。

2. sigs.k8s.io/controller-runtime/pkg/client

• 它是干什么的：Operator 的“手”，负责所有 API 操作。

• 关键函数详解：

  • Get(ctx, key, obj):

    • 传参：Context（超时控制）、NamespacedName（找谁）、对象指针（结果存哪）。

    • 返回：error。如果是 NotFound，说明资源不存在。

  • Status().Update(ctx, obj):

    • 为什么要这么用：这是最佳实践。Status 是子资源，独立更新它不会导致 metadata.generation 增加，从而避免因为触发了不必要的 Spec 变更而导致死循环。

3. sigs.k8s.io/controller-runtime/pkg/reconcile

• 它是干什么的：定义了大脑的“单次思考任务”。

• 关键返回值的含义：

  • Result{}, nil: “我任务完成了，不用再叫我。”

  • Result{Requeue: true}, nil: “我刚做了个动作，请立刻让我再检查一遍。”（常用在创建完资源后）

  • Result{RequeueAfter: 1*time.Minute}, nil: “现在正常，但 1 分钟后请准时叫醒我巡检。”

4. sigs.k8s.io/controller-runtime/pkg/controller/controllerutil

• 它是干什么的：处理复杂的对象关系和删除逻辑。

• 关键函数：

  • SetControllerReference(owner, controlled, scheme):

    • 传参：父对象、子对象、Scheme 户口本。

    • 返回：error。

    • 什么时候用：在 r.Create() 子资源之前调用，确保子资源出生就有“父亲”。

  • Add/RemoveFinalizer(obj, string):

    • 为什么要用：当资源被删时，你想在它彻底消失前执行一些动作（如清理云端数据库），必须用这个防止它被瞬间抹除。

💡 开发最佳实践 (Best Practices)

1. 幂等性 (Idempotency) 第一原则： 永远假设你的代码会在任何一行报错退出。当它第二次进来时，必须能接上进度。做法： 每次操作前先 Get 查一下，存在就不创建，一致就不更新。

2. 读写分离： client.Client 默认从缓存读，往集群写。不要手动去写缓存，始终相信 r.Get 拿到的就是当前的最优状态。

3. 细颗粒度的 RBAC 权限： 只给 Operator 申请它需要的权限。如果你只需要改 Pod，不要申请集群级别的权限。

4. 状态驱动 (State Driven)： 不要让你的 Operator 试图去记住历史，它应该像一个“金鱼”，每次进来都通过观察现在的集群状态来决定下一步。

🛠️ 推荐的开发路径 (Roadmap)

1. 脚手架生成： 使用 kubebuilder init 和 create api 生成代码框架。

2. 定义 Spec (数据模型)： 在 _types.go 里想清楚用户需要填什么参数。原则： 字段越少越好，能推导出来的字段不要让用户填。

3. 编写 Reconcile (核心逻辑)： 按照“获取 CR -> 获取子资源 -> 对比差异 -> 执行同步 -> 更新 Status”的五步法写逻辑。

4. 本地测试 (Local Debug)： 利用 Minikube，直接在本地运行 make install 和 make run。这样你可以在 IDE 里打断点看变量。

5. 镜像部署： 测试完成后，执行 make docker-build docker-push 和 make deploy 将 Operator 真正运行在集群里。

实战

定义数据模型

定义数据模型（Schema）—— 设计你的“资源协议”。

在 Kubernetes 中，所有的资源本质上都是一段 JSON。在这一阶段，我们要去修改 api/v1/myconfig_types.go 文件，决定用户在 YAML 里能填什么参数（Spec），以及我们的 Operator 反馈什么信息（Status）。

1. 明确我们要实现的字段

我们要做的 MyConfig 资源，目标是生成一个 ConfigMap。

• 期望（Spec）：用户需要提供 ConfigMap 的数据内容，我们定义一个 Data 字段。

• 状态（Status）：我们要告诉用户这个 ConfigMap 是否已经同步成功，我们定义一个 SyncStatus 字段。

2. 修改 api/v1/myconfig_types.go

找到 MyConfigSpec 和 MyConfigStatus 结构体，按如下方式修改：

// MyConfigSpec 定义了用户希望看到的资源状态
type MyConfigSpec struct {
	// Data 是我们要存入 ConfigMap 的键值对数据
	// +kubebuilder:validation:Required (这是一个注解，表示该字段必填)
	Data map[string]string `json:"data"`
}

// MyConfigStatus 定义了资源的实际运行状态
type MyConfigStatus struct {
	// SyncStatus 表示同步结果：Success 或 Failed
	SyncStatus string `json:"syncStatus,omitempty"`

	// LastSyncTime 记录最后一次成功同步的时间
	LastSyncTime *metav1.Time `json:"lastSyncTime,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status  <-- 【关键！】必须有这一行才能更新 Status 子资源
// +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.syncStatus" <-- 【进阶】让 kubectl get 也能直接看到状态

// MyConfig 是 MyConfig 资源的结构体定义
type MyConfig struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   MyConfigSpec   `json:"spec,omitempty"`
	Status MyConfigStatus `json:"status,omitempty"`
}

🔍 深度拆解：为什么要这么做？

① +kubebuilder:subresource:status

• 为什么要这么做？

  Kubernetes 将资源分为“主资源”和“子资源”。如果你不加这行注释，你的 Operator 在尝试调用 r.Status().Update() 时会报错，因为 API Server 会认为这个资源没有 status 这个接口。

• 不这么做的后果：

  你的 Operator 逻辑能跑，但是无法把运行结果（比如“同步成功”）反馈给用户。用户执行 kubectl get myconfig -o yaml 时，status 永远是空的。

② JSON 标签 (`json:"data"`)

• 为什么要这么做？

  Go 语言的变量首字母必须大写（Public）才能被其他包访问，但 Kubernetes 的 YAML 规范习惯使用小写（如 spec.data）。这个标签就是翻译官。

• 不这么做的后果：

  如果你漏掉了标签或者写错了，用户在 YAML 里填了 data，Go 代码里的 Data 变量拿不到任何值。

③ +kubebuilder:printcolumn (最佳实践)

• 为什么要这么做？

  你一定用过 kubectl get pods，它会显示 STATUS、AGE 等列。这行代码就是让你自定义 kubectl get myconfig 时的显示列。

• 不这么做的后果：

  不加这行，你执行 kubectl get myconfig 时只能看到名字，必须加 -o yaml 才能看到同步结果，非常不直观。

3. 生成 Manifests (同步代码到 YAML)

每当你修改了 _types.go 文件，你必须运行以下命令，否则 Kubernetes 不认识这些新字段：

Bash

make manifests

• 这个函数干了什么？

  它会扫描你的 Go 代码和注释（那些 +kubebuilder 开头的行），然后在 config/crd/bases/ 目录下生成一个庞大的 YAML 文件。

• 不这么做的后果：

  即使你代码写得完美，只要没执行这一步，当你把 YAML 发给集群时，集群会报错：unknown field "data" in spec。

将 CRD 安装到 Minikube

现在，我们要把这个“设计图”交给 Minikube。

make install

• 验证结果：

  执行 kubectl get crds | grep myconfigs

  如果你看到了 myconfigs.web.example.com，说明你已经在集群里成功登记了你的新资源类型！

编写 Reconcile 逻辑

我们将分三步完成控制器的编写：设置权限、建立逻辑循环、实现父子绑定。

设置 RBAC 权限（必须先做）

在 Reconcile 函数上方，你会看到一堆以 // +kubebuilder:rbac 开头的注释。这些不是普通注释，它们是权限声明。

操作： 找到这些行，确保添加了对 configmaps 的权限：

// +kubebuilder:rbac:groups=web.example.com,resources=myconfigs,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=web.example.com,resources=myconfigs/status,verbs=get;update;patch
// +kubebuilder:rbac:groups="",resources=configmaps,verbs=get;list;watch;create;update;patch;delete

• 为什么要这么做？

  Kubernetes 默认是不允许任何程序随意创建资源的。这些注释会被 make manifests 转化成集群的 ClusterRole。

• 不这么做的后果：

  你的代码运行到 r.Create(configMap) 时会直接崩溃，报错 Forbidden（无权操作）。

实现核心调解逻辑 (Reconcile)

我们将重写 Reconcile 函数。请仔细阅读代码中的中文注释：

func (r *MyConfigReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	// 1. 初始化日志对象，方便调试
	l := log.FromContext(ctx)

	// 2. 获取用户创建的 MyConfig 实例
	// 我们先定义一个空的结构体，然后让 Client 去填充它
	myConfig := &webv1.MyConfig{}
	err := r.Get(ctx, req.NamespacedName, myConfig)
	if err != nil {
		// 如果没找到，说明资源可能被删除了
		return ctrl.Result{}, client.IgnoreNotFound(err)
	}

	// 3. 定义我们“期望”的 ConfigMap 长什么样
	// 我们把这个逻辑抽离成一个单独的函数（见下文）
	cm, err := r.desiredConfigMap(myConfig)
	if err != nil {
		return ctrl.Result{}, err
	}

	// 4. 检查集群中是否已经存在这个 ConfigMap
	foundCM := &corev1.ConfigMap{}
	err = r.Get(ctx, types.NamespacedName{Name: cm.Name, Namespace: cm.Namespace}, foundCM)

	if err != nil && errors.IsNotFound(err) {
		// --- 场景 A：ConfigMap 不存在，直接创建 ---
		l.Info("正在创建 ConfigMap", "Name", cm.Name)
		if err := r.Create(ctx, cm); err != nil {
			return ctrl.Result{}, err
		}
		// 创建成功后，更新状态
		return r.updateStatus(ctx, myConfig, "Success")
		
	} else if err != nil {
		// 发生了其他读取错误
		return ctrl.Result{}, err
	}

	// --- 场景 B：ConfigMap 已存在，对比数据是否一致 ---
	// 目的：实现“幂等性”，如果用户改了 MyConfig 的 Data，我们要同步更新 ConfigMap
	if !reflect.DeepEqual(foundCM.Data, myConfig.Spec.Data) {
		l.Info("数据不一致，正在更新 ConfigMap", "Name", cm.Name)
		foundCM.Data = myConfig.Spec.Data
		if err := r.Update(ctx, foundCM); err != nil {
			return ctrl.Result{}, err
		}
	}

	return ctrl.Result{}, nil
}

实现“父子绑定”（关键函数）

这是实现自动清理和关联的核心。我们在控制器类下增加这个辅助函数：

func (r *MyConfigReconciler) desiredConfigMap(myConfig *webv1.MyConfig) (*corev1.ConfigMap, error) {
	cm := &corev1.ConfigMap{
		ObjectMeta: metav1.ObjectMeta{
			Name:      myConfig.Name, // 名字和父资源保持一致
			Namespace: myConfig.Namespace,
		},
		Data: myConfig.Spec.Data, // 使用我们在 Spec 中定义的 Data
	}

	// 【核心：父子绑定】
	// 参数 1: 父资源 (MyConfig)
	// 参数 2: 子资源 (ConfigMap)
	// 参数 3: 户口本 (r.Scheme)
	// 目的：在 ConfigMap 的 Metadata 中注入 OwnerReference
	if err := controllerutil.SetControllerReference(myConfig, cm, r.Scheme); err != nil {
		return nil, err
	}

	return cm, nil
}

• 为什么要这么做？

  这是 Operator 的最佳实践。设置了 OwnerReference 后，当你 kubectl delete myconfig ... 时，K8s 会自动帮你删掉这个对应的 ConfigMap。

• 不这么做的后果：

  资源会发生“泄露”。你的自定义资源删了，但它留下的垃圾（ConfigMap）会永远留在集群里，占用命名空间。

更新状态 (Status Update)

func (r *MyConfigReconciler) updateStatus(ctx context.Context, myConfig *webv1.MyConfig, status string) (ctrl.Result, error) {
	myConfig.Status.SyncStatus = status
	now := metav1.Now()
	myConfig.Status.LastSyncTime = &now

	// 注意：使用 r.Status().Update 而不是 r.Update
	if err := r.Status().Update(ctx, myConfig); err != nil {
		return ctrl.Result{}, err
	}
	return ctrl.Result{}, nil
}

• 为什么要这么做？

  让用户能看到结果。

• 不这么做的后果：

  用户不知道 Operator 是否在干活，只能去翻日志，效率极低。

监听

func (r *MyConfigReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&webv1.MyConfig{}).
        Owns(&corev1.ConfigMap{}). // <--- 必须有这一行！
        Complete(r)
}

当你写下 For 和 Owns 时，底层的 controller-runtime 其实在为你做以下几件事：

① 注册事件处理器 (Event Handlers)

• For(&webv1.MyConfig{}): 向 K8s 注册一个监听器（Informer）。一旦 MyConfig 资源有 Create/Update/Delete 动作，K8s 就会把这个事件扔进一个工作队列 (WorkQueue)。

• Owns(&corev1.ConfigMap{}): 同样注册一个针对 ConfigMap 的监听器。

② 自动过滤与映射 (Map to Owner)

这是 Owns 最神奇的地方。 当一个 ConfigMap 发生变动时，controller-runtime 不会盲目地触发 Reconcile。它会执行以下逻辑：

1. 检查 Metadata：查看这个 ConfigMap 的 ownerReferences 列表。

2. 匹配类型：看看里面有没有一个 Owner 的 Kind 是 MyConfig，且 Controller 字段为 true。

3. 获取名字：如果有，提取出那个 MyConfig 的 Name。

4. 触发父资源：把这个父资源的名字扔进工作队列，触发 Reconcile 函数。

重点： 你的 Reconcile 函数接收到的 req.Name 永远是 父资源 (MyConfig) 的名字，即使刚才变动的是 子资源 (ConfigMap)。这保证了你的逻辑始终从“源头”开始检查。

需要修改此函数的 3 大常见场景

除了基础的 For 和 Owns，实际开发中为了提高性能和处理复杂逻辑，经常需要修改它。

场景一：防止“状态更新”导致的死循环 (使用 Predicates)

问题：当你在 Reconcile 中更新 Status 时，K8s 会认为资源变了，再次触发 Reconcile。如果不加控制，会陷入：更新状态 -> 触发 -> 更新状态的死循环。 解决方案：使用 Predicate 过滤掉非 Spec 的更新。

import (
    "sigs.k8s.io/controller-runtime/pkg/predicate"
    "sigs.k8s.io/controller-runtime/pkg/event"
)

func (r *MyConfigReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&webv1.MyConfig{}).
        Owns(&corev1.ConfigMap{}).
        // 【新增：过滤器】
        WithEventFilter(predicate.Funcs{
            UpdateFunc: func(e event.UpdateEvent) bool {
                // 只有当 Spec (Generation) 发生变化时才触发调解
                // 如果只是 Status 变化，Generation 是不会变的
                return e.ObjectOld.GetGeneration() != e.ObjectNew.GetGeneration()
            },
        }).
        Complete(r)
}

场景二：监听“非所属”的外部资源 (使用 Watches)

问题：假设你的 MyConfig 逻辑依赖于一个全局的 Secret（比如数据库证书），但这个 Secret 并不是由 MyConfig 创建的（没有 Owner 绑定）。当 Secret 变化时，你也需要重新同步。 解决方案：手动建立映射关系。

import (
    "sigs.k8s.io/controller-runtime/pkg/handler"
    "sigs.k8s.io/controller-runtime/pkg/source"
)

func (r *MyConfigReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&webv1.MyConfig{}).
        Owns(&corev1.ConfigMap{}).
        // 【新增：监听第三方资源】
        Watches(
            &source.Kind{Type: &corev1.Secret{}},
            handler.EnqueueRequestsFromMapFunc(func(obj client.Object) []reconcile.Request {
                // 这里写逻辑：当任何 Secret 变化时，找出受影响的 MyConfig 名字
                // 这里为了演示，假设触发所有命名空间下的 myconfig-test
                return []reconcile.Request{
                    {NamespacedName: types.NamespacedName{Name: "myconfig-test", Namespace: obj.GetNamespace()}},
                }
            }),
        ).
        Complete(r)
}

场景三：控制并发处理速度

问题：默认情况下，Operator 是一次处理一个 Reconcile。如果你的集群规模很大，处理速度太慢。 解决方案：增加并发 worker 数。

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

func (r *MyConfigReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&webv1.MyConfig{}).
        Owns(&corev1.ConfigMap{}).
        // 【新增：并发配置】
        WithOptions(controller.Options{
            MaxConcurrentReconciles: 10, // 同时跑 10 个调解协程
        }).
        Complete(r)
}

总结

• For: 定义你的主要观察对象。

• Owns: 定义你的直接下属（自动反向映射）。

• Watches: 定义跟你没亲戚关系但你很关心的“邻居”。

• WithEventFilter: 闭上眼不看那些没意义的琐碎变动。