`CLUSTER NODES` ignores `ClusterPreferredEndpointType=hostname` and still returns worker bind addresses

[nixxcz]

When using --cluster-announce-hostname together with --cluster-preferred-endpoint-type hostname, Garnet only partially switches cluster metadata to the external client-facing endpoint.

CLUSTER SLOTS and redirection behavior can prefer the announced hostname, but CLUSTER NODES still returns the internal bind or Docker bridge address as the primary node address. From code inspection, CLUSTER SHARDS appears to use the same raw worker address path.

Environment

• Garnet image: ghcr.io/microsoft/garnet:1.1.1
• Two-node cluster in Docker bridge mode
• Nodes listen on the same ports that are published to the host
• Host-reachable client endpoints: 10.20.22.211:17000 and 10.20.22.211:17001
• Garnet started with:
  • --cluster
  • --aof
  • --bind 0.0.0.0
  • --port <published-port>
  • --cluster-announce-hostname 10.20.22.211
  • --cluster-preferred-endpoint-type hostname

Reproduction

1. Start two Garnet nodes in Docker bridge mode.
2. Publish their ports to the host and set --cluster-announce-hostname to a host-reachable address or hostname.
3. Set --cluster-preferred-endpoint-type hostname.
4. Form a cluster and connect from outside the Docker network using the published host endpoints.
5. Run CLUSTER NODES.

Actual behavior

Observed CLUSTER NODES output:

0342309892aa1c7b5d0cdde9f8e92bf1af0f96c0 172.18.0.2:17000@27000,10.20.22.211 myself,master - 0 0 16 connected 0-16383
ad13485b48e14bc16dd3b0653e1401a5d3bb970f 172.18.0.3:17001@27001,10.20.22.211 slave 0342309892aa1c7b5d0cdde9f8e92bf1af0f96c0 639104637187557405 639104637187553617 17 connected

Observed related replication output from the same cluster:

slave0:ip=172.18.0.3,port=17001,state=online,offset=64,lag=0

So even though clients are expected to use 10.20.22.211:17000 and 10.20.22.211:17001, CLUSTER NODES still serializes 172.18.0.2 and 172.18.0.3 as the primary node addresses and only appends the announced host after the comma.

From source inspection, CLUSTER SHARDS also appears to build its address field from workers[workerId].Address, so this likely affects CLUSTER SHARDS as well.

Expected behavior

One of these outcomes would solve the problem:

1. CLUSTER NODES and CLUSTER SHARDS honor ClusterPreferredEndpointType and expose the announced hostname or preferred external endpoint as the primary address.
2. Garnet provides an explicit configuration option that makes these commands emit the announced external endpoint instead of the internal worker bind address.
3. If the raw bind address must remain for compatibility, Garnet provides a separate cluster metadata view that is consistent with CLUSTER SLOTS and redirection responses.

Why this matters

• External diagnostics become misleading because the primary address reported by CLUSTER NODES is not reachable from the host.
• Cluster-aware clients or topology probes may still attempt side connections to the internal Docker address even when the configured seed endpoints are correct.
• Control planes and dashboards have to special-case internal Docker addresses instead of relying on Garnet's own cluster metadata.

Relevant code references

• GetEndpointByPreferredType(...) is where preferred endpoint selection is implemented for slot or redirect-style endpoint paths:
  • https://github.com/microsoft/garnet/blob/main/libs/cluster/Server/ClusterConfig.cs#L479-L489
• GetNodeInfo(...) currently emits workers[workerId].Address as the leading ip:port@cport field in CLUSTER NODES, and only appends hostname metadata after the comma:
  • https://github.com/microsoft/garnet/blob/main/libs/cluster/Server/ClusterConfig.cs#L543-L552
• GetSlotsInfo(...) routes through the preferred-endpoint path for CLUSTER SLOTS:
  • https://github.com/microsoft/garnet/blob/main/libs/cluster/Server/ClusterConfig.cs#L735-L807
  • https://github.com/microsoft/garnet/blob/main/libs/cluster/Server/ClusterConfig.cs#L838-L858
• GetShardsInfo(...) appears to serialize the address field from workers[workerId].Address as well:
  • https://github.com/microsoft/garnet/blob/main/libs/cluster/Server/ClusterConfig.cs#L684-L715

Related issues checked

I checked these before filing, and they look related but not duplicates:

• #1446 added --cluster-announce-hostname and hostname-preferred endpoint support for client-facing behavior such as CLUSTER SLOTS and redirections.
• #640 fixed stale announce data after node movement or recovery.
• #1561 fixed hostname handling for MIGRATE and automatic slot migration.
• #931 fixed consistency issues between CLUSTER NODES and CLUSTER REPLICAS.

This issue appears to be a remaining metadata-selection gap specifically in CLUSTER NODES, and likely CLUSTER SHARDS, after the earlier hostname work.

Additional notes

I can provide a minimal two-container repro or sanitized capture files if that would help validate the behavior quickly.

[vazois]

In my opinion redis has messed this up because hostnames were an afterthought.
A quick search indicates that only newer APIs adhere to the preferred-endpoint-type (i.e. CLUSTER SHARDS). CLUSTER SLOTS and CLUSTER NODES are part of legacy API, so hostname support is additive, not substitutive.
To control cluster slots and cluster nodes advertised ip, you have to use --cluster-announce-ip option.
The --cluster-preferred-endpoint-type, controls the ordering in which the information is presented in the cluster slots and cluster shards options but leaves the ordering fixed for cluster nodes.
See below, what I am getting with redis 7.0.15.

• [redis-server --cluster-enabled yes --bind 0.0.0.0]
  $ redis-cli cluster nodes
  c9b52b88c01a22e3cd1ef329762239e001478ea2 :6379@16379 myself,master - 0 0 0 connected 0-16383
  $ redis-cli cluster slots

1. 1. (integer) 0
   2. (integer) 16383
   3. 1. ""
      2. (integer) 6379
      3. "c9b52b88c01a22e3cd1ef329762239e001478ea2"
      4. (empty array)
         $ redis-cli cluster shards
2. 1. "slots"
   2. 1. (integer) 0
      2. (integer) 16383
   3. "nodes"
   4. 1. 1. "id"
         2. "c9b52b88c01a22e3cd1ef329762239e001478ea2"
         3. "port"
         4. (integer) 6379
         5. "ip"
         6. ""
         7. "endpoint"
         8. ""
         9. "role"
      2. "master"
      3. "replication-offset"
      4. (integer) 0
      5. "health"
      6. "online"

• [redis-server --cluster-enabled yes --bind 0.0.0.0 --cluster-announce-ip 127.0.0.1]
  $ redis-cli cluster nodes
  c9b52b88c01a22e3cd1ef329762239e001478ea2 127.0.0.1:6379@16379 myself,master - 0 0 0 connected 0-16383
  $ redis-cli cluster slots

1. 1. (integer) 0
   2. (integer) 16383
   3. 1. "127.0.0.1"
      2. (integer) 6379
      3. "c9b52b88c01a22e3cd1ef329762239e001478ea2"
      4. (empty array)
         $ redis-cli cluster shards
2. 1. "slots"
   2. 1. (integer) 0
      2. (integer) 16383
   3. "nodes"
   4. 1. 1. "id"
         2. "c9b52b88c01a22e3cd1ef329762239e001478ea2"
         3. "port"
         4. (integer) 6379
         5. "ip"
         6. "127.0.0.1"
         7. "endpoint"
         8. "127.0.0.1"
         9. "role"
      2. "master"
      3. "replication-offset"
      4. (integer) 0
      5. "health"
      6. "online"

• [redis-server --cluster-enabled yes --bind 0.0.0.0 --cluster-announce-ip 127.0.0.1 --cluster-announce-hostname customhost]
  $ redis-cli cluster nodes
  c9b52b88c01a22e3cd1ef329762239e001478ea2 127.0.0.1:6379@16379,customhost myself,master - 0 0 0 connected 0-16383
  $ redis-cli cluster slots

1. 1. (integer) 0
   2. (integer) 16383
   3. 1. "127.0.0.1"
      2. (integer) 6379
      3. "c9b52b88c01a22e3cd1ef329762239e001478ea2"
      4. 1. "hostname"
         2. "customhost"
            $ redis-cli cluster shards
2. 1. "slots"
   2. 1. (integer) 0
      2. (integer) 16383
   3. "nodes"
   4. 1. 1. "id"
         2. "c9b52b88c01a22e3cd1ef329762239e001478ea2"
         3. "port"
         4. (integer) 6379
         5. "ip"
         6. "127.0.0.1"
         7. "endpoint"
         8. "127.0.0.1"
         9. "hostname"
      2. "customhost"
      3. "role"
      4. "master"
      5. "replication-offset"
      6. (integer) 0
      7. "health"
      8. "online"

• [redis-server --cluster-enabled yes --bind 0.0.0.0 --cluster-announce-ip 127.0.0.1 --cluster-announce-hostname customhost --cluster-preferred-endpoint-type hostname]
  $ redis-cli cluster nodes
  c9b52b88c01a22e3cd1ef329762239e001478ea2 127.0.0.1:6379@16379,customhost myself,master - 0 0 0 connected 0-16383
  $ redis-cli cluster slots

1. 1. (integer) 0
   2. (integer) 16383
   3. 1. "customhost"
      2. (integer) 6379
      3. "c9b52b88c01a22e3cd1ef329762239e001478ea2"
      4. 1. "ip"
         2. "127.0.0.1"
            $ redis-cli cluster shards
2. 1. "slots"
   2. 1. (integer) 0
      2. (integer) 16383
   3. "nodes"
   4. 1. 1. "id"
         2. "c9b52b88c01a22e3cd1ef329762239e001478ea2"
         3. "port"
         4. (integer) 6379
         5. "ip"
         6. "127.0.0.1"
         7. "endpoint"
         8. "customhost"
         9. "hostname"
      2. "customhost"
      3. "role"
      4. "master"
      5. "replication-offset"
      6. (integer) 0
      7. "health"
      8. "online"

I think what we are missing is the slots and shards ordering.
For your use-case you might benefit from the --cluster-announce-ip option.

[copilot-swe-agent]

The agent encountered an error and was unable to start working on this issue: Before you can use Copilot coding agent, you need to pick a "Usage billed to" option in your Copilot settings. Update your settings, then try again. (Request id: 1EF8:3338F4:172B0BB:1749381:69CC12B4)