1. Controller Runtime 概述

Controller Runtime 是 Kubernetes 社区官方维护的 Go 库，用于构建控制器和 Operator。它封装了 client-go 的底层细节，提供了一套声明式的、可组合的 API，让开发者专注于业务逻辑（Reconcile），而非重复编写事件监听、队列管理、领导者选举等基础设施代码。

1.1 什么是 Controller Runtime

Controller Runtime 本质上是一个 控制器框架，它定义了控制面控制器的标准构建范式。其核心设计哲学是：

• 关注点分离：将事件源、调度、业务逻辑解耦为独立组件。
• 约定优于配置：提供默认的 Manager、Controller、Reconciler 实现，开箱即用。
• 可测试性：通过 fake client 和 envtest 支持单元测试与集成测试。

1.2 核心组件：Manager、Controller、Reconciler

Controller Runtime 的架构围绕三个核心抽象构建，它们形成了从启动到业务处理的完整链路：

三者协作流程如下：

1. Manager 启动时初始化共享 Cache 和 Client，并启动所有已注册的 Controller。
2. Controller 通过 Watch() 注册事件源（如对 Deployment 的变更），事件进入内部 WorkQueue。
3. Reconciler 从队列中取出请求，执行 Reconcile() 方法，返回结果或错误。

1.3 与 client-go 的关系

client-go 是 Kubernetes 官方提供的 Go 客户端库，提供对 API Server 的底层访问能力。Controller Runtime 在 client-go 之上构建了更高层的抽象：

Controller Runtime 内部大量使用 client-go 的组件：

• Cache 基于 client-go 的 SharedInformerFactory 实现。
• Client 封装了 client-go 的 ClientSet 或 DynamicClient，提供类型安全的读写接口。
• WorkQueue 直接复用 client-go 的 workqueue.RateLimitingInterface。

1.4 整体架构图

下图展示了 Controller Runtime 的核心组件及其与 client-go 的协作关系：

1.5 组件协作时序图

以下时序图展示了一个典型 Reconcile 请求的完整生命周期：

1.6 最小控制器代码示例

以下代码展示了 Controller Runtime 三个核心组件的典型使用方式：

package main

import (
    "context"
    "fmt"
    "os"
    "time"

    corev1 "k8s.io/api/core/v1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/apimachinery/pkg/runtime"
    "k8s.io/apimachinery/pkg/types"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/client"
    "sigs.k8s.io/controller-runtime/pkg/log"
    "sigs.k8s.io/controller-runtime/pkg/log/zap"
    "sigs.k8s.io/controller-runtime/pkg/reconcile"
)

// PodReconciler 实现 Reconciler 接口
type PodReconciler struct {
    client.Client
    Scheme *runtime.Scheme
}

// Reconcile 是业务逻辑入口
func (r *PodReconciler) Reconcile(ctx context.Context, req reconcile.Request) (reconcile.Result, error) {
    log := log.FromContext(ctx)
    log.Info("Reconciling Pod", "namespace", req.Namespace, "name", req.Name)

    var pod corev1.Pod
    if err := r.Get(ctx, req.NamespacedName, &pod); err != nil {
        log.Error(err, "unable to fetch Pod")
        return reconcile.Result{}, client.IgnoreNotFound(err)
    }

    fmt.Printf("Pod %s/%s 当前 Phase: %s\n", pod.Namespace, pod.Name, pod.Status.Phase)
    return reconcile.Result{RequeueAfter: 30 * time.Second}, nil
}

func main() {
    // 1. 设置日志
    ctrl.SetLogger(zap.New(zap.UseDevMode(true)))

    // 2. 创建 Manager
    mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
        Scheme:             scheme,
        MetricsBindAddress: ":8080",
        LeaderElection:     true,
        LeaderElectionID:   "pod-controller.example.com",
    })
    if err != nil {
        fmt.Println("unable to start manager:", err)
        os.Exit(1)
    }

    // 3. 创建 Controller 并注册 Reconciler
    err = ctrl.NewControllerManagedBy(mgr).
        For(&corev1.Pod{}).           // 监听 Pod 事件
        Owns(&corev1.Event{}).        // 同时监听关联的 Event
        Complete(&PodReconciler{
            Client: mgr.GetClient(),
            Scheme: mgr.GetScheme(),
        })
    if err != nil {
        fmt.Println("unable to create controller:", err)
        os.Exit(1)
    }

    // 4. 启动 Manager（阻塞）
    if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
        fmt.Println("problem running manager:", err)
        os.Exit(1)
    }
}