Deterministic 模式部署手册

面向 Active + Standby Global 集群的运维或部署方。本手册回答四个问题：

部署前需要准备什么
Active 和 Standby 各自要执行什么
怎么配置 etcd-sync 让 SeedBundle 同步过去
怎么验证两边密钥一致；出问题怎么处理

适用范围

Global 集群安装 etcd-encryption-manager，使用 deterministic 模式
etcd-sync 版本需 v4.3.7 或更高
runtime Active / Standby 角色不再手工配置，由 kube-public/etcd-sync ConfigMap 自动判定

前置条件

项目	要求
etcd-sync	`v4.3.7` 及以上
Root Secret	`kube-system/<root_secret_name>`，Active 与 Standby 内容完全一致，32 字节随机数据
`replication_group_id`	同一对 Active/Standby 必须完全一致；不要直接用 cluster name
集群名	当 `global.cluster.name=global` 时，chart 会强制 `key_strategy=deterministic`

部署流程

整体顺序：

1. 规划 `replication_group_id`

同一 DR 组内的 Active 与 Standby 必须配相同值。推荐使用 UUID 风格、不暴露业务身份的不透明标识。

生成示例：

openssl rand -hex 16 | sed -E 's/^(.{8})(.{4})(.{4})(.{4})(.{12})$/\1-\2-\3-\4-\5/'

2. 在 Active 与 Standby 各自创建 Root Secret

两边内容必须完全一致。先在任一侧生成、再把同一份内容部署到另一侧。

生成 32 字节随机数据：

openssl rand -out ./root-key.bin 32

在 Active 创建：

kubectl -n kube-system create secret generic etcd-derivation-root \
  --from-file=root-key=./root-key.bin

在 Standby 创建（用同一份root-key.bin）：

kubectl -n kube-system create secret generic etcd-derivation-root \
  --from-file=root-key=./root-key.bin

文件传输完成后立即销毁 root-key.bin。

3. 安装 `etcd-encryption-manager`

通过 chart 或插件 UI 安装时，填入下列三个参数：

插件参数	Chart 字段	推荐值
`key_strategy`	`etcdEncryption.keyStrategy`	`deterministic`
`replication_group_id`	`etcdEncryption.deterministic.replicationGroupID`	步骤 1 规划的值
`root_secret_name`	`etcdEncryption.deterministic.rootSecretRef.name`	`etcd-derivation-root` 或你们的统一命名

其余参数（dimension、derivationAlgorithm、activationPolicy、approvalDelay、rootSecretRef.namespace）当前不在插件 UI 暴露，使用默认值即可。rootSecretRef.namespace 固定为 kube-system。

4. 配置 etcd-sync 规则

为这一组 SeedBundle / 本地状态 / Secret / marker 单独维护一个产品级 ConfigMap，按 etcd-sync-dynamic-configmap-migration/provider-spec.md 规定的字段约定写：

apiVersion: v1
kind: ConfigMap
metadata:
  name: etcd-encryption-manager-rules
  namespace: cpaas-system
  labels:
    etcd-sync.cpaas.io/enabled: "true"
data:
  sync-prefix-file.txt: |
    /registry/etcdkeyseedbundles.cluster.alauda.io/
  ignore-prefix-file.txt: |
    /registry/etcdkeyseedbundlestates.cluster.alauda.io/
    /registry/secrets/kube-system/etcd-encryption-key-
  ignore-equal.txt: |
    /registry/etcdencryptionconfigs.cluster.alauda.io/default
    /registry/secrets/kube-system/etcd-derivation-root
    /registry/configmaps/kube-public/etcd-sync

如果 root_secret_name 不是默认值，把 ignore-equal.txt 中的最后一项替换成实际名称。

5. 验证

下面这张时序图概括了"装好之后到底发生了什么"，验证步骤也是顺着这条时间线一项一项检查：

依次确认：

检查	命令 / 看什么	预期
Active 已生成 SeedBundle	`kubectl get etcdkeyseedbundles`	至少一条记录，`Revision` 单调递增
Standby 收到 SeedBundle	在 Standby 上执行同样命令	与 Active 同 `Revision` 的对象出现
两边派生出同一把 key	比对 `kubectl -n kube-system get secret etcd-encryption-key-<revision> -o jsonpath='{.data.key}'`	两边输出完全相同
加密配置就绪	`kubectl get etcdencryptionconfig default -o jsonpath='{.status.deployStatus}'`	各 etcd 节点的 `state` 进入 `Success`
runtime 角色判定	看 etcd-encryption-manager 日志	Active 端日志显示 active 角色，Standby 端显示 standby

常见故障

症状	可能原因	处理
Standby 上 `etcd-encryption-key-<revision>` 与 Active 不同	Root Secret 不一致，或 `replication_group_id` 不一致	比对两边 Secret 内容；纠正参数后重新触发 SeedBundle 派生
Standby 没收到 SeedBundle	etcd-sync 规则未覆盖、规则被 reject、weight 被压制	看本产品 ConfigMap 的状态 annotation；参考迁移手册排障章节
Standby 启动时报 `root secret must be 32 bytes`	Secret 数据 key 不是 `root-key`，或长度不对	用 `kubectl -n kube-system get secret etcd-derivation-root -o yaml` 检查
Standby 报告角色与预期不符	`kube-public/etcd-sync` ConfigMap 不在预期一侧	该 ConfigMap 由本地 etcd-sync 维护；先确认 etcd-sync 自身角色配置正确
切换演练后控制器日志反复出现 "runtime role change ... restart required"	这是正常行为：runtime 监控发现角色翻转后会主动退出，由 supervisor 重启进程，避免老进程持有过期角色上下文	等容器重启即可

回滚

回滚到 random 模式只对单集群有意义；DR 双方继续使用 etcd-sync 的话不能回滚到 random，因为 random 两侧 key 不一致。

如果需要紧急停用 deterministic：

把 etcd-encryption-manager chart values 中的 etcdEncryption.keyStrategy 改为 random，重新部署
此时 etcd-sync 仍会同步密文，但 Standby 解密会失败。仅限于切断 DR 复制后单集群独立运行的场景

交接清单

replication_group_id 已沉淀到产品文档
Root Secret 内容由谁、用什么方式分发，已写入 Runbook
etcd-sync 产品 ConfigMap 名称、命名空间、weight 已固化
切换演练剧本中已包含 SeedBundle 同步与密钥派生一致性两项验证

Deterministic 模式部署手册

On this page