How Clients Discover a Valkey Cluster: CLUSTER SLOTS vs SHARDS vs NODES, NAT and TLS Ports

A Valkey Cluster client does not ask a proxy where a key lives. It downloads the slot map from one node, caches it, and corrects it when a node answers -MOVED 1649 10.0.1.13:6379. Whatever address a node publishes in that map is the address your application dials. Behind NAT, in Kubernetes, or on a TLS-only cluster, that address is often wrong: a private pod IP, port 0, a ? endpoint, or a plaintext port handed to a TLS client. The errors show up in the client, as go-redis logging dial tcp <ip>:0: connection refused or GLIDE returning AllConnectionsUnavailable. This guide covers Valkey 8.0 to 9.1.3: what CLUSTER SLOTS, CLUSTER SHARDS and CLUSTER NODES return, which client reads which, and the cluster-announce-* settings that control the answer.

Scope and review date: November 2026. This post covers self-managed Valkey Cluster 8.0 to 9.1.3 (released 26 October 2026) and the client versions named in the text. Behaviour was checked on 10 November 2026 against the valkey.io command pages, the release notes, and the server and client source at the tags named. Commands were not run in a lab, so rehearse them on staging.

How does a Valkey cluster client build and refresh its slot map?

The Valkey Cluster specification says clients fetch the full slot map at startup and when they receive a MOVED redirection. It recommends reloading the whole map rather than one slot, because a failover remaps every slot the old primary served at once.

A MOVED reply carries the slot and the owner's endpoint and port. The endpoint can be an IP, a hostname, or empty (-MOVED 3999 :6380), meaning "same host, this port". An ASK reply is a one-off redirect during slot migration: the client sends ASKING and the command to the target and leaves its map alone.

# Which slot does the key hash to, and who answers for it?
valkey-cli -h 10.0.1.11 -p 6379 CLUSTER KEYSLOT user:1000
# (integer) 1649

# Without -c, valkey-cli shows the redirect instead of following it
valkey-cli -h 10.0.1.11 -p 6379 GET user:1000
# (error) MOVED 1649 10.0.1.13:6379

Interpretation: the slot is fixed by the key (CRC16 of user:1000 modulo 16384 is 1649). The address after it is what the answering node announces for the owner. If the application cannot reach that address, the redirect leads nowhere, even though the seed address works.

What do CLUSTER SLOTS, CLUSTER SHARDS and CLUSTER NODES return?

All three describe the cluster from the answering node's view. CLUSTER SLOTS returns slot ranges, each with a primary and replicas as arrays of endpoint, port, node ID and a metadata map. CLUSTER SHARDS (since 7.0) returns one map per shard, with a map per node that includes health and replication-offset. CLUSTER NODES returns one text line per node, and its page says clients should normally use CLUSTER SLOTS instead. Valkey 9.1.0 added availability-zone to SLOTS and SHARDS and a shard id to SHARDS.

# The same cluster, three views. --json uses RESP3, so SHARDS maps become objects.
valkey-cli -h 10.0.1.11 -p 6379 --json CLUSTER SLOTS \
  | jq -c '.[] | [.[0], .[1], .[2][0], .[2][1]]'
valkey-cli -h 10.0.1.11 -p 6379 --json CLUSTER SHARDS \
  | jq -c '.[].nodes[] | [.endpoint, .ip, .port, ."tls-port", .health]'
valkey-cli -h 10.0.1.11 -p 6379 CLUSTER NODES | awk '{print $2, $3}'

Interpretation: the first query prints each slot range with its primary's endpoint and port. The second prints what a SHARDS client will dial, including failed or loading nodes. The third prints the address and flags column that Lettuce parses. If the three disagree on a node's address, your client libraries will disagree too.

Which topology command does each client library use?

The three replies treat hostnames, failed nodes and TLS ports differently, so one cluster can work for one service and fail for another. This table comes from each client's source at the tag shown.

The valkey-go rule is in cluster.go: useShards := v >= 8 || (preferShards && v >= 7). With extended-redis-compatibility yes the server reports 7.2.4, so valkey-go falls back to SLOTS. The StackExchange.Redis 3.2.0 notes record its move to SLOTS. Direct ClusterShards() calls in go-redis 9.20.0 and earlier break on the 9.1 shard id; see the changes that break Valkey client libraries.

How does cluster-preferred-endpoint-type change the address clients get?

cluster-preferred-endpoint-type takes ip (the default), hostname or unknown-endpoint. It sets the endpoint in CLUSTER SLOTS, CLUSTER SHARDS, MOVED and ASK, but not in CLUSTER NODES.

• hostname: clients get cluster-announce-hostname. A node without one returns ?, which clients should treat as an unknown node. valkey-go and GLIDE drop such nodes.
• unknown-endpoint: CLUSTER SLOTS returns null, telling the client to reuse the host it just used, with the returned port. It suits nodes behind a load balancer. In the 9.1.3 source, SHARDS and MOVED send an empty string here, though the SHARDS page says NULL.

# The setting is per node, and each node formats its own replies.
for h in 10.0.1.11 10.0.1.12 10.0.1.13; do
  printf '%s ' "$h"
  valkey-cli -h "$h" -p 6379 CONFIG GET cluster-preferred-endpoint-type | tail -1
done

Interpretation: every node must print the same value, or a client refreshing from a different node gets IPs from one and hostnames from another. The setting is modifiable at runtime and clears the cached SLOTS reply. Set a hostname on every node before switching to hostname.

Which cluster-announce settings control what clients see?

A node publishes its addresses over the cluster bus, and the other nodes repeat them to clients. The 9.1.3 valkey.conf lists the overrides under "CLUSTER DOCKER/NAT support". All are modifiable at runtime.

PR #2429 added the client ports so that clients "always get to see the configured port", while bus traffic keeps the non-client values. They travel in new ping extensions, so set them only once every node runs 9.0 or later.

# What does this node announce? CONFIG GET accepts glob patterns.
valkey-cli -h 10.0.1.11 -p 6379 CONFIG GET 'cluster-announce-*'

Interpretation: empty strings and zero ports mean "use what the node detects". In the 9.1.3 source the client IP depends only on the connection's address family, so a node shows one IPv4 and one IPv6 address to all clients, not one per network.

How do you set announce addresses behind NAT or in Kubernetes?

Nodes need addresses for each other on the bus, and clients need addresses they can reach. Inside one Kubernetes cluster both can be the pod IP. Outside clients, or per-node load balancers, need the client-only settings. The bus connects by IP, so a hostname helps clients (for example with certificate checks) but not nodes.

# StatefulSet container excerpt: announce the pod IP and a stable DNS name
env:
  - name: POD_IP
    valueFrom:
      fieldRef:
        fieldPath: status.podIP
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
command: ["valkey-server"]
args:
  - /etc/valkey/valkey.conf
  - --cluster-announce-ip
  - $(POD_IP)
  - --cluster-announce-hostname
  - $(POD_NAME).valkey-hl.prod.svc.cluster.local

Interpretation: Kubernetes expands $(POD_IP) and $(POD_NAME) in args, and valkey-server accepts config directives as --name value after the config file. A headless Service (here valkey-hl) makes each name resolve to its pod. An operator may already set these; see Valkey and Redis operators for Kubernetes compared.

Why do clients get the wrong port on a TLS cluster?

The server picks the port by the protocol of the connection it sees. In the 9.1.3 cluster.c, shouldReturnTlsInfo() returns connIsTLS() for the caller, and SLOTS, NODES, MOVED and ASK report TLS ports only to TLS clients. That causes three common faults:

• TLS terminated in front of Valkey. The node sees plaintext and hands out plaintext ports, which the application then dials with TLS. Announce the proxy's port with cluster-announce-client-port.
• A SHARDS parser that reads only port. TLS-only nodes have no port, and with both open a TLS client dials the plaintext listener. valkey-go picks tls-port; Lettuce 7.9.0's SHARDS parser reads only port, though its default refresh uses NODES.
• Only cluster-announce-port set on a TLS cluster. See below.

# Same node, two protocols: the ports in the replies should differ
valkey-cli -h 10.0.1.11 -p 6379 --json CLUSTER SLOTS | jq -c '.[0][2][0:2]'
valkey-cli --tls --cacert ca.crt -h 10.0.1.11 -p 6380 --json CLUSTER SLOTS \
  | jq -c '.[0][2][0:2]'

Interpretation: plaintext should return plaintext ports and TLS should return TLS ports. An internal TLS port where you expected the NAT-mapped one means cluster-announce-tls-port is missing. 9.0.0-rc1 also fixed "CLUSTER SLOTS/NODES showing wrong port after updating port/tls-port" (#2186), so on 8.x restart a node after changing those at runtime.

What do topology problems look like in the client?

Most of these appear after the first connection succeeds, because the seed address is reachable and the announced ones are not.

The go-redis port 0 bug affected PubSub on TLS-only clusters from v9.18.0, per the v9.20.0 notes. Announcing a hostname also changes Lettuce and GLIDE even with the endpoint type left at ip, so make sure it resolves everywhere first. For zone labels, see multi-AZ Valkey placement and zone-aware clients.

How do you test topology discovery for each client?

Test from the application network, over its protocol, against every node. The SLOTS page says the reply is deterministic across nodes, so identical replies mean one shared view.

# 1. Every node should give the same CLUSTER SLOTS reply
for h in 10.0.1.11 10.0.1.12 10.0.1.13 10.0.1.14 10.0.1.15 10.0.1.16; do
  printf '%s ' "$h"
  valkey-cli --tls --cacert ca.crt -h "$h" -p 6380 CLUSTER SLOTS | md5sum
done

# 2. Every advertised endpoint must answer PING over the same protocol
valkey-cli --tls --cacert ca.crt -h 10.0.1.11 -p 6380 --json CLUSTER SLOTS \
  | jq -r '.[] | .[2:][] | "\(.[0]) \(.[1])"' | sort -u \
  | while read -r host port; do
      printf '%s:%s ' "$host" "$port"
      valkey-cli --tls --cacert ca.crt -h "$host" -p "$port" PING
    done

Interpretation: step 1 passes with one checksum for all nodes; a different one points to a node with another endpoint type or announce setting. In step 2 every line must end in PONG. Then, on staging, run CLUSTER FAILOVER on a replica and check each client:

• go-redis: the ClusterClient reloads after the failover; PubSub works on TLS-only clusters (v9.20.0 or later).
• valkey-go: it dials tls-port on TLS, and still uses SHARDS unless compatibility mode is on.
• Lettuce: announced hostnames resolve; on 6.x, enable adaptive refresh triggers (7.0 enables them by default).
• Remap users (redis-py, valkey-py, ioredis, iovalkey): the new primary's address is in the remap.
• GLIDE and StackExchange.Redis: GLIDE is past the empty-hostname fix; StackExchange.Redis is retested after moving to 3.2.0 or later.

Frequently asked questions

Key takeaways

Review Valkey cluster connectivity with JusDB

JusDB's Valkey Cluster team can review your announce settings, endpoint types and TLS ports against the client libraries your services use, plan the changes node by node, and run the discovery and failover tests above on staging.

Bring your Valkey versions, network layout, TLS setup and client library inventory. Your team approves every production change.

Related reading

• Valkey performance tuning: memory, persistence, and cluster config
• Redis Cluster: data sharding, replication, and high availability
• Valkey and Redis operators for Kubernetes compared
• Valkey documentation: Cluster specification