连接到 Cluster 实例

Valkey Cluster 将 key 分布到 16,384 个哈希槽中。客户端必须发现拓扑并跟随 MOVED 和 ASK 重定向。不支持 Cluster 的客户端可以连接到一个节点，但当命令属于另一个节点时，会向应用暴露重定向错误。

有关协议级行为，请参阅官方 Valkey Cluster 规范。

发现 Service 和节点

kubectl -n default get valkey valkey-cluster -o wide
kubectl -n default get service -l buf.red/name=valkey-cluster -o wide
kubectl -n default get valkey valkey-cluster \
  -o jsonpath='{range .status.nodes[*]}{.podName}{"\t"}{.role}{"\t"}{.ip}{":"}{.port}{"\t"}{.slots}{"\n"}{end}'

对于 ClusterIP，与 Valkey 资源同名的 Service 是一个引导端点。客户端从服务器获取拓扑，然后打开到公布的节点地址的连接。

使用 valkey-cli 连接

使用 -c 跟随 Cluster 重定向：

valkey-cli -c -h valkey-cluster.default.svc -p 6379 PING

使用访问控制列表（ACL）认证：

valkey-cli -c -h valkey-cluster.default.svc -p 6379 \
  --user app --askpass PING

测试一个一次性 key：

valkey-cli -c -h valkey-cluster.default.svc -p 6379 \
  --user app --askpass SET connectivity:{test} ok EX 60
valkey-cli -c -h valkey-cluster.default.svc -p 6379 \
  --user app --askpass GET connectivity:{test}

花括号定义哈希标签。花括号内具有相同非空文本的 key 会映射到同一个槽，这对于在单个 Cluster 槽上操作的多 key 命令是必需的。

验证拓扑

从就绪的数据 Pod 或已认证的客户端端点运行健康检查命令：

kubectl -n default exec <ready-cluster-pod> -c valkey -- \
  valkey-cli CLUSTER INFO
kubectl -n default exec <ready-cluster-pod> -c valkey -- \
  valkey-cli CLUSTER NODES
kubectl -n default exec <ready-cluster-pod> -c valkey -- \
  valkey-cli CLUSTER SHARDS

确认 cluster_state:ok、完整的槽分配、预期的主节点和从节点数量，以及可访问的公布地址。

使用 TLS

valkey-cli -c --tls --cacert <ca-file> \
  --cert <client-certificate-file> --key <client-key-file> \
  -h valkey-cluster.default -p 6379 \
  --user app --askpass PING

默认情况下，生成的服务器要求受信任的客户端证书。对于此示例，生成的证书中包含引导名称 valkey-cluster.default；但不包含 .svc 形式。此命令只能证明引导连接可以通过认证。

Cluster 会为节点连接公布生成的每个 Pod 的 Service 地址，但生成的证书不包含这些 Service 名称或地址。因此，即使引导 PING 成功，执行常规主机名验证的客户端在 MOVED 或 ASK 之后也可能失败。请将此视为未解决的 2.0.0 Cluster TLS 限制。要求交付的构建将每个公布的端点与证书的 subject alternative name 对齐，并在每个分片上测试一个 key。不要使用 --insecure 作为临时解决方法。

外部访问

Cluster 外部访问会为每个 Pod 创建 Service，以便公布的拓扑可以将客户端直接路由到正确的节点。发现所有生成的 Service：

kubectl -n default get service -l buf.red/name=valkey-cluster -o wide

对于 LoadBalancer，请等待每个所需的按 Pod Service 都具有 ingress 地址。对于 NodePort，请确保客户端可以到达所选的节点地址和所有分配的端口。如果重定向后的节点端点被阻止，单个可访问的引导端点是不够的。

生成的证书同样不涵盖任意外部地址，因此上述 Cluster TLS 限制同样适用于外部访问以及集群内公布的拓扑。

对于 2.0.0，请保持 spec.access.ports 未设置，除非交付的构建文档说明了已验证的固定端口格式。随后 Kubernetes 会分配 NodePort。

应用客户端要求

当客户端库支持时，请配置多个引导端点。
启用拓扑刷新以及 MOVED/ASK 处理。
使用有边界的连接、命令和重试超时。
为每个公布的节点确认 DNS、路由、防火墙规则、TLS 名称和网络策略。
将多 key 操作限制在一个哈希槽内，或重新设计该操作。
在扩容、故障转移、访问变更或证书轮换后，重新验证拓扑行为。

Cluster 复制是异步的，并且该协议允许在已文档化的故障窗口内丢失已确认的写入。请参阅官方 Cluster 规范、CLUSTER SHARDS 参考、TLS 文档和客户端目录。请在所选库自身的文档和测试中验证其行为。

#连接到 Cluster 实例

#目录

#发现 Service 和节点

#使用 valkey-cli 连接

#验证拓扑

#使用 TLS

#外部访问

#应用客户端要求