etcd-sync 动态 ConfigMap 迁移手册

面向产品方。本手册回答四个问题：

哪些规则适合迁出
怎么拆分到产品自己的 ConfigMap
迁完之后怎么验证排序和功能结果
出问题时怎么回滚

背景

etcd-sync 已经支持运行时动态加载 ConfigMap：

默认规则继续由 chart 渲染并维护
产品级规则可以放到产品自己的 ConfigMap 里，加上启用标签后自动被发现并生效

迁移前后对比：

维度	迁移前	迁移后
规则归属	集中写在 etcd-sync 的默认 ConfigMap	由产品维护各自的 ConfigMap
变更方式	改 chart 并发版	直接增删改 ConfigMap
生效方式	发版后生效	监听到事件后即时生效
回滚方式	回退 chart	删除 ConfigMap 或移除启用标签
排障入口	看 etcd-sync 内置规则	看源 ConfigMap 的状态 annotation

整体治理流程：

哪些规则适合迁出

满足以下任一特征的规则适合迁出，由产品自己维护：

由某个产品长期持有
变更频率高于 etcd-sync 的发版频率
与某个项目、环境、租户强绑定
需要独立回滚或独立验证

下列规则建议继续留在默认规则来源里：

平台级公共基线
跨所有 DR 集群强绑定的默认前缀
必须随 etcd-sync 一起交付的保底规则

具体到每条规则的归属和迁移建议，见 ownership-migration-inventory.md。

迁移步骤

1. 盘点本产品的规则

从 etcd-sync-ignore-text 中筛出属于本产品的条目，按 data key 分类。建议直接登记成下面这种四列表：

原条目	规则类型	归属产品	目标 ConfigMap
`/registry/devops.alauda.io`	`sync-prefix-file.txt`	DevOps	`devops-etcd-sync-rules`
`/registry/devops.alauda.io/tmp/`	`ignore-prefix-file.txt`	DevOps	`devops-etcd-sync-rules`

获取当前规则：

kubectl -n cpaas-system get configmap etcd-sync-ignore-text -o yaml

如果还在仓库内整理规则，也可以直接从 chart/templates/sync-key-cm.yaml 盘点。

2. 创建产品 ConfigMap

带上启用标签，data key 与原集中规则保持一致：

apiVersion: v1
kind: ConfigMap
metadata:
  name: devops-etcd-sync-rules
  namespace: devops-system
  labels:
    etcd-sync.cpaas.io/enabled: "true"
  annotations:
    etcd-sync.cpaas.io/weight: "20"
data:
  sync-prefix-file.txt: |
    /registry/devops.alauda.io
  ignore-prefix-file.txt: |
    /registry/devops.alauda.io/tmp/

3. 决定优先级

weight 是非负整数，数值越大优先级越高。建议：

场景	推荐取值
普通产品规则	`0`
需要覆盖默认基线	`10` 或 `20`
需要压过其他产品规则	与相关方明确约定一个更高值

同一个产品先收敛到一个 ConfigMap，需要时再考虑分层不同的 weight。

4. 应用并查看状态

kubectl apply -f devops-etcd-sync-rules.yaml
kubectl -n devops-system get configmap devops-etcd-sync-rules -o yaml

重点看以下 annotation：

etcd-sync.cpaas.io/status
etcd-sync.cpaas.io/message
etcd-sync.cpaas.io/observed-weight
etcd-sync.cpaas.io/observed-hash
etcd-sync.cpaas.io/processed-at

状态	含义	下一步
`accepted`	当前内容已进入快照	做功能验证
`rejected`	当前内容未进入快照	修正 data key、`weight` 或规则内容

5. 验证排序和功能

先验证排序，再验证功能。

排序验证：确认两件事——

本 ConfigMap 的 weight 是否符合预期
与可能产生覆盖关系的其他来源的 namespace/name 谁先谁后

排序规则：

weight 高 -> 先评估
weight 相同 -> 按 namespace/name 升序先评估
首个明确结论 -> 直接生效

功能验证分三类用例：

本来要同步的 key，迁移后仍同步
本来要忽略的 key，迁移后仍忽略
用于覆盖默认基线的规则，迁移后确实压过

排障时可以辅助看日志：

kubectl -n cpaas-system logs deploy/etcd-sync
kubectl -n cpaas-system logs deploy/etcd-sync-monitor

6. 清理集中规则

确认目标 key 命中预期规则之后再清理集中规则，按下面顺序操作：

等产品 ConfigMap 稳定在 accepted
从 etcd-sync-ignore-text 中移除已迁出的条目
再做一次回归验证

整体流程

模板

模板 A：普通 prefix 同步

apiVersion: v1
kind: ConfigMap
metadata:
  name: project-a-rules
  namespace: project-a-system
  labels:
    etcd-sync.cpaas.io/enabled: "true"
data:
  sync-prefix-file.txt: |
    /registry/project.a.io

模板 B：覆盖默认基线

apiVersion: v1
kind: ConfigMap
metadata:
  name: project-a-override
  namespace: project-a-system
  labels:
    etcd-sync.cpaas.io/enabled: "true"
  annotations:
    etcd-sync.cpaas.io/weight: "20"
data:
  ignore-prefix-file.txt: |
    /registry/project.a.io/tmp/
  sync-prefix-file.txt: |
    /registry/project.a.io/critical/

模板 C：带删除语义

apiVersion: v1
kind: ConfigMap
metadata:
  name: project-a-delete-rules
  namespace: project-a-system
  labels:
    etcd-sync.cpaas.io/enabled: "true"
data:
  sync-delete-prefix-file.txt: |
    /registry/project.a.io/releases/
  sync-delete-ignore.txt: |
    /registry/project.a.io/releases/pinned/

回滚

按从快到慢的顺序选择：

删除产品 ConfigMap
移除启用标签 etcd-sync.cpaas.io/enabled
恢复上一版 ConfigMap 内容

失败时的运行时行为

场景	结果
当前版本内容合法	当前版本进入快照
当前版本内容非法	当前版本被拒绝，上一版成功内容继续生效
ConfigMap 被删除	该规则层从快照中移除
启用标签被移除	该规则层从快照中移除

常见问题

现象	原因	处理
状态长期 `rejected`	data key 非法、`weight` 非法、regexp 非法	修正 data key、注解或表达式
状态 `accepted`，行为不对	排序不符合预期	检查 `weight` 与 `namespace/name`
删除 ConfigMap 后仍看到旧行为	informer 还在收敛	等收敛后再复查
新建 ConfigMap 没有任何状态 annotation	平台侧权限或 watcher 异常	看 etcd-sync 日志和平台 RBAC

经验沉淀

一个产品先收敛到一个 ConfigMap 再说
基线规则用低 weight，覆盖规则用高 weight
规则变更后先看状态，再看功能结果
删除事件相关的规则单独审视：sync-delete-prefix-file.txt、sync-delete-ignore.txt

交接清单

产品来源 ConfigMap 的名称与命名空间已固定
归属人明确并记录
weight 约定写入产品文档
回滚方式沉淀到产品 Runbook

etcd-sync 动态 ConfigMap 迁移手册

On this page