[Core]Separate Environment Variables for ray.init() and ray ctl to Reflect Different Protocols and Ports #55189

machichima · 2025-08-04T08:40:10Z

Why are these changes needed?

Currently, both ray.init() and ray ctl rely on the same environment variable RAY_ADDRESS to determine the default address to connect to a Ray cluster. However, in practice:

ray.init() uses the ray:// protocol and connects via the GCS gRPC port (default 10001)
ray ctl uses the HTTP protocol (http://) and connects via the Dashboard port (default 8265)
This leads to potential confusion when setting the RAY_ADDRESS environment variable, as it may not be valid for both tools simultaneously. For example, setting RAY_ADDRESS=http://localhost:8265/ would work for ray ctl, but not for ray.init(), which expects a ray:// URI with the GCS port.

In this PR, we do:

Keep RAY_ADDRESS for ray.init()
Use RAY_API_SERVER_ADDRESS for ray job ctl
Update docs: https://anyscale-ray--55189.com.readthedocs.build/en/55189/cluster/running-applications/job-submission/quickstart.html

Result Screenshot:

Related issue number

Closes #53226

Checks

I've signed off every commit(by using the -s flag, i.e., git commit -s) in this PR.
I've run scripts/format.sh to lint the changes in this PR.
I've included any doc changes needed for https://docs.ray.io/en/master/.
- I've added any new APIs to the API Reference. For example, if I added a
  method in Tune, I've added it in doc/source/tune/api/ under the
  corresponding .rst file.
I've made sure the tests are passing. Note that there might be a few flaky tests, see the recent failures at https://flakey-tests.ray.io/
Testing Strategy
- Unit tests
- Release tests
- This PR is not tested :(

gemini-code-assist

Summary of Changes

Hello @machichima, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

I've addressed a potential source of confusion in Ray's environment variable usage. Previously, both ray.init() and ray ctl relied on the single RAY_ADDRESS environment variable, despite connecting to different services (GCS gRPC for ray.init() and Dashboard HTTP for ray ctl) with different protocols and default ports. To resolve this, I've introduced RAY_API_SERVER_ADDRESS specifically for ray ctl connections, allowing RAY_ADDRESS to remain dedicated to ray.init(). This change clarifies the intended use of each environment variable, making it easier for users to configure their Ray cluster connections correctly without conflicts.

Highlights

New Environment Variable: I've introduced a new environment variable, RAY_API_SERVER_ADDRESS, to specifically designate the address for connecting to the Ray API server, which is primarily used by ray ctl.
CLI Updates for ray ctl: I've updated the command-line interface for ray ctl to inform users about the new RAY_API_SERVER_ADDRESS and ensure that it is prioritized for connection addresses, while still maintaining backward compatibility by falling back to RAY_ADDRESS if the new variable is not set.
Internal Logic and Documentation Alignment: I've modified the internal logic and documentation within the Ray dashboard utilities and SDK to reflect this new precedence, ensuring that ray.init() continues to correctly use RAY_ADDRESS for GCS connections, while ray ctl leverages the new variable for the dashboard API.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments or fill out our survey to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a new environment variable, RAY_API_SERVER_ADDRESS, for ray ctl commands to distinguish it from RAY_ADDRESS used by ray.init(). This change effectively resolves potential confusion between the different protocols and ports used by these tools. The implementation correctly includes fallback logic to RAY_ADDRESS for backward compatibility, and all related documentation and help messages have been updated accordingly. I have one suggestion to improve code quality by avoiding redundant lookups of environment variables.

gemini-code-assist · 2025-08-04T08:45:18Z

python/ray/dashboard/utils.py

+    if os.environ.get("RAY_API_SERVER_ADDRESS"):
+        logger.debug(f"Using RAY_API_SERVER_ADDRESS={os.environ['RAY_API_SERVER_ADDRESS']}")
+        address = os.environ["RAY_API_SERVER_ADDRESS"]
+    # Fall back to RAY_ADDRESS if RAY_API_SERVER_ADDRESS not set
+    elif os.environ.get("RAY_ADDRESS"):
        logger.debug(f"Using RAY_ADDRESS={os.environ['RAY_ADDRESS']}")
        address = os.environ["RAY_ADDRESS"]


To improve performance and readability, you can use the walrus operator := (available in Python 3.8+) to avoid multiple lookups for the same environment variable.

Suggested change

if os.environ.get("RAY_API_SERVER_ADDRESS"):

logger.debug(f"Using RAY_API_SERVER_ADDRESS={os.environ['RAY_API_SERVER_ADDRESS']}")

address = os.environ["RAY_API_SERVER_ADDRESS"]

# Fall back to RAY_ADDRESS if RAY_API_SERVER_ADDRESS not set

elif os.environ.get("RAY_ADDRESS"):

logger.debug(f"Using RAY_ADDRESS={os.environ['RAY_ADDRESS']}")

address = os.environ["RAY_ADDRESS"]

if api_server_address := os.environ.get("RAY_API_SERVER_ADDRESS"):

logger.debug(f"Using RAY_API_SERVER_ADDRESS={api_server_address}")

address = api_server_address

# Fall back to RAY_ADDRESS if RAY_API_SERVER_ADDRESS not set

elif ray_address := os.environ.get("RAY_ADDRESS"):

logger.debug(f"Using RAY_ADDRESS={ray_address}")

address = ray_address

rueian · 2025-08-07T03:54:35Z

python/ray/dashboard/utils.py

+    # Fall back to RAY_ADDRESS if RAY_API_SERVER_ADDRESS not set
+    elif ray_address := os.environ.get(ray_constants.RAY_ADDRESS_ENVIRONMENT_VARIABLE):
+        address = ray_address
+        logger.debug(f"Using RAY_ADDRESS={address}")


I think we need a test at class TestRayAddress.

No problem! Added test in 9e8764c

rueian · 2025-08-07T03:59:59Z

We may also need to change the usage hint:

and relevant test_cli_patterns files, such as:

machichima · 2025-08-08T02:15:39Z

We may also need to change the usage hint and relevant test_cli_patterns files

Thanks for point these out! Updated in 5d656e9

owenowenisme

LG

edoakes

Looks good overall

edoakes · 2025-08-08T21:31:54Z

python/ray/dashboard/modules/job/tests/test_cli_integration.py

+        ray_api_server_address: str,
+        should_fail: bool,
+    ):
+        # Always use problematic client address to ensure


what is "problematic client address"?

It means the wrong RAY_ADDRESS format (which we name RAY_ADDRESS as ray_client_address)

If the job cli use this address, it will surely fail. I use this to ensure job cli is dominated by RAY_API_SERVER_ADDRESS

I see. maybe we can make this more clear in the comment, like:

# Set a `RAY_ADDRESS` that would not work with the `ray job submit` CLI because it uses the `ray://` prefix. # This verifies that the `RAY_API_SERVER_ADDRESS` env var takes precedence.

Thank you! Updated the comment in 79a50d0

edoakes · 2025-08-08T21:32:17Z

python/ray/dashboard/modules/job/tests/test_cli_integration.py

            assert "hello" in stdout
            assert "succeeded" in stdout

    @pytest.mark.parametrize(


If there are other existing PRs that use RAY_ADDRESS, could you please make sure to update them as well?

Sure! Do you mean opening some follow-up PR for other existing ones to change RAY_ADDRESS to RAY_API_SERVER_ADDRESS if related to ray job cli?

yes that's right

No problem!

-e Signed-off-by: machichima <[email protected]>

edoakes · 2025-08-11T15:17:51Z

Started CI tests & one minor nit, please ping me when tests pass!

-e Signed-off-by: machichima <[email protected]>

edoakes · 2025-08-12T00:42:35Z

Thanks @machichima!

…flect Different Protocols and Ports (#55189) Currently, both `ray.init()` and ray ctl rely on the same environment variable RAY_ADDRESS to determine the default address to connect to a Ray cluster. However, in practice: `ray.init()` uses the `ray:// protocol` and connects via the GCS gRPC port (default `10001`) ray ctl uses the HTTP protocol (`http://`) and connects via the Dashboard port (default `8265`) This leads to potential confusion when setting the `RAY_ADDRESS` environment variable, as it may not be valid for both tools simultaneously. For example, setting `RAY_ADDRESS=http://localhost:8265/` would work for ray ctl, but not for `ray.init()`, which expects a `ray://` URI with the GCS port. In this PR, we do: - Keep `RAY_ADDRESS` for `ray.init()` - Use `RAY_API_SERVER_ADDRESS` for ray job ctl - Update docs: https://anyscale-ray--55189.com.readthedocs.build/en/55189/cluster/running-applications/job-submission/quickstart.html Closes #53226 Signed-off-by: sampan <[email protected]>

…flect Different Protocols and Ports (ray-project#55189) Currently, both `ray.init()` and ray ctl rely on the same environment variable RAY_ADDRESS to determine the default address to connect to a Ray cluster. However, in practice: `ray.init()` uses the `ray:// protocol` and connects via the GCS gRPC port (default `10001`) ray ctl uses the HTTP protocol (`http://`) and connects via the Dashboard port (default `8265`) This leads to potential confusion when setting the `RAY_ADDRESS` environment variable, as it may not be valid for both tools simultaneously. For example, setting `RAY_ADDRESS=http://localhost:8265/` would work for ray ctl, but not for `ray.init()`, which expects a `ray://` URI with the GCS port. In this PR, we do: - Keep `RAY_ADDRESS` for `ray.init()` - Use `RAY_API_SERVER_ADDRESS` for ray job ctl - Update docs: https://anyscale-ray--55189.com.readthedocs.build/en/55189/cluster/running-applications/job-submission/quickstart.html Closes ray-project#53226 Signed-off-by: Andrew Grosser <[email protected]>

…flect Different Protocols and Ports (ray-project#55189) Currently, both `ray.init()` and ray ctl rely on the same environment variable RAY_ADDRESS to determine the default address to connect to a Ray cluster. However, in practice: `ray.init()` uses the `ray:// protocol` and connects via the GCS gRPC port (default `10001`) ray ctl uses the HTTP protocol (`http://`) and connects via the Dashboard port (default `8265`) This leads to potential confusion when setting the `RAY_ADDRESS` environment variable, as it may not be valid for both tools simultaneously. For example, setting `RAY_ADDRESS=http://localhost:8265/` would work for ray ctl, but not for `ray.init()`, which expects a `ray://` URI with the GCS port. In this PR, we do: - Keep `RAY_ADDRESS` for `ray.init()` - Use `RAY_API_SERVER_ADDRESS` for ray job ctl - Update docs: https://anyscale-ray--55189.com.readthedocs.build/en/55189/cluster/running-applications/job-submission/quickstart.html Closes ray-project#53226 Signed-off-by: jugalshah291 <[email protected]>

…flect Different Protocols and Ports (#55189) Currently, both `ray.init()` and ray ctl rely on the same environment variable RAY_ADDRESS to determine the default address to connect to a Ray cluster. However, in practice: `ray.init()` uses the `ray:// protocol` and connects via the GCS gRPC port (default `10001`) ray ctl uses the HTTP protocol (`http://`) and connects via the Dashboard port (default `8265`) This leads to potential confusion when setting the `RAY_ADDRESS` environment variable, as it may not be valid for both tools simultaneously. For example, setting `RAY_ADDRESS=http://localhost:8265/` would work for ray ctl, but not for `ray.init()`, which expects a `ray://` URI with the GCS port. In this PR, we do: - Keep `RAY_ADDRESS` for `ray.init()` - Use `RAY_API_SERVER_ADDRESS` for ray job ctl - Update docs: https://anyscale-ray--55189.com.readthedocs.build/en/55189/cluster/running-applications/job-submission/quickstart.html Closes #53226 Signed-off-by: Douglas Strodtman <[email protected]>

gemini-code-assist bot reviewed Aug 4, 2025

View reviewed changes

machichima force-pushed the 53226-env-var-for-ray-ctl branch from c131ad0 to 1270db9 Compare August 4, 2025 08:40

gemini-code-assist bot reviewed Aug 4, 2025

View reviewed changes

machichima force-pushed the 53226-env-var-for-ray-ctl branch 2 times, most recently from 159fb66 to 27f1b63 Compare August 7, 2025 01:06

machichima marked this pull request as ready for review August 7, 2025 01:51

machichima requested review from a team as code owners August 7, 2025 01:51

rueian reviewed Aug 7, 2025

View reviewed changes

ray-gardener bot added community-contribution Contributed by the community docs An issue or change related to documentation core Issues that should be addressed in Ray Core labels Aug 7, 2025

machichima force-pushed the 53226-env-var-for-ray-ctl branch from ef026f2 to 5d656e9 Compare August 8, 2025 02:13

owenowenisme approved these changes Aug 8, 2025

View reviewed changes

edoakes reviewed Aug 8, 2025

View reviewed changes

machichima added 6 commits August 9, 2025 09:08

feat: add env var for ray ctl only

e121f1d

-e Signed-off-by: machichima <[email protected]>

fix: use constant for env var name

d2ba39a

-e Signed-off-by: machichima <[email protected]>

refactor: format

0900bcc

-e Signed-off-by: machichima <[email protected]>

docs: update using RAY_API_SERVER_ADDRESS in docs

c1ac9b1

-e Signed-off-by: machichima <[email protected]>

test: add test for api server address

80079c7

-e Signed-off-by: machichima <[email protected]>

fix: update new env var in usage hint and cli pattern file

b7cb367

-e Signed-off-by: machichima <[email protected]>

machichima force-pushed the 53226-env-var-for-ray-ctl branch from 1271402 to b7cb367 Compare August 9, 2025 01:08

edoakes added the go add ONLY when ready to merge, run all tests label Aug 11, 2025

machichima and others added 2 commits August 12, 2025 07:09

Merge branch 'master' into 53226-env-var-for-ray-ctl

c00df16

refactor: update comments

79a50d0

-e Signed-off-by: machichima <[email protected]>

edoakes approved these changes Aug 12, 2025

View reviewed changes

edoakes merged commit 3a8e423 into ray-project:master Aug 12, 2025
5 checks passed

[Core]Separate Environment Variables for ray.init() and ray ctl to Reflect Different Protocols and Ports #55189

[Core]Separate Environment Variables for ray.init() and ray ctl to Reflect Different Protocols and Ports #55189

Uh oh!

Conversation

machichima commented Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why are these changes needed?

Related issue number

Checks

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

machichima Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rueian commented Aug 7, 2025

Uh oh!

machichima commented Aug 8, 2025

Uh oh!

owenowenisme left a comment

Choose a reason for hiding this comment

Uh oh!

edoakes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edoakes commented Aug 11, 2025

Uh oh!

edoakes commented Aug 12, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

machichima commented Aug 4, 2025 •

edited

Loading

machichima Aug 8, 2025 •

edited

Loading