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

machichima · dioptre · commit af94574c15f3 · 2025-08-20T13:19:17.000-07:00
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 <dioptre@gmail.com>
diff --git a/doc/source/cluster/running-applications/job-submission/quickstart.rst b/doc/source/cluster/running-applications/job-submission/quickstart.rst
@@ -68,13 +68,13 @@ If you are using a local Ray Cluster (``ray start --head``), connect directly at
 If you are using a Ray Cluster started on VMs or Kubernetes, follow the instructions there for setting up network access from a client. See :ref:`Using a Remote Cluster <jobs-remote-cluster>` for tips.
 
 
-To tell the Ray Jobs CLI how to find your Ray Cluster, pass the Ray Dashboard address. Set the ``RAY_ADDRESS`` environment variable:
+To tell the Ray Jobs CLI how to find your Ray Cluster, pass the Ray Dashboard address. Set the ``RAY_API_SERVER_ADDRESS`` environment variable:
 
 .. code-block:: bash
 
-    $ export RAY_ADDRESS="http://127.0.0.1:8265"
+    $ export RAY_API_SERVER_ADDRESS="http://127.0.0.1:8265"
 
-Alternatively, you can also pass the ``--address=http://127.0.0.1:8265`` flag explicitly to each Ray Jobs CLI command, or prepend each command with ``RAY_ADDRESS=http://127.0.0.1:8265``.
+Alternatively, you can also pass the ``--address=http://127.0.0.1:8265`` flag explicitly to each Ray Jobs CLI command, or prepend each command with ``RAY_API_SERVER_ADDRESS=http://127.0.0.1:8265``.
 
 Additionally, if you wish to pass headers per HTTP request to the Cluster, use the `RAY_JOB_HEADERS` environment variable. This environment variable must be in JSON form.
 
@@ -217,7 +217,7 @@ Run the following command on your local machine, where ``cluster.yaml`` is the c
     ray dashboard cluster.yaml
 
 Once this command is running, verify that you can view the Ray Dashboard in your local browser at ``http://127.0.0.1:8265``.
-Also, verify that you set the environment variable ``RAY_ADDRESS`` to ``"http://127.0.0.1:8265"``. After this setup, you can use the Jobs CLI on the local machine as in the preceding example to interact with the remote Ray cluster.
+Also, verify that you set the environment variable ``RAY_API_SERVER_ADDRESS`` to ``"http://127.0.0.1:8265"``. After this setup, you can use the Jobs CLI on the local machine as in the preceding example to interact with the remote Ray cluster.
 
 Using the CLI on Kubernetes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/python/ray/_private/ray_constants.py b/python/ray/_private/ray_constants.py
@@ -126,6 +126,7 @@ def env_set_by_user(key):
 DEFAULT_PORT = 6379
 
 RAY_ADDRESS_ENVIRONMENT_VARIABLE = "RAY_ADDRESS"
+RAY_API_SERVER_ADDRESS_ENVIRONMENT_VARIABLE = "RAY_API_SERVER_ADDRESS"
 RAY_NAMESPACE_ENVIRONMENT_VARIABLE = "RAY_NAMESPACE"
 RAY_RUNTIME_ENV_ENVIRONMENT_VARIABLE = "RAY_RUNTIME_ENV"
 RAY_RUNTIME_ENV_URI_PIN_EXPIRATION_S_ENV_VAR = (
diff --git a/python/ray/dashboard/modules/job/cli.py b/python/ray/dashboard/modules/job/cli.py
@@ -115,7 +115,7 @@ def job_cli_group():
     required=False,
     help=(
         "Address of the Ray cluster to connect to. Can also be specified "
-        "using the RAY_ADDRESS environment variable."
+        "using the RAY_API_SERVER_ADDRESS environment variable (falls back to RAY_ADDRESS)."
     ),
 )
 @click.option(
@@ -333,7 +333,7 @@ def submit(
     required=False,
     help=(
         "Address of the Ray cluster to connect to. Can also be specified "
-        "using the `RAY_ADDRESS` environment variable."
+        "using the RAY_API_SERVER_ADDRESS environment variable (falls back to RAY_ADDRESS)."
     ),
 )
 @click.argument("job-id", type=str)
@@ -363,7 +363,7 @@ def status(
     required=False,
     help=(
         "Address of the Ray cluster to connect to. Can also be specified "
-        "using the `RAY_ADDRESS` environment variable."
+        "using the RAY_API_SERVER_ADDRESS environment variable (falls back to RAY_ADDRESS)."
     ),
 )
 @click.option(
@@ -418,7 +418,7 @@ def stop(
     required=False,
     help=(
         "Address of the Ray cluster to connect to. Can also be specified "
-        "using the RAY_ADDRESS environment variable."
+        "using the RAY_API_SERVER_ADDRESS environment variable (falls back to RAY_ADDRESS)."
     ),
 )
 @click.argument("job-id", type=str)
@@ -455,7 +455,7 @@ def delete(
     required=False,
     help=(
         "Address of the Ray cluster to connect to. Can also be specified "
-        "using the RAY_ADDRESS environment variable."
+        "using the RAY_API_SERVER_ADDRESS environment variable (falls back to RAY_ADDRESS)."
     ),
 )
 @click.argument("job-id", type=str)
@@ -508,7 +508,7 @@ def logs(
     required=False,
     help=(
         "Address of the Ray cluster to connect to. Can also be specified "
-        "using the RAY_ADDRESS environment variable."
+        "using the RAY_API_SERVER_ADDRESS environment variable (falls back to RAY_ADDRESS)."
     ),
 )
 @add_common_job_options
diff --git a/python/ray/dashboard/modules/job/sdk.py b/python/ray/dashboard/modules/job/sdk.py
@@ -46,7 +46,7 @@ class JobSubmissionClient(SubmissionClient):
             ray.init(), e.g. a Ray Client address (ray://<head_node_host>:10001),
             or "auto", or "localhost:<port>". If unspecified, will try to connect to
             a running local Ray cluster. This argument is always overridden by the
-            RAY_ADDRESS environment variable.
+            RAY_API_SERVER_ADDRESS or RAY_ADDRESS environment variable.
         create_cluster_if_needed: Indicates whether the cluster at the specified
             address needs to already be running. Ray doesn't start a cluster
             before interacting with jobs, but third-party job managers may do so.
diff --git a/python/ray/dashboard/modules/job/tests/test_cli_integration.py b/python/ray/dashboard/modules/job/tests/test_cli_integration.py
@@ -142,11 +142,38 @@ def test_empty_ray_address(self, ray_start_stop):
             assert "succeeded" in stdout
 
     @pytest.mark.parametrize(
-        "ray_client_address", ["127.0.0.1:8265", "ray://127.0.0.1:8265"]
+        "ray_api_server_address,should_fail",
+        [
+            ("http://127.0.0.1:8265", False),  # correct API server
+            ("127.0.0.1:8265", True),  # wrong format without http
+            ("http://127.0.0.1:9999", True),  # wrong port
+        ],
     )
-    def test_ray_client_address(self, ray_start_stop, ray_client_address: str):
+    def test_ray_api_server_address(
+        self,
+        ray_start_stop,
+        ray_api_server_address: str,
+        should_fail: bool,
+    ):
+        # 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.
+        with set_env_var("RAY_ADDRESS", "ray://127.0.0.1:8265"):
+            with set_env_var("RAY_API_SERVER_ADDRESS", ray_api_server_address):
+                _run_cmd("ray job submit -- echo hello", should_fail=should_fail)
+
+    @pytest.mark.parametrize(
+        "ray_client_address,should_fail",
+        [
+            ("127.0.0.1:8265", True),
+            ("ray://127.0.0.1:8265", True),
+            ("http://127.0.0.1:8265", False),
+        ],
+    )
+    def test_ray_client_address(
+        self, ray_start_stop, ray_client_address: str, should_fail: bool
+    ):
         with set_env_var("RAY_ADDRESS", ray_client_address):
-            _run_cmd("ray job submit -- echo hello", should_fail=True)
+            _run_cmd("ray job submit -- echo hello", should_fail=should_fail)
 
     def test_valid_http_ray_address(self, ray_start_stop):
         stdout, _ = _run_cmd("ray job submit -- echo hello")
diff --git a/python/ray/dashboard/utils.py b/python/ray/dashboard/utils.py
@@ -709,9 +709,15 @@ def get_address_for_submission_client(address: Optional[str]) -> str:
     Returns:
         API server HTTP URL, e.g. "http://<head-node-ip>:8265".
     """
-    if 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_constants.RAY_API_SERVER_ADDRESS_ENVIRONMENT_VARIABLE
+    ):
+        address = api_server_address
+        logger.debug(f"Using RAY_API_SERVER_ADDRESS={address}")
+    # 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}")
 
     if address and "://" in address:
         module_string, _ = split_address(address)
diff --git a/python/ray/scripts/scripts.py b/python/ray/scripts/scripts.py
@@ -983,7 +983,7 @@ def start(
                 cli_logger.print("To submit a Ray job using the Ray Jobs CLI:")
                 cli_logger.print(
                     cf.bold(
-                        "  RAY_ADDRESS='http://{}' ray job submit "
+                        "  RAY_API_SERVER_ADDRESS='http://{}' ray job submit "
                         "--working-dir . "
                         "-- python my_script.py"
                     ),
diff --git a/python/ray/tests/test_cli_patterns/test_ray_start.txt b/python/ray/tests/test_cli_patterns/test_ray_start.txt
@@ -14,7 +14,7 @@ Next steps
     ray\.init\(\)
 
   To submit a Ray job using the Ray Jobs CLI:
-    RAY_ADDRESS='http://.+:8265' ray job submit --working-dir \. -- python my_script\.py
+    RAY_API_SERVER_ADDRESS='http://.+:8265' ray job submit --working-dir \. -- python my_script\.py
 
   See https://docs\.ray\.io/en/latest/cluster/running-applications/job-submission/index\.html
   for more information on submitting Ray jobs to the Ray cluster.
diff --git a/python/ray/tests/test_cli_patterns/test_ray_start_windows_osx.txt b/python/ray/tests/test_cli_patterns/test_ray_start_windows_osx.txt
@@ -15,7 +15,7 @@ Next steps
     ray\.init\(\)
 
   To submit a Ray job using the Ray Jobs CLI:
-    RAY_ADDRESS='http://.+:8265' ray job submit --working-dir \. -- python my_script\.py
+    RAY_API_SERVER_ADDRESS='http://.+:8265' ray job submit --working-dir \. -- python my_script\.py
 
   See https://docs\.ray\.io/en/latest/cluster/running-applications/job-submission/index\.html
   for more information on submitting Ray jobs to the Ray cluster.
