#etcd 加密

在 中安装并运行 etcd Encryption Manager，以自动完成集群内 etcd 数据加密密钥轮换。

它可确保存储在 etcd 中的敏感数据（例如 secrets 和 configmaps）使用安全算法加密，从而提升集群安全性。

#密钥策略

该插件支持两种密钥策略。请选择与集群角色匹配的策略。

在 deterministic 模式下，会自动检测运行时 Active / Standby 角色；这不是手动安装参数。

#安装

该插件根据目标集群支持两种安装路径：

• workload / DCS 集群 — 使用默认的 random 密钥策略。
• global 集群 — 必须使用 deterministic 密钥策略（请参见下方的 Global 集群（Deterministic 模式））。

有关通用插件安装流程，请参见 集群插件。

#workload / DCS 集群（random 策略）

• 支持的集群类型：本地部署、DCS。
• 无需额外安装参数——通过标准集群插件工作流安装即可。

#Global 集群（Deterministic 模式）

#前提条件

• 集群必须是 global 集群。当 global.cluster.name 为 global 时，chart 会强制设置 etcdEncryption.keyStrategy=deterministic；对于标记为 is-global=true 的集群，插件 UI 也会将该字段默认设为 deterministic。

#插件参数

插件表单会为 deterministic 安装暴露以下参数。默认值反映了 chart 当前随附的 plugin-config.yaml。

rootSecretRef.namespace 固定为 kube-system，不会在表单中暴露。

#key_strategy

对于 global 集群，这里必须设置为 deterministic。

#replication_group_id

建议：

• 对于使用 etcd Synchronizer 构建的 DR 集群，同一 DR 组的两侧必须共享相同的 replication_group_id。
• 为避免泄露真实业务、环境或集群标识，即使 UI 已预填集群名称，也不要重复使用该名称。请在安装前规划一个单独的不透明标识符。
• 类似 UUID 的标识符可能很合适，例如 6f1b9e2c-7c3a-4a9c-8b72-2fd0f8f3c1ab。

要从命令行生成类似 UUID 的值：

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

#root_secret_name

插件表单仅暴露 Secret 名称；在渲染时命名空间始终为 kube-system。

#准备根 Secret

在安装插件之前，确定性根 Secret 必须已存在于 kube-system 中。请按两个步骤准备：

1. 将 32 字节的密码学强随机材料生成到 ./root-key.bin。这些字节必须来自高熵源——通常是操作系统的 CSPRNG。openssl rand 是安全的默认选择；基于等效操作系统 CSPRNG 的命令，例如 head -c 32 /dev/urandom > ./root-key.bin，也可以使用。不要使用 shell 的 $RANDOM、语言级别的 rand()，或任何基于时间种子的生成器。

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

2. 使用该文件在 kube-system 中创建 Secret：

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

如果您使用不同的 Secret 名称，请将上面的 etcd-derivation-root 替换为您将作为 root_secret_name 输入的值。

#高级（chart 值，未在插件表单中暴露）

#工作原理

安装后，会在 kube-system 命名空间部署 etcd-encryption-manager 控制器，它会：

• 定期轮换 etcd 数据加密密钥。
• 保留最近 8 个密钥以保证回滚兼容性。
• 更新所有控制节点上的加密配置。
• 触发 kube-apiserver 热加载新密钥。
• 自动迁移资源，使用新密钥重新加密数据。

在这些操作过程中，集群稳定性始终得以保持。

当插件在 global DR 对上以 deterministic 模式安装时，控制器还会：

• 在运行时自动检测自身是 Active 还是 Standby——这不是手动配置。
• 在 Active 端生成 SeedBundle，并让 etcd Synchronizer 将其复制到 Standby。
• 在 Standby 端，基于共享的 SeedBundle 和 root Secret 派生相同的按修订版本密钥，因此故障切换无需手动复制密钥即可获得一致的加密密钥。

#默认配置

#运维指南

#配置文件

#检查状态

运行以下命令检查当前轮换状态：

kubectl get EtcdEncryptionConfig default -o yaml

示例输出：

apiVersion: cluster.alauda.io/v1alpha1
kind: EtcdEncryptionConfig
metadata:
  name: default
spec:
  resources:
    - secrets
    - configmaps
  rotationInterval: 168h0m0s
  type: aesgcm
status:
  deployStatus:
    192.168.100.1:
      revision: 3
      state: Success
    192.168.100.2:
      revision: 3
      state: Success
    192.168.100.3:
      revision: 3
      state: Success
  migration:
    completeTimestamp: "2025-05-27T05:47:01Z"
    resources:
      - secrets
      - configmaps
    revision: 3
    state: Success
  revision: 3