Controller 集成手册

面向需要在 Global 集群上跑 Controller / Operator 并接入 DR 体系的开发者。

背景

ACP 的 Global + 业务集群（行业里常说的 Hub-Spoke）形态下，Global 集群同时承担两个角色：

• 当 Global 是 Active 时，正常 reconcile，写入它自己的 etcd
• 当 Global 是 Standby 时，etcd-sync 把 Active 的状态同步过来，覆盖本地 etcd 中相应 key 段

如果 Standby Global 上的 Controller 也照常 reconcile，可能出现两类问题：

下面这张时序图对比了有 / 没有 drsyncgate 时 Standby 上发生的事：

正确做法：

• Standby 期间短路 reconcile，让出对象给 etcd-sync
• Active 期间正常工作
• 切换期间留 grace period，避免单次 informer 抖动触发 false positive

角色信号

判定信号是 kube-public/etcd-sync ConfigMap：

ConfigMap 的内容不重要；只看存在性。它由 etcd-sync 自身在它生效的一侧维护。

drsyncgate 库

astrolabe/pkg/drsyncgate 把判定细节封装成一个函数：

import "github.com/alauda/astrolabe/pkg/drsyncgate"
 
syncing, err := drsyncgate.IsRunning(ctx, reader)

完整源码

drsyncgate 是 astrolabe 仓内的私有包，外部仓不会拉到这份代码。完整列出便于 review、移植、或在没接入 astrolabe 的项目里直接照抄一份。

内部 grace period 状态机：

调用方只需要决定：当 syncing 为 true 时，是否要给本对象短路 reconcile。

标准接入姿势

入口在 Reconcile() 顶部。astrolabe 仓的两个示例：

// pkg/cvo/controllers/controller.go:160
syncing, err := drsyncgate.IsRunning(ctx, r.DirectClient)
if err != nil {
    return ctrl.Result{}, err
}
if syncing && !isGlobalCluster(obj.Name) {
    logger.Info(
        "Skipping reconcile while etcd-sync is running",
        "cluster", obj.Name,
        "configMap", metav1.NamespacePublic+"/"+drsyncgate.ConfigMapName,
        "requeueAfter", etcdSyncRequeueAfter,
    )
    return ctrl.Result{RequeueAfter: etcdSyncRequeueAfter}, nil
}

// pkg/cvo/controllers/syncer.go:69
syncing, err := drsyncgate.IsRunning(ctx, c.DirectClient)
if err != nil {
    return ctrl.Result{}, err
}
if syncing && !isGlobalCluster(cluster.Name) {
    return ctrl.Result{RequeueAfter: etcdSyncRequeueAfter}, nil
}

要点：

• etcdSyncRequeueAfter = 30 * time.Second，与 grace period 量级匹配
• isGlobalCluster(name) 是仓内的小帮手 name == globalClusterName——参见下文豁免说明
• 读取使用 DirectClient（绕过 cache），避免 informer 还没观测到 marker 变化时漏判

把上面的代码翻译成判断流程：

"Global 豁免"为什么需要

仓内对 cluster name 等于 global 的对象不短路。原因：

如果你写的 Controller 不区分 Global 集群自身 vs 它管理的业务集群，那就直接 if syncing { requeue } 不带豁免；如果区分，请套用同样的 carve-out。

日志与可观测

判定结果本身没有 metric / event。建议 Controller 在短路分支记一行 Info 日志，至少包含：

• 对象名
• marker 的 namespace/name（kube-public/etcd-sync，可用 drsyncgate.ConfigMapName 拼出）
• 选择的 requeue 间隔

避免只打"skipping reconcile"——排障时无法区分是 gate 触发还是别的逻辑。

测试姿势

astrolabe/pkg/drsyncgate/gate_test.go 用 fake client + 注入 ConfigMap 的方式覆盖了三类场景：

测试用的内部钩子：

• resetStateForTest(t, clockFn)：重置库内状态并替换时钟
• resetClockForTest(t)：单独替换时钟

钩子是非导出的，只能在同包测试或本仓内的 wrapper test 中使用；从外部包测试自己 Controller 时，直接用 fake client 注入 / 删除 ConfigMap 就够了。

反模式