diff --git a/doc/source/ray-client.rst b/doc/source/ray-client.rst index a0cd6292a..a0335faae 100644 --- a/doc/source/ray-client.rst +++ b/doc/source/ray-client.rst @@ -10,13 +10,11 @@ Ray Client Basic usage =========== -The Ray client server is automatically started on port ``10001`` when you use ``ray start --head`` or Ray in an autoscaling cluster. The port can be changed by specifying --ray-client-server-port in the ``ray start`` command. - -To start the server manually, you can run: +While in beta, the server is available as an executable module. To start the server, run ``python -m ray.util.client.server [--host host_ip] [--port port] [--redis-address address] [--redis-password password]`` -This runs ``ray.init()`` with default options and exposes the client gRPC port at ``host_ip:port`` (by default, ``0.0.0.0:10001``). Providing ``redis-address`` and ``redis-password`` will be passed into ``ray.init()`` when the server starts, allowing connection to an existing Ray cluster, as per the `cluster setup `_ instructions. +This runs ``ray.init()`` with default options and exposes the client gRPC port at ``host_ip:port`` (by default, ``0.0.0.0:50051``). Providing ``redis-address`` and ``redis-password`` will be passed into ``ray.init()`` when the server starts, allowing connection to an existing Ray cluster, as per the `cluster setup `_ instructions. From here, another Ray script can access that server from a networked machine with ``ray.util.connect()`` @@ -25,7 +23,7 @@ From here, another Ray script can access that server from a networked machine wi import ray import ray.util - ray.util.connect(":10001") # replace with the appropriate host and port + ray.util.connect("0.0.0.0:50051") # replace with the appropriate host and port # Normal Ray code follows @ray.remote @@ -34,12 +32,13 @@ From here, another Ray script can access that server from a networked machine wi do_work.remote(2) #.... - -When the client disconnects, any object or actor references held by the server on behalf of the client are dropped, as if directly disconnecting from the cluster. -============ -Known issues -============ +When the client disconnects, any object or actor references held by the server on behalf of the client are dropped, as if directly disconnecting from the cluster + + +=================== +``RAY_CLIENT_MODE`` +=================== Because Ray client mode affects the behavior of the Ray API, larger scripts or libraries imported before ``ray.util.connect()`` may not realize they're in client mode. This feature is being tracked with `issue #13272 `_ but the workaround here is provided for beta users. @@ -50,3 +49,21 @@ Therefore, an environment variable is also available to force a Ray program into .. code-block:: bash RAY_CLIENT_MODE=1 python my_ray_program.py + + +=================================== +Programatically creating the server +=================================== + +For larger use-cases, it may be desirable to connect remote Ray clients to an existing Ray environment. The server can be started separately via + +.. code-block:: python + + from ray.util.client.server import serve + + server = serve("0.0.0.0:50051") + # Server does some work + # ... + # Time to clean up + server.stop(0) + diff --git a/python/ray/scripts/scripts.py b/python/ray/scripts/scripts.py index 378f302eb..11941f87a 100644 --- a/python/ray/scripts/scripts.py +++ b/python/ray/scripts/scripts.py @@ -282,7 +282,7 @@ def debug(address): "--ray-client-server-port", required=False, type=int, - default=10001, + default=None, help="the port number the ray client server will bind on. If not set, " "the ray client server will not be started.") @click.option( diff --git a/python/ray/tests/test_job.py b/python/ray/tests/test_job.py index cc7909dd8..15b082b46 100644 --- a/python/ray/tests/test_job.py +++ b/python/ray/tests/test_job.py @@ -33,7 +33,7 @@ _ = Actor.remote() assert len(actor_table) == 1 job_table = ray.jobs() - assert len(job_table) == 3 # dash, ray client server + assert len(job_table) == 2 # Kill the driver process. p.kill() @@ -79,7 +79,7 @@ ray.get(_.value.remote()) assert len(actor_table) == 1 job_table = ray.jobs() - assert len(job_table) == 3 # dash, ray client server + assert len(job_table) == 2 # Kill the driver process. p.kill()