DR 容灾Active / Standby Controller 协同
Active → Standby 资源同步规范
Sync 资源的契约与字段定义
Active → Standby 资源同步规范
面向规则提供方与 Controller 作者：在 Global 集群 + Active/Standby 容灾场景下，怎么决定我的 CRD / Secret / ConfigMap 应该被 etcd-sync 同步过去，还是应该被忽略。
原则
转成判断：
| 资源是否需要在 Standby 上"立即可见" | 是 | 否 |
|---|---|---|
| Standby 是否会基于该资源在本集群再写其他对象 | 同步主对象 + 忽略派生对象 | 同步主对象 |
| — | 忽略 |
决策表
| 资源类型 | 默认建议 | 备注 |
|---|---|---|
| 业务方 CRD 主对象（spec 由 Active 维护） | 同步 | Standby 切换为 Active 后能立刻接管 |
CRD 的 *State / *Status 子对象（由本地 Controller 维护） | 忽略 | 每集群本地状态，同步过去只会引发循环冲突 |
| 本集群派生的密钥 Secret | 忽略 | 例：etcd-encryption-key-<revision> |
| 根密钥材料 Secret（需要在两侧分别布置） | 忽略 | 例：etcd-derivation-root，由部署流程在两侧各自创建 |
| 集群级运行时配置 ConfigMap（控制本集群行为） | 忽略 | 例：kube-public/etcd-sync 自身 |
| 默认/全局元数据对象（spec 跨 DR 一致） | 视情况 | 如果两侧都由 chart 渲染、值天然一致，建议忽略；否则同步 |
| 节点 / 命名空间级缓存对象 | 忽略 | 这些对象在 Standby 上由本地控制器自然重建 |
跨集群拓扑对象（Cluster、MachinePool 等） | 同步 | 见 迁移清单 中 Cluster Lifecycle 一行 |
与 etcd-sync 字段的对应
落到 ConfigMap 上的实际字段（详见 etcd-sync-dynamic-configmap-migration/provider-spec.md 的"支持的数据键"）：
| 决策 | 推荐 data key | 何时使用 |
|---|---|---|
| 同步整个资源前缀 | sync-prefix-file.txt | 资源以前缀聚合，例如某个 API group 下整批 CRD |
| 同步特定单条 | sync-equal-file.txt | 仅一两个对象（例如某个具名 default 实例） |
| 同步并附带删除事件 | 配套 sync-delete-prefix-file.txt + sync-delete-ignore.txt | Active 删除一个对象时，Standby 也要级联删除；sync-delete-ignore.txt 用于保留 Global 集群自身托管的同前缀对象 |
| 忽略整个前缀 | ignore-prefix-file.txt | 状态对象、本地派生 Secret 这类整批忽略 |
| 忽略单条 | ignore-equal.txt | 单个具名对象，例如 marker ConfigMap |
| 按值过滤 | ignore-kvs-file.txt | 只想忽略某些 phase / 某些类型字段值的对象 |
推荐写法
每个产品维护一个带启用标签的 ConfigMap，把"同步"和"忽略"两类字段都收敛到同一个对象里。这样：
- 删除时一次操作就能下掉全部规则
weight可以集中调provider-spec.md中的状态 annotation 直接定位到本产品
骨架示例：
weight 默认 0；只有需要压过其他来源时才提高。
参考样板：etcd-encryption-manager
这是本仓内已有的一份完整决策样本：
| 路径 | 决策 |
|---|---|
/registry/etcdkeyseedbundles.cluster.alauda.io/ | 同步——Standby 据此派生密钥 |
/registry/etcdkeyseedbundlestates.cluster.alauda.io/ | 忽略——本地执行状态 |
/registry/etcdencryptionconfigs.cluster.alauda.io/default | 忽略——两侧分别由 chart 渲染 |
/registry/secrets/kube-system/etcd-derivation-root | 忽略——根密钥由部署在两侧各自分发 |
/registry/secrets/kube-system/etcd-encryption-key- | 忽略——本地派生出的 key |
/registry/configmaps/kube-public/etcd-sync | 忽略——本地 etcd-sync 自身的 marker |
把这份样板按"同步 / 忽略"二分组展开：
完整背景见 etcd-encryption-deterministic-key/key-derivation-spec.md。
校验
| 检查 | 方法 | 通过标准 |
|---|---|---|
| 同步前缀确实被覆盖 | 在 Active 创建一条对象，看 Standby 是否出现 | 出现且字段一致 |
| 忽略前缀确实没动 | 在 Active 修改一个本应忽略的 Secret，看 Standby 是否变化 | 不变化 |
| 状态 annotation 落到产品 ConfigMap 上 | kubectl get cm -o yaml 看 etcd-sync.cpaas.io/status | accepted |
| 优先级符合预期 | etcd-sync.cpaas.io/observed-weight 与设置值一致 | 完全一致 |
排障路径见 etcd-sync-dynamic-configmap-migration/migration-handbook.md 的"常见问题"章节。