Skip to content

[Core] Bind gRPC servers to the node address family - #65867

Open
400Ping wants to merge 2 commits into
ray-project:masterfrom
400Ping:fix/ipv6-grpc-bind-family
Open

[Core] Bind gRPC servers to the node address family#65867
400Ping wants to merge 2 commits into
ray-project:masterfrom
400Ping:fix/ipv6-grpc-bind-family

Conversation

@400Ping

@400Ping 400Ping commented Sep 2, 2026

Copy link
Copy Markdown
Member

Description

This PR allows Ray's core gRPC servers to bind using the address family of the
node's advertised IP address.

Previously, ray start --node-ip-address=<IPv6 address> advertised an IPv6
node address, but GrpcServer selected its wildcard bind address from the
system's localhost resolution. On IPv4-first systems, this caused the server
to listen on 0.0.0.0 even when the Ray node advertised an IPv6 address.

As a result, an IPv6-only worker could attempt to connect to the GCS through
IPv6 while the GCS was only listening on an IPv4 socket.

The new bind behavior is:

Advertised node address gRPC bind address
localhost Resolved localhost address
127.0.0.1 127.0.0.1
::1 ::1
Non-loopback IPv4 0.0.0.0
Non-loopback IPv6 ::

Changes

  • Select the gRPC wildcard bind address from the advertised node IP:
    • IPv4 → 0.0.0.0
    • IPv6 → ::
    • Loopback addresses remain local-only.
  • Apply the address-family-aware binding to GCS, NodeManager, ObjectManager,
    CoreWorker, and the dashboard agent.
  • Add IPv4/IPv6 mapping tests and an IPv6 gRPC connectivity test.
  • Skip the IPv6 socket test safely when the test environment does not support
    IPv6.
  • Log the complete gRPC bind address with the actual dynamically allocated
    port.

Related issues

Related to
#54660
ray-project/kuberay#5215

Additional information

Signed-off-by: 400Ping <jiekaichang@apache.org>
@400Ping 400Ping self-assigned this Sep 2, 2026
@400Ping 400Ping added the core Issues that should be addressed in Ray Core label Sep 2, 2026
Signed-off-by: 400Ping <jiekaichang@apache.org>
@400Ping
400Ping marked this pull request as ready for review September 3, 2026 01:06
@400Ping
400Ping requested review from a team, MengjinYan and edoakes as code owners September 3, 2026 01:06

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates Ray's gRPC server binding logic to accept a node_ip_address string instead of a boolean flag, allowing servers to dynamically bind to the correct wildcard address (0.0.0.0 or ::) matching the node's address family. This change is integrated across both C++ and Python/Cython layers. Feedback on these changes includes simplifying the IsIpv6LoopbackAvailable test helper to avoid a full TCP handshake, passing node_ip_address by const std::string & in the GrpcServer constructor to prevent unnecessary string copies, and removing the Optional[str] type hint in Cython to avoid a potential runtime NameError.

Comment thread src/ray/rpc/tests/grpc_server_client_test.cc
Comment thread src/ray/rpc/grpc_server.h
Comment thread src/ray/rpc/grpc_server.cc
Comment thread python/ray/includes/network_util.pxi

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

Fix All in Cursor

Reviewed by Cursor Bugbot for commit ac759e2. Configure here.

if is_localhost(node_ip_address)
else get_all_interfaces_ip(node_ip_address)
)
return build_address(grpc_ip, grpc_port)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dashboard agent ignores loopback family

Medium Severity

_build_grpc_address maps every localhost value through get_localhost_ip(), so 127.0.0.1 and ::1 follow the system's localhost family instead of the advertised address. Core gRPC servers keep the literal loopback address, so an IPv6-localhost node can leave the dashboard agent listening on IPv4 loopback while clients connect to ::1.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit ac759e2. Configure here.

Comment thread src/ray/rpc/grpc_server.h

/// Internal helper that returns the address on which a gRPC server should listen for a
/// Ray node address. This is not a public networking API.
std::string GetGrpcServerBindAddress(const std::string &node_ip_address);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing Doxygen on bind helper

Low Severity

⚠️ Document functions and classes with Doxygen /** ... */ block comments using @ tags (@brief, and @param/@return where applicable). Newly added GetGrpcServerBindAddress has only a brief /// comment and omits @brief, @param, and @return.

Fix in Cursor Fix in Web

Triggered by project rule: Bugbot Rules

Reviewed by Cursor Bugbot for commit ac759e2. Configure here.

@machichima

Copy link
Copy Markdown
Contributor

cc @Yicheng-Lu-llll

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core Issues that should be addressed in Ray Core

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants