#Connect to a Cluster instance

A Valkey Cluster partitions keys across 16,384 hash slots. The client must discover topology and follow MOVED and ASK redirections. A non-Cluster-aware client can connect to one node but exposes redirection errors to the application when a command belongs to another node.

For protocol-level behavior, see the official Valkey Cluster specification.

#Discover Services and nodes

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}'

For ClusterIP, the Service with the same name as the Valkey resource is a bootstrap endpoint. The client obtains topology from the server and then opens connections to the advertised node addresses.

#Connect with valkey-cli

Use -c to follow Cluster redirections:

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

With access control list (ACL) authentication:

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

Test a disposable 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}

Curly braces define a hash tag. Keys with the same non-empty text inside braces map to the same slot, which is required for multi-key commands that operate on a single Cluster slot.

#Verify topology

Run health commands from a ready data Pod or an authenticated client endpoint:

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

Confirm cluster_state:ok, full slot assignment, expected primary and replica counts, and reachable advertised addresses.

#Use 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

The generated server requires a trusted client certificate by default. The bootstrap name valkey-cluster.default is in the generated certificate for this example; the .svc form is not. This command proves only that the bootstrap connection can authenticate.

The Cluster announces generated per-Pod Service addresses for node connections, but the generated certificate does not include those Service names or addresses. Consequently, a client that performs normal hostname verification can fail after MOVED or ASK, even when bootstrap PING succeeds. Treat this as an unresolved 2.0.0 Cluster TLS limitation. Require a delivered build that aligns every announced endpoint with a certificate subject alternative name, and test a key on every shard. Do not use --insecure as the workaround.

#External access

Cluster external access creates per-Pod Services so the advertised topology can route clients directly to the correct node. Discover all generated Services:

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

For LoadBalancer, wait until every required per-Pod Service has an ingress address. For NodePort, ensure the client can reach the selected node addresses and all allocated ports. A single reachable bootstrap endpoint is insufficient if redirected node endpoints are blocked.

The generated certificate also does not cover arbitrary external addresses, so the Cluster TLS limitation above applies to external access as well as the in-cluster announced topology.

Leave spec.access.ports unset for 2.0.0 unless the delivered build documents a validated fixed-port format. Kubernetes then allocates NodePorts.

#Application-client requirements

• Configure more than one bootstrap endpoint when the client library supports it.
• Enable topology refresh and MOVED/ASK handling.
• Use bounded connection, command, and retry timeouts.
• Confirm DNS, routes, firewall rules, TLS names, and network policies for every advertised node.
• Keep multi-key operations within one hash slot or redesign the operation.
• Revalidate topology behavior after scaling, failover, access changes, or certificate rotation.

Cluster replication is asynchronous, and the protocol permits acknowledged write loss in documented failure windows. See the official Cluster specification, CLUSTER SHARDS reference, TLS documentation, and client catalog. Verify the selected library's behavior in its own documentation and tests.