Bitnami valkey-cluster Helm Chart 演进全解析：从分片集群诞生到 3.0.x 的安全加固与运维能力迭代

导读：本文以 Bitnami valkey-cluster Helm Chart 的 CHANGELOG.md 为时间骨架，完整梳理该图表从 0.1.0（2024-07）到 3.0.24（2025-08）的版本演进脉络，并深入 values.yaml 与 templates/ 下的模板实现，剖析每个关键变更背后的技术动因——包括认证方式从环境变量转向密码文件、master/slave 到 primary/replica 的术语体系迁移、Prometheus 监控链路修复、集群节点在线增删等。读完你将掌握该图表的架构形态、核心参数语义，以及各版本升级时需要注意的兼容性要点，可直接用于生产集群的选型与升级规划。

一、图表全景：当前版本与核心定位

valkey-cluster 是 Bitnami 提供的、用于在 Kubernetes 上部署 Valkey Cluster（分片集群） 的 Helm Chart。Valkey 是 BSD 协议开源的高性能 key/value 数据存储，可承载缓存、消息队列等负载，也可作为主数据库。与部署"主从 + Sentinel"形态的 Valkey Chart 不同，valkey-cluster 部署的是原生 Cluster 模式：数据被划分为 16384 个哈希槽（hash slot）分布在多个主节点上，支持多写入点。

从 Chart.yaml 可以看到当前仓库内该图表的元信息：

• version: 3.0.25（应用版本号 appVersion: 8.1.3，对应 bitnami/valkey-cluster:8.1.3-debian-12-r3 镜像）
• 唯一依赖为 common（oci://registry-1.docker.io/bitnamicharts，2.x.x），几乎所有命名、探针、亲和性、安全上下文逻辑都复用了 bitnami/common 中的模板
• tanzuCategory: service 注解（这正是 2.2.1 版本引入的变更）

从 CHANGELOG 看，该图表诞生于 2024-07-08 的 0.1.0，在约 14 个月内历经 55 个版本条目，经历了"从 0.x 快速迭代 → 1.0 稳定 → 2.0 术语体系重构 → 3.0 安全与生态适配"的完整生命周期。

二、部署形态：Valkey 与 Valkey Cluster 两种图表的本质区别

README.md 给出了两张拓扑对比图，可以帮助我们理解该图表到底"部署了什么"：

两者的核心差异总结如下：

能力维度	Valkey（valkey Chart）	Valkey Cluster（valkey-cluster Chart）
数据库数量	支持多个逻辑数据库	仅支持一个数据库（SELECT 受限），更适合大数据集
写入点	单一主节点写入	多主节点并行写入
高可用机制	Sentinel 监控与自动故障转移	原生 Cluster 模式，副本自动晋升主节点
扩容方式	提升副本能力 / 更换规格	在线添加节点并 rebalance 哈希槽

节点规模计算规则（源自 README 与 cluster 参数）：

nodes = numOfPrimaryNodes + numOfPrimaryNodes * replicas

默认值 cluster.nodes=6、cluster.replicas=1 意味着部署 3 个主节点 + 3 个副本节点；主节点数必须 ≥ 3，否则集群创建会失败。配置如 cluster.nodes=9、cluster.replicas=2 则得到 3 主 + 每主 2 副本的布局。该公式在 update-cluster.yaml 的节点扩容脚本中也被直接复用（currentPrimaryNodesNum、replicaNodesEndPos 的计算）。

三、完整版本时间线（0.1.0 → 3.0.24）

以下是 CHANGELOG 全部版本条目的时间线总览，便于建立整体演进印象：

版本	日期	关键内容
0.1.0	2024-07-08	首次加入 valkey-cluster 图表（#27737）
0.1.1	2024-07-08	常规发布
0.1.2	2024-07-11	常规发布
0.1.3	2024-07-18	将 Global StorageClass 作为默认值（#28106）
0.1.4	2024-07-22	修复外部访问模板中的名称生成循环（#28163）
0.1.5 / 0.1.6	2024-07-24 / 07-25	常规发布
0.1.7	2024-07-29	更新 metrics-svc 模板名称格式（#27993）
0.1.8	2024-07-31	常规发布
0.1.9	2024-08-19	修复 metrics 容器的环境变量（#28885）
0.1.10	2024-08-28	改进 ginkgo 测试可靠性（#29080）
0.1.11	2024-09-09	常规发布
1.0.0	2024-09-16	首个 1.0 稳定版（#29450）
1.0.1	2024-09-26	redis_exporter 的 redis_url 改用 rediss/redis scheme 而非 valkey（#29589）
1.0.2 / 1.0.3	2024-10-03 / 10-22	文档链接迁移至 techdocs.broadcom.com 等
2.0.0	2024-10-23	全部引用从 master/slave 改为 primary/replica（#30025）
2.0.1	2024-11-08	移除 imagePullPolicy 错误注释、统一 seLinuxOptions 默认值（#30322）
2.0.2	2024-12-01	补充 Prometheus metrics 文档（#30675）
2.1.0	2024-12-10	NOTES.txt 增加 Bitnami Premium、新增"Update Credentials"文档、检测非标准镜像（#30951）
2.1.1	2025-01-08	修复 README 拼写错误
2.1.2	2025-02-17	使用 CDN 图标、更新版权年份
2.1.3	2025-02-20	常规发布
2.2.0	2025-02-24	usePasswordFiles=true 设为默认（#32122）
2.2.1	2025-03-28	增加 tanzuCategory 注解（#32409）
3.0.0	2025-04-09	3.x 系列开启（#32934）
3.0.1 / 3.0.2	2025-04-09	常规发布
3.0.3	2025-04-23	常规发布
3.0.4	2025-05-05	仅在启用认证时挂载密码文件（#33239）
3.0.5	2025-05-07	更新 common、移除 K8s < 1.23 相关引用（#33444）
3.0.6	2025-05-13	kubeapps 弃用跟进 + 依赖更新
3.0.7 ~ 3.0.18	2025-05-15 ~ 07-15	持续依赖引用更新（13 个版本）
3.0.19	2025-08-07	BSI（Bitnami Secure Images）品牌化：README ascii、欢迎语、notes 警告（#35173/#35170/#35174/#35340）
3.0.20 ~ 3.0.24	2025-08-07 ~ 08-23	持续依赖引用更新

从分布规律看，0.x 阶段（约 3 个月）密集修复的是集群可用性、监控与模板健壮性问题；1.x 阶段完成稳定与文档化；2.x 阶段完成术语重构、认证方式升级与镜像供应链加固；3.x 阶段则进入"安全镜像品牌化 + 依赖持续跟进"的常态化维护期，几乎每个版本都在跟随 common 与容器镜像同步更新依赖引用。

四、术语体系演进：2.0.0 的 master/slave → primary/replica 重构

2.0.0 是首个不向后兼容的大版本。变更内容非常明确：

• 参数前缀从 master 改为 primary
• 环境变量从 VALKEY_MASTER、VALKEY_SENTINEL_MASTER 改为 VALKEY_PRIMARY、VALKEY_SENTINEL_PRIMARY

这一变更的源码痕迹在今天依然可见。在 configmap.yaml 中，所有 Valkey 默认配置的注释与指令都已使用 primary/replica 术语体系，例如：

• # By default, outgoing connections (from replica to primary, from Sentinel to ...)（L109）
• replica-serve-stale-data yes、replica-read-only yes（L580 / L596）
• replicaof <primaryip> <primaryport>、primaryauth <primary-password>（L546 / L553）

模板层的脚本（如 scripts-configmap.yaml 中的探针脚本）同样全部采用新术语。由于这是全局性重命名，从 1.x 直接 helm upgrade 到 2.0.0 不保证向后兼容，README 明确建议：先备份数据，在新版本上安装全新 release，再通过备份恢复（参见 README 的 Upgrading 一节）。

五、认证与凭证管理演进：从环境变量到密码文件

这是该图表安全能力最核心的演进线，涉及三个关键版本：

5.1 2.2.0：usePasswordFiles=true 成为默认

密码作为环境变量注入容器存在泄露风险（env 可见、易进入进程命令行与日志），而挂载为只读文件更安全。2.2.0 将 values.yaml 中的 usePasswordFiles 默认值从 false 改为 true，这一行为在模板中的体现如下（valkey-statefulset.yaml）：

{{- if .Values.usePassword }}
- name: REDISCLI_AUTH
  valueFrom:
    secretKeyRef:
      name: {{ template "valkey-cluster.secretName" . }}
      key: {{ template "valkey-cluster.secretPasswordKey" . }}
{{- if .Values.usePasswordFiles }}
- name: VALKEY_PASSWORD_FILE
  value: "/opt/bitnami/valkey/secrets/valkey-password"
{{- else }}
- name: VALKEY_PASSWORD
  valueFrom:
    secretKeyRef:
      name: {{ template "valkey-cluster.secretName" . }}
      key: {{ template "valkey-cluster.secretPasswordKey" . }}
{{- end }}

当 usePasswordFiles=true 时，容器只拿到 VALKEY_PASSWORD_FILE 指向的路径，密码本身以文件形式挂载（L277-L279、L441-L447）：

volumeMounts:
  - name: valkey-password
    mountPath: /opt/bitnami/valkey/secrets/
...
volumes:
  - name: valkey-password
    secret:
      secretName: {{ include "valkey-cluster.secretName" . }}
      items:
        - key: {{ include "valkey-cluster.secretPasswordKey" . }}
          path: valkey-password

密码的载体是 secret.yaml 中渲染的 Secret，其中固定使用 valkey-password 作为键名——这也是 README 强调"使用密码文件时，Secret 中的密码文件必须命名为 valkey-password"的原因。

5.2 3.0.4：仅在启用认证时才使用密码文件

3.0.4 进一步收紧了条件：valkey-password 卷与挂载点仅在 usePassword && usePasswordFiles 同时为真时生成（见上文模板中大量 and .Values.usePassword .Values.usePasswordFiles 的守卫）。这避免了关闭认证（usePassword=false）时产生无意义的 Secret 挂载，也让模板条件与 secret.yaml 的渲染条件（usePassword && not existingSecret）保持了一致。

5.3 探针脚本如何消费密码文件

探针逻辑在 scripts-configmap.yaml 中，其 ping_readiness_local.sh / ping_liveness_local.sh 会先读取密码文件再导出为 REDISCLI_AUTH：

password_aux=`cat ${VALKEY_PASSWORD_FILE}`
export REDISCLI_AUTH=$password_aux

而非文件模式则回退到 VALKEY_PASSWORD 环境变量。这解释了为何 2.2.0 切换默认值后，探针、状态检查（CLUSTER INFO 的 cluster_state:ok 判断）、以及 valkey-cli 认证（REDISCLI_AUTH）能够无感工作——整套凭证链路是统一设计的。

5.4 凭证更新方式

由于 Helm 渲染的 Secret 会被复用，升级时更新凭证有两种方式（README "Update credentials"）：

• helm upgrade 时通过 --set password=... 指定新密码
• 或提供新的 existingSecret

六、监控可观测性演进：metrics 链路的三次关键修复

metrics.enabled=true 时会在每个 Pod 中注入 redis_exporter sidecar（镜像 bitnami/redis-exporter），并渲染 metrics-svc.yaml 中带 Prometheus 抓取注解的 Service，还可配合 metrics.serviceMonitor.enabled 生成 ServiceMonitor。这条链路在 0.x 阶段经历了三次关键修复：

• 0.1.7（#27993）：修正 metrics Service 的模板命名格式（printf "%s-metrics" ... | replace "+" "_" | trunc 63 | trimSuffix "-"），确保服务名长度与合法性符合 Kubernetes DNS 规范。
• 0.1.9（#28885）：修复 metrics 容器（sidecar）的环境变量。当前实现中（valkey-statefulset.yaml），exporter 使用 REDIS_ALIAS、REDIS_ADDR、REDIS_PASSWORD_FILE/REDIS_PASSWORD、REDIS_EXPORTER_WEB_LISTEN_ADDRESS（:9121）等变量。
• 1.0.1（#29589）：修复 redis_url 的 scheme。exporter 连接地址必须使用 rediss://（TLS 开启时）或 redis://，而非 valkey://：

- name: REDIS_ADDR
  value: {{ printf "%s://127.0.0.1:%g" (ternary "rediss" "redis" .Values.tls.enabled) .Values.valkey.containerPorts.valkey | quote }}

值得注意的是，即使应用本身叫 Valkey，exporter 仍是 redis_exporter，因此其 REDIS_* 系列变量名与 redis/rediss scheme 全部保持 redis 生态约定。2.0.2 又补充了完整的 Prometheus metrics 接入文档，使得该链路从"可用"走向"可文档化、可运维"。

七、集群运维能力演进：外部访问、在线扩缩容与高可用

7.1 0.1.4：修复外部访问模板的名称生成循环

外部访问模式（cluster.externalAccess.enabled=true）会为每个节点生成一个独立的 Service（默认 LoadBalancer 类型，端口 6379 + 总线端口 16379）。0.1.4 修复了该模板中的名称生成循环。当前实现（svc-cluster-external-access.yaml）用 until $nodesCount 精确控制循环次数，并用 statefulset.kubernetes.io/pod-name: {{ $targetPod }} 选择器把每个 Service 绑定到对应 Pod，同时按 loadBalancerIP 数组逐索引分配固定 IP——这正是 README 中"先安装拿到 6 个外部 IP，再在 upgrade 时回填 loadBalancerIP 数组"两阶段流程的模板基础。

7.2 在线添加节点：post-upgrade 钩子 Job

update-cluster.yaml 渲染的是一个 post-upgrade Helm hook Job（"helm.sh/hook": {{ .Values.updateJob.helmHook }}，默认 post-upgrade），只有 cluster.update.addNodes=true 时才创建。其脚本逻辑完整对应 README 的扩节点流程：

• 内部网络模式下，用 wait_for_dns_lookup 等待新 Pod 的 headless DNS 就绪，然后对每个新节点执行 valkey-cli --cluster add-node <newNodeIP> <firstNodeIP>，并依据 newNodeIndex 与 replicaNodesEndPos 的数学关系判断该节点应作为 replica 加入（--cluster-slave）还是作为新 primary；
• 添加完成后执行 valkey-cli --cluster rebalance ... --cluster-use-empty-masters 重新分配哈希槽，失败时自动 --cluster fix 重试；
• 外部访问模式下，则遍历 cluster.update.newExternalIPs，以 loadBalancerIP[0] 作为集群入口执行 add-node，这正是 README 中"两次 upgrade"流程（先扩容拿 IP，再回填 IP 触发加节点）的模板支撑。

扩缩容期间集群可持续服务，前提是不丢失 quorum——因此 README 建议单次缩容差值 ≤ cluster.replicas，避免同时下线主节点及其副本。

7.3 缩容与故障节点清理

缩容时先 helm upgrade --set cluster.nodes=6（需提供安装时的 password，并设置 cluster.init=false 防止重复执行初始化 Job），再用 valkey-cli -a $VALKEY_PASSWORD CLUSTER NODES 查看标记为 fail 的节点 ID，在每个存活节点上执行 CLUSTER FORGET <NODE_ID> 完成集群元数据清理。

7.4 高可用与数据持久化配套

• pdb.create=true 默认生成 PodDisruptionBudget，配合 updateStrategy: RollingUpdate 与 podManagementPolicy: Parallel 保障滚动更新安全；
• 持久化默认挂载 /bitnami/valkey/data（8Gi，ReadWriteOnce），并支持 persistentVolumeClaimRetentionPolicy；
• 禁用持久化仅推荐用于测试——缺少 nodes.conf 的节点重启后会"自封 primary"脱离集群，README 给出了通过 nodes.sh 获取节点 IP 映射、再用 cluster meet 重新接入的恢复方法。

八、安全与供应链演进：镜像验证、BSI 与生态注解

8.1 2.1.0：镜像验证与非标准镜像检测

2.1.0 引入了镜像验证（image verification）：渲染的 StatefulSet 与 Job 会校验镜像是否来自受信任来源；若使用私有镜像仓库或自定义镜像，需显式设置 global.security.allowInsecureImages=true 跳过校验。同版本还新增了"非标准镜像检测"（#30951），避免误用不兼容镜像导致集群初始化失败。

8.2 3.0.19：全面转向 Bitnami Secure Images（BSI）

3.0.19 是一组横跨所有 Bitnami 图表的品牌化变更：

• 调整主 README 排版与 ascii 图案（#35173）
• 将安装后的欢迎信息（NOTES.txt）适配 BSI 语境（#35170 / #35340）
• 在 README 中统一加入 BSI 说明（#35174）

BSI 是基于 VMware Photon OS 构建的加固镜像，强调 Near-Zero Vulnerabilities、VEX 漏洞披露、FIPS/STIG 合规选项与 in-toto 供应链可溯源（详见 README.md）。这也解释了 3.0.4 之后版本为何密集跟随镜像版本更新依赖引用——安全镜像的持续迭代正是 BSI 体系的核心承诺。

8.3 其他安全与合规相关变更

• 2.2.1：增加 tanzuCategory: service 注解，便于 Tanzu Application Catalog 分类；
• 2.0.1：统一 seLinuxOptions 默认值、移除关于 imagePullPolicy 的错误注释；
• 2.1.0 / 2.1.2：NOTES.txt 增加 Bitnami Premium 提示、图标迁移到 CDN；
• 当前版本的安全基线可从 values.yaml 的 podSecurityContext / containerSecurityContext 看到：runAsUser: 1001、runAsNonRoot: true、readOnlyRootFilesystem: true、capabilities.drop: ["ALL"]、seccompProfile: RuntimeDefault，并支持 global.compatibility.openshift.adaptSecurityContext 自动适配 OpenShift restricted-v2 SCC。

九、基础设施适配与工程质量

• 0.1.3（#28106）：默认 StorageClass 改由 global.defaultStorageClass 统一提供（替代各图表各自硬编码），global.storageClass 被标记为 DEPRECATED——这是跨图表一致性治理的早期动作。
• 3.0.5（#33444）：更新 common 依赖并移除 Kubernetes < 1.23 的兼容引用。因此当前图表的前置条件是 Kubernetes 1.23+、Helm 3.8.0+（README Prerequisites）。
• 0.1.10（#29080）：改进 ginkgo 测试可靠性——说明该图表的发布质量是由自动化测试保障的，0.x 阶段在功能修复的同时持续完善测试套件，为 1.0.0 稳定版奠定基础。
• 1.0.3：将文档链接从旧站点迁移至 techdocs.broadcom.com，反映项目从 Bitnami 到 Broadcom 的品牌归并过程。

十、升级路径与兼容性速查

基于 CHANGELOG 与 README 的 Upgrading 章节，升级时需特别注意以下门槛：

目标版本	注意事项
2.0.0+	master* 参数与 VALKEY_MASTER* 环境变量已失效，需改用 primary* / VALKEY_PRIMARY*；不保证向后兼容，建议全新安装 + 数据迁移
2.1.0+	默认启用镜像验证，私有镜像需设 global.security.allowInsecureImages=true
2.2.0+	usePasswordFiles 默认 true，升级前请确认探针/脚本依赖的是密码文件路径还是 VALKEY_PASSWORD 环境变量
3.0.5+	不再支持 Kubernetes < 1.23
任意扩缩容	遵循 README 的两阶段流程并传 cluster.init=false，避免初始化 Job 重复执行导致集群状态错乱

此外，所有升级在修改认证凭证时都应遵循"升级复用 Secret"原则：要么在 password 中显式传入新密码，要么切换 existingSecret，不要删除原 Secret。

结语

回顾整个 CHANGELOG，valkey-cluster 的演进轨迹清晰可循：0.x 打磨集群可用性与监控链路 → 1.x 稳定化与文档化 → 2.x 术语体系重构与安全默认值升级 → 3.x 安全镜像常态化迭代与基础设施版本跟随。每一步变更都能在 values.yaml 与 templates/ 中找到对应的实现证据：密码文件机制沉淀在 StatefulSet 的条件挂载逻辑里，扩缩容能力沉淀在 post-upgrade 钩子 Job 的 add-node/rebalance 脚本里，安全加固则体现在 SecurityContext 与镜像验证的默认值中。对于计划在生产环境使用 Valkey Cluster 的团队，本文梳理的版本门槛与参数语义，可以作为选型、升级与排障的直接参考。