bitnamicharts/valkey-cluster

Bitnami Valkey Cluster Helm Chart

镜像概述和主要用途

Valkey 是一款开源（BSD许可）的高性能键值存储系统，支持缓存、消息队列等多种工作负载，亦可作为主数据库使用。Bitnami Valkey Cluster Helm Chart 用于在 Kubernetes 集群上通过 Helm 包管理器部署 Valkey 集群，实现基于分片（sharding）的分布式部署架构。

Valkey Cluster 官方概述

商标说明：本软件包由 Bitnami 打包。所提及的商标分属各自公司所有，使用此类商标不意味着任何关联或背书。

核心功能和特性

• 分片集群架构：基于 Valkey Cluster 原生分片机制，将数据分布在多个主节点，支持大规模数据集存储
• 多主写入能力：集群包含多个主节点，均可处理写入请求，提升并发写入性能
• 自动故障转移：主节点故障时，其副本节点自动晋升为主节点，保障服务可用性
• 动态扩缩容：支持在线添加/移除节点，调整集群规模以适应负载变化
• Prometheus 监控集成：可部署 redis_exporter 采集 metrics，支持 Prometheus 自动发现
• 资源优化配置：支持资源请求/限制设置，提供预设资源配置模板
• 安全增强：支持密码认证、TLS 加密通信、网络策略隔离
• 持久化存储：默认使用 PersistentVolume 存储集群元数据（nodes.conf）及数据，避免节点重启后集群信息丢失

使用场景和适用范围

适用场景

• 大规模数据集存储：需通过分片扩展存储容量的场景（如亿级键值存储）
• 高并发读写应用：多主节点架构适合读写字节高的业务（如实时统计、会话存储）
• 高可用关键业务：需自动故障转移、避免单点故障的生产环境
• 开发/测试环境：快速部署 Valkey 集群用于功能验证或性能测试

Valkey 与 Valkey Cluster Helm Chart 对比

先决条件

• Kubernetes 集群版本 1.23+
• Helm 版本 3.8.0+
• 集群支持 PersistentVolume（PV）动态供应

详细使用方法和配置说明

快速安装（TL;DR）

console
helm install my-release oci://registry-1.docker.io/bitnamicharts/valkey-cluster

生产环境建议：如需用于生产环境，推荐使用 VMware Tanzu Application Catalog（Bitnami 商业版应用目录）。

⚠️ 重要通知：Bitnami 镜像目录即将变更

自 2025 年 8 月 28 日起，Bitnami 将升级其公共镜像目录，推出Bitnami Secure Images 计划，提供经过安全加固的精选容器镜像。过渡期变更如下：

• 首次向社区用户开放安全优化版容器镜像
• 逐步弃用免费 tier 中非加固的 Debian 基础镜像，公共目录将仅保留少量加固镜像（仅含 "latest" 标签，适用于开发环境）
• 8 月 28 日起，两周内所有现有容器镜像（含历史版本标签，如 2.50.0、10.6）将从公共目录（docker.io/bitnami）迁移至 "Bitnami Legacy" 仓库（docker.io/bitnamilegacy），且不再更新
• 生产环境建议采用 Bitnami Secure Images，包含加固容器、更小***面、CVE 透明度（通过 VEX/KEV）、SBOM 及企业支持

更多详情见 https://github.com/bitnami/containers/issues/83267%E3%80%82

安装步骤

标准安装

使用默认配置部署 Valkey Cluster：

console
helm install my-release oci://registry-1.docker.io/bitnamicharts/valkey-cluster

注意：如需指定私有仓库，需替换 REGISTRY_NAME 和 REPOSITORY_NAME。例如 Bitnami 公共仓库为 REGISTRY_NAME=registry-1.docker.io，REPOSITORY_NAME=bitnamicharts。

自定义安装

通过 --set 参数覆盖默认配置，例如指定集群节点数和副本数：

console
helm install my-release oci://registry-1.docker.io/bitnamicharts/valkey-cluster \
  --set cluster.nodes=9 \
  --set cluster.replicas=2 \
  --set password=StrongPassword123

处理安装超时

若因集群初始化耗时过长导致超时，可增加超时时间：

console
helm install --timeout 600s my-release oci://registry-1.docker.io/bitnamicharts/valkey-cluster

核心配置参数

高级配置

1. 外部访问配置

默认集群仅允许 Kubernetes 集群内访问，如需外部访问（如本地 valkey-cli 连接）：

1. 首次部署时启用外部访问：

console
helm install my-release oci://registry-1.docker.io/bitnamicharts/valkey-cluster \
  --set cluster.externalAccess.enabled=true \
  --set cluster.externalAccess.service.type=LoadBalancer

2. 获取 Load* IP**：部署后，每个节点会创建 Load*** 服务，获取其外部 IP：

console
kubectl get svc -l app.kubernetes.io/instance=my-release

3. 升级集群配置外部 IP：将获取的 IP 填入 cluster.externalAccess.service.loadBalancerIP 数组：

console
helm upgrade my-release oci://registry-1.docker.io/bitnamicharts/valkey-cluster \
  --set cluster.externalAccess.enabled=true \
  --set cluster.externalAccess.service.loadBalancerIP[0]=<ip-0> \
  --set cluster.externalAccess.service.loadBalancerIP[1]=<ip-1> \
  --set cluster.externalAccess.service.loadBalancerIP[2]=<ip-2> \
  --set cluster.externalAccess.service.loadBalancerIP[3]=<ip-3> \
  --set cluster.externalAccess.service.loadBalancerIP[4]=<ip-4> \
  --set cluster.externalAccess.service.loadBalancerIP[5]=<ip-5> \
  --set cluster.init=false

2. 集群扩缩容

扩容集群（添加节点）

1. 非外部访问场景：直接调整 cluster.nodes 并指定密码：

console
helm upgrade --timeout 600s my-release \
  --set password=${VALKEY_PASSWORD} \
  --set cluster.nodes=9 \
  --set cluster.update.addNodes=true \
  --set cluster.update.currentNumberOfNodes=6 \
  oci://registry-1.docker.io/bitnamicharts/valkey-cluster

说明：cluster.update.currentNumberOfNodes 为当前节点数，cluster.update.addNodes=true 触发添加节点的 Job。

2. 外部访问场景：需分两次升级（先创建节点及 Load***，再配置新 IP），详见英文文档“External Access”部分。

缩容集群（减少节点）

1. 调整节点数：缩容后节点数不得少于 6，且缩容数量不超过 cluster.replicas：

console
helm upgrade --timeout 600s my-release \
  --set password=${VALKEY_PASSWORD} \
  --set cluster.nodes=6 \
  --set cluster.init=false \
  oci://registry-1.docker.io/bitnamicharts/valkey-cluster

2. 清理失效节点：缩容后通过 CLUSTER FORGET 命令移除失效节点 ID：

console
# 获取失效节点 ID
valkey-cli -a $VALKEY_PASSWORD CLUSTER NODES | grep fail
# 在每个节点执行（替换 NODE_ID）
valkey-cli -a $VALKEY_PASSWORD CLUSTER FORGET <NODE_ID>

3. Prometheus 监控集成

启用 metrics 采集并集成 Prometheus：

console
helm install my-release oci://registry-1.docker.io/bitnamicharts/valkey-cluster \
  --set metrics.enabled=true \
  --set metrics.serviceMonitor.enabled=true  # 如需 Prometheus Operator 集成

• 指标暴露：通过 sidecar 容器（redis_exporter）暴露指标，端口 9121
• 服务发现：metrics 服务默认添加 prometheus.io/scrape: "true" 注解，支持 Prometheus 自动发现
• ServiceMonitor：启用后创建 ServiceMonitor 资源，适配 Prometheus Operator

4. 安全配置

密码认证

• 自动生成密码：未指定 password 时，密码存储在 Secret <release-name>-valkey-cluster 中，可通过以下命令获取：

console
kubectl get secret my-release-valkey-cluster -o jsonpath="{.data.password}" | base64 -d

• 指定密码：安装时通过 --set password=xxx 设置，或通过 existingSecret 引用现有 Secret。

TLS 加密

1. 创建 TLS 密钥 Secret：

console
kubectl create secret generic valkey-tls --from-file=cert.pem --from-file=key.pem --from-file=ca.pem

2. 启用 TLS 配置：

console
helm install my-release oci://registry-1.docker.io/bitnamicharts/valkey-cluster \
  --set tls.enabled=true \
  --set tls.existingSecret=valkey-tls \
  --set tls.certFilename=cert.pem \
  --set tls.certKeyFilename=key.pem \
  --set tls.certCAFilename=ca.pem

5. 持久化配置

• 默认配置：使用动态 PV 存储 /bitnami 目录（含 nodes.conf 和数据），避免节点重启后集群元数据丢失。
• 禁用持久化：仅推荐测试环境，需设置 persistence.enabled=false，此时使用 emptyDir 存储（节点重启后集群信息丢失，可能导致节点脱离集群）。

备份与恢复

Valkey Cluster 数据备份需通过 Velero 工具备份 PersistentVolume：

1. 安装 Velero：在源集群和目标集群部署 Velero
2. 备份 PV：使用 Velero 备份集群使用的 PV：

console
velero backup create valkey-backup --include-resources=pvc,pv --selector app.kubernetes.io/instance=my-release

3. 恢复 PV：在目标集群恢复备份：

console
velero restore create --from-backup valkey-backup

4. 部署新集群：使用与原集群相同的 release 名称、密码及配置参数，新集群将挂载恢复的 PV 并恢复数据。

主机内核设置优化

Valkey 可能需要调整主机内核参数以优化性能：

• 增大 somaxconn：提高 TCP 连接队列长度
• 禁用透明大页（THP）：避免内存分配延迟波动

通过 initContainer 配置（推荐生产环境）：

yaml
sysctlImage:
  enabled: true
  mountHostSys: true
  command:
    - /bin/sh
    - -c
    - |-
      sysctl -w net.core.somaxconn=10000
      echo never > /host-sys/kernel/mm/transparent_hugepage/enabled

或通过 podSecurityContext.sysctls（Kubernetes 1.12+）：

yaml
podSecurityContext:
  sysctls:
    - name: net.core.somaxconn
      value: "10000"

注意事项

1. 镜像迁移：2025 年 8 月 28 日后，历史版本镜像将迁移至 docker.io/bitnamilegacy，不再更新，生产环境建议迁移至 Bitnami Secure Images。
2. 不可变标签：生产环境推荐使用不可变标签（如 7.2.4-debian-11-r0），避免镜像更新导致部署变更。
3. 持久化必要性：禁用持久化（emptyDir）会导致 nodes.conf 丢失，节点重启后可能脱离集群，仅用于测试。
4. 资源配置：生产环境需根据负载调整 resources，避免使用 resourcesPreset（可能无法适配实际需求）。
5. 集群扩缩容限制：缩容时节点数不得少于 6，且缩容数量不超过 cluster.replicas，避免同时移除主节点及其所有副本。

参考链接

• Valkey 官方文档
• https://github.com/bitnami/charts/tree/main/bitnami/valkey-cluster
• https://github.com/bitnami/containers/issues/83267
• Valkey Cluster 运维指南