def _server_init(self,
job_config: JobConfig,
ray_init_kwargs: Optional[Dict[str, Any]] = None):
"""Initialize the server"""
if ray_init_kwargs is None:
ray_init_kwargs = {}
try:
if job_config is None:
serialized_job_config = None
else:
with tempfile.TemporaryDirectory() as tmp_dir:
runtime_env = job_config.runtime_env or {}
runtime_env = upload_py_modules_if_needed(runtime_env,
tmp_dir,
logger=logger)
runtime_env = upload_working_dir_if_needed(runtime_env,
tmp_dir,
logger=logger)
# Remove excludes, it isn't relevant after the upload step.
runtime_env.pop("excludes", None)
job_config.set_runtime_env(runtime_env)
serialized_job_config = pickle.dumps(job_config)
response = self.data_client.Init(
ray_client_pb2.InitRequest(
job_config=serialized_job_config,
ray_init_kwargs=json.dumps(ray_init_kwargs),
reconnect_grace_period=self._reconnect_grace_period))
if not response.ok:
raise ConnectionAbortedError(
f"Initialization failure from server:\n{response.msg}")
except grpc.RpcError as e:
raise decode_exception(e)
class ClientBuilder:
"""
Builder for a Ray Client connection.
"""
def __init__(self, address: Optional[str]) -> None:
self.address = address
self._job_config = JobConfig()
def env(self, env: Dict[str, Any]) -> "ClientBuilder":
"""
Set an environment for the session.
"""
self._job_config.set_runtime_env(env)
return self
def namespace(self, namespace: str) -> "ClientBuilder":
self._job_config.set_ray_namespace(namespace)
return self
def connect(self) -> ClientInfo:
"""
Begin a connection to the address passed in via ray.client(...).
"""
client_info_dict = ray.util.client_connect.connect(
self.address, job_config=self._job_config)
dashboard_url = ray.get(
ray.remote(ray.worker.get_dashboard_url).remote())
return ClientInfo(
dashboard_url=dashboard_url,
python_version=client_info_dict["python_version"],
ray_version=client_info_dict["ray_version"],
ray_commit=client_info_dict["ray_commit"],
protocol_version=client_info_dict["protocol_version"])
class ClientBuilder:
"""
Builder for a Ray Client connection. This class can be subclassed by
custom builder classes to modify connection behavior to include additional
features or altered semantics. One example is the ``_LocalClientBuilder``.
"""
def __init__(self, address: Optional[str]) -> None:
self.address = address
self._job_config = JobConfig()
def env(self, env: Dict[str, Any]) -> "ClientBuilder":
"""
Set an environment for the session.
Args:
env (Dict[st, Any]): A runtime environment to use for this
connection. See ``runtime_env.py`` for what values are
accepted in this dict.
"""
self._job_config.set_runtime_env(env)
return self
def namespace(self, namespace: str) -> "ClientBuilder":
"""
Sets the namespace for the session.
Args:
namespace (str): Namespace to use.
"""
self._job_config.set_ray_namespace(namespace)
return self
def connect(self) -> ClientContext:
"""
Begin a connection to the address passed in via ray.client(...).
Returns:
ClientInfo: Dataclass with information about the setting. This
includes the server's version of Python & Ray as well as the
dashboard_url.
"""
client_info_dict = ray.util.client_connect.connect(
self.address, job_config=self._job_config)
dashboard_url = ray.get(
ray.remote(ray.worker.get_dashboard_url).remote())
return ClientContext(
dashboard_url=dashboard_url,
python_version=client_info_dict["python_version"],
ray_version=client_info_dict["ray_version"],
ray_commit=client_info_dict["ray_commit"],
protocol_version=client_info_dict["protocol_version"],
_num_clients=client_info_dict["num_clients"])
class ClientBuilder:
"""
Builder for a Ray Client connection. This class can be subclassed by
custom builder classes to modify connection behavior to include additional
features or altered semantics. One example is the ``_LocalClientBuilder``.
"""
def __init__(self, address: Optional[str]) -> None:
self.address = address
self._job_config = JobConfig()
self._remote_init_kwargs = {}
# Whether to allow connections to multiple clusters"
# " (allow_multiple=True).
self._allow_multiple_connections = False
self._credentials = None
# Set to False if ClientBuilder is being constructed by internal
# methods
self._deprecation_warn_enabled = True
def env(self, env: Dict[str, Any]) -> "ClientBuilder":
"""
Set an environment for the session.
Args:
env (Dict[st, Any]): A runtime environment to use for this
connection. See :ref:`runtime-environments` for what values are
accepted in this dict.
"""
self._job_config.set_runtime_env(env)
return self
def namespace(self, namespace: str) -> "ClientBuilder":
"""
Sets the namespace for the session.
Args:
namespace (str): Namespace to use.
"""
self._job_config.set_ray_namespace(namespace)
return self
def connect(self) -> ClientContext:
"""
Begin a connection to the address passed in via ray.client(...).
Returns:
ClientInfo: Dataclass with information about the setting. This
includes the server's version of Python & Ray as well as the
dashboard_url.
"""
if self._deprecation_warn_enabled:
self._client_deprecation_warn()
# Fill runtime env/namespace from environment if not already set.
# Should be done *after* the deprecation warning, since warning will
# check if those values are already set.
self._fill_defaults_from_env()
# If it has already connected to the cluster with allow_multiple=True,
# connect to the default one is not allowed.
# But if it has connected to the default one, connect to other clients
# with allow_multiple=True is allowed
default_cli_connected = ray.util.client.ray.is_connected()
has_cli_connected = ray.util.client.num_connected_contexts() > 0
if (
not self._allow_multiple_connections
and not default_cli_connected
and has_cli_connected
):
raise ValueError(
"The client has already connected to the cluster "
"with allow_multiple=True. Please set allow_multiple=True"
" to proceed"
)
old_ray_cxt = None
if self._allow_multiple_connections:
old_ray_cxt = ray.util.client.ray.set_context(None)
client_info_dict = ray.util.client_connect.connect(
self.address,
job_config=self._job_config,
_credentials=self._credentials,
ray_init_kwargs=self._remote_init_kwargs,
)
get_dashboard_url = ray.remote(ray.worker.get_dashboard_url)
dashboard_url = ray.get(get_dashboard_url.options(num_cpus=0).remote())
cxt = ClientContext(
dashboard_url=dashboard_url,
python_version=client_info_dict["python_version"],
ray_version=client_info_dict["ray_version"],
ray_commit=client_info_dict["ray_commit"],
protocol_version=client_info_dict["protocol_version"],
_num_clients=client_info_dict["num_clients"],
_context_to_restore=ray.util.client.ray.get_context(),
)
if self._allow_multiple_connections:
ray.util.client.ray.set_context(old_ray_cxt)
return cxt
def _fill_defaults_from_env(self):
# Check environment variables for default values
namespace_env_var = os.environ.get(RAY_NAMESPACE_ENVIRONMENT_VARIABLE)
if namespace_env_var and self._job_config.ray_namespace is None:
self.namespace(namespace_env_var)
runtime_env_var = os.environ.get(RAY_RUNTIME_ENV_ENVIRONMENT_VARIABLE)
if runtime_env_var and self._job_config.runtime_env is None:
self.env(json.loads(runtime_env_var))
def _init_args(self, **kwargs) -> "ClientBuilder":
"""
When a client builder is constructed through ray.init, for example
`ray.init(ray://..., namespace=...)`, all of the
arguments passed into ray.init with non-default values are passed
again into this method. Custom client builders can override this method
to do their own handling/validation of arguments.
"""
# Use namespace and runtime_env from ray.init call
if kwargs.get("namespace") is not None:
self.namespace(kwargs["namespace"])
del kwargs["namespace"]
if kwargs.get("runtime_env") is not None:
self.env(kwargs["runtime_env"])
del kwargs["runtime_env"]
if kwargs.get("allow_multiple") is True:
self._allow_multiple_connections = True
del kwargs["allow_multiple"]
if "_credentials" in kwargs.keys():
self._credentials = kwargs["_credentials"]
del kwargs["_credentials"]
if kwargs:
expected_sig = inspect.signature(ray_driver_init)
extra_args = set(kwargs.keys()).difference(expected_sig.parameters.keys())
if len(extra_args) > 0:
raise RuntimeError(
"Got unexpected kwargs: {}".format(", ".join(extra_args))
)
self._remote_init_kwargs = kwargs
unknown = ", ".join(kwargs)
logger.info(
"Passing the following kwargs to ray.init() "
f"on the server: {unknown}"
)
return self
def _client_deprecation_warn(self) -> None:
"""
Generates a warning for user's if this ClientBuilder instance was
created directly or through ray.client, instead of relying on
internal methods (ray.init, or auto init)
"""
namespace = self._job_config.ray_namespace
runtime_env = self._job_config.runtime_env
replacement_args = []
if self.address:
if isinstance(self, _LocalClientBuilder):
# Address might be set for LocalClientBuilder if ray.client()
# is called while ray_current_cluster is set
# (see _get_builder_from_address). In this case,
# leave off the ray:// so the user attaches the driver directly
replacement_args.append(f'"{self.address}"')
else:
replacement_args.append(f'"ray://{self.address}"')
if namespace:
replacement_args.append(f'namespace="{namespace}"')
if runtime_env:
# Use a placeholder here, since the real runtime_env would be
# difficult to read if formatted in directly
replacement_args.append("runtime_env=<your_runtime_env>")
args_str = ", ".join(replacement_args)
replacement_call = f"ray.init({args_str})"
# Note: stack level is set to 3 since we want the warning to reach the
# call to ray.client(...).connect(). The intervening frames are
# connect() -> client_deprecation_warn() -> warnings.warn()
# https://docs.python.org/3/library/warnings.html#available-functions
warnings.warn(
"Starting a connection through `ray.client` will be deprecated "
"in future ray versions in favor of `ray.init`. See the docs for "
f"more details: {CLIENT_DOCS_URL}. You can replace your call to "
"`ray.client().connect()` with the following:\n"
f" {replacement_call}\n",
DeprecationWarning,
stacklevel=3,
)
class ClientBuilder:
"""
Builder for a Ray Client connection. This class can be subclassed by
custom builder classes to modify connection behavior to include additional
features or altered semantics. One example is the ``_LocalClientBuilder``.
"""
def __init__(self, address: Optional[str]) -> None:
self.address = address
self._job_config = JobConfig()
self._fill_defaults_from_env()
def env(self, env: Dict[str, Any]) -> "ClientBuilder":
"""
Set an environment for the session.
Args:
env (Dict[st, Any]): A runtime environment to use for this
connection. See :ref:`runtime-environments` for what values are
accepted in this dict.
"""
self._job_config.set_runtime_env(env)
return self
def namespace(self, namespace: str) -> "ClientBuilder":
"""
Sets the namespace for the session.
Args:
namespace (str): Namespace to use.
"""
self._job_config.set_ray_namespace(namespace)
return self
def connect(self) -> ClientContext:
"""
Begin a connection to the address passed in via ray.client(...).
Returns:
ClientInfo: Dataclass with information about the setting. This
includes the server's version of Python & Ray as well as the
dashboard_url.
"""
client_info_dict = ray.util.client_connect.connect(
self.address, job_config=self._job_config)
dashboard_url = ray.get(
ray.remote(ray.worker.get_dashboard_url).remote())
return ClientContext(
dashboard_url=dashboard_url,
python_version=client_info_dict["python_version"],
ray_version=client_info_dict["ray_version"],
ray_commit=client_info_dict["ray_commit"],
protocol_version=client_info_dict["protocol_version"],
_num_clients=client_info_dict["num_clients"])
def _fill_defaults_from_env(self):
# Check environment variables for default values
namespace_env_var = os.environ.get(RAY_NAMESPACE_ENVIRONMENT_VARIABLE)
if namespace_env_var and self._job_config.ray_namespace is None:
self.namespace(namespace_env_var)
runtime_env_var = os.environ.get(RAY_RUNTIME_ENV_ENVIRONMENT_VARIABLE)
if runtime_env_var and self._job_config.runtime_env is None:
self.env(json.loads(runtime_env_var))
def _init_args(self, **kwargs) -> "ClientBuilder":
"""
When a client builder is constructed through ray.init, for example
`ray.init(ray://..., namespace=...)`, all of the
arguments passed into ray.init are passed again into this method.
Custom client builders can override this method to do their own
handling/validation of arguments.
"""
# Use namespace and runtime_env from ray.init call
if kwargs.get("namespace") is not None:
self.namespace(kwargs["namespace"])
del kwargs["namespace"]
if kwargs.get("runtime_env") is not None:
self.env(kwargs["runtime_env"])
del kwargs["runtime_env"]
if not kwargs:
return self
unknown = ", ".join(kwargs)
raise RuntimeError(
f"Unexpected keyword argument(s) for Ray Client: {unknown}")
class ClientBuilder:
"""
Builder for a Ray Client connection. This class can be subclassed by
custom builder classes to modify connection behavior to include additional
features or altered semantics. One example is the ``_LocalClientBuilder``.
"""
def __init__(self, address: Optional[str]) -> None:
self.address = address
self._job_config = JobConfig()
self._fill_defaults_from_env()
self._remote_init_kwargs = {}
# Whether to allow connections to multiple clusters"
# " (allow_multiple=True).
self._allow_multiple_connections = False
self._credentials = None
def env(self, env: Dict[str, Any]) -> "ClientBuilder":
"""
Set an environment for the session.
Args:
env (Dict[st, Any]): A runtime environment to use for this
connection. See :ref:`runtime-environments` for what values are
accepted in this dict.
"""
self._job_config.set_runtime_env(env)
return self
def namespace(self, namespace: str) -> "ClientBuilder":
"""
Sets the namespace for the session.
Args:
namespace (str): Namespace to use.
"""
self._job_config.set_ray_namespace(namespace)
return self
def connect(self) -> ClientContext:
"""
Begin a connection to the address passed in via ray.client(...).
Returns:
ClientInfo: Dataclass with information about the setting. This
includes the server's version of Python & Ray as well as the
dashboard_url.
"""
# If it has already connected to the cluster with allow_multiple=True,
# connect to the default one is not allowed.
# But if it has connected to the default one, connect to other clients
# with allow_multiple=True is allowed
default_cli_connected = ray.util.client.ray.is_connected()
has_cli_connected = ray.util.client.num_connected_contexts() > 0
if not self._allow_multiple_connections and \
not default_cli_connected and has_cli_connected:
raise ValueError(
"The client has already connected to the cluster "
"with allow_multiple=True. Please set allow_multiple=True"
" to proceed")
old_ray_cxt = None
if self._allow_multiple_connections:
old_ray_cxt = ray.util.client.ray.set_context(None)
client_info_dict = ray.util.client_connect.connect(
self.address,
job_config=self._job_config,
_credentials=self._credentials,
ray_init_kwargs=self._remote_init_kwargs)
dashboard_url = ray.get(
ray.remote(ray.worker.get_dashboard_url).remote())
cxt = ClientContext(
dashboard_url=dashboard_url,
python_version=client_info_dict["python_version"],
ray_version=client_info_dict["ray_version"],
ray_commit=client_info_dict["ray_commit"],
protocol_version=client_info_dict["protocol_version"],
_num_clients=client_info_dict["num_clients"],
_context_to_restore=ray.util.client.ray.get_context())
if self._allow_multiple_connections:
ray.util.client.ray.set_context(old_ray_cxt)
return cxt
def _fill_defaults_from_env(self):
# Check environment variables for default values
namespace_env_var = os.environ.get(RAY_NAMESPACE_ENVIRONMENT_VARIABLE)
if namespace_env_var and self._job_config.ray_namespace is None:
self.namespace(namespace_env_var)
runtime_env_var = os.environ.get(RAY_RUNTIME_ENV_ENVIRONMENT_VARIABLE)
if runtime_env_var and self._job_config.runtime_env is None:
self.env(json.loads(runtime_env_var))
def _init_args(self, **kwargs) -> "ClientBuilder":
"""
When a client builder is constructed through ray.init, for example
`ray.init(ray://..., namespace=...)`, all of the
arguments passed into ray.init are passed again into this method.
Custom client builders can override this method to do their own
handling/validation of arguments.
"""
# Use namespace and runtime_env from ray.init call
if kwargs.get("namespace") is not None:
self.namespace(kwargs["namespace"])
del kwargs["namespace"]
if kwargs.get("runtime_env") is not None:
self.env(kwargs["runtime_env"])
del kwargs["runtime_env"]
if kwargs.get("allow_multiple") is True:
self._allow_multiple_connections = True
del kwargs["allow_multiple"]
if "_credentials" in kwargs.keys():
self._credentials = kwargs["_credentials"]
del kwargs["_credentials"]
if kwargs:
expected_sig = inspect.signature(ray_driver_init)
extra_args = set(kwargs.keys()).difference(
expected_sig.parameters.keys())
if len(extra_args) > 0:
raise RuntimeError("Got unexpected kwargs: {}".format(
", ".join(extra_args)))
self._remote_init_kwargs = kwargs
unknown = ", ".join(kwargs)
logger.info("Passing the following kwargs to ray.init() "
f"on the server: {unknown}")
return self
def start_specific_server(self, client_id: str,
job_config: JobConfig) -> bool:
"""
Start up a RayClient Server for an incoming client to
communicate with. Returns whether creation was successful.
"""
specific_server = self._get_server_for_client(client_id)
assert specific_server, f"Server has not been created for: {client_id}"
output, error = self.node.get_log_file_handles(
f"ray_client_server_{specific_server.port}", unique=True)
# Set up the working_dir for the server.
# TODO(edoakes): this should go be unified with the worker setup code
# by going through the runtime_env agent.
uris = job_config.get_runtime_env_uris() if job_config else []
if uris:
# Download and set up the working_dir locally.
working_dir = working_dir_pkg.ensure_runtime_env_setup(uris)
# Set PYTHONPATH in the environment variables so the working_dir
# is included in the module search path.
runtime_env = job_config.runtime_env
env_vars = runtime_env.get("env_vars", None) or {}
python_path = working_dir
if "PYTHONPATH" in env_vars:
python_path += (os.pathsep + runtime_env["PYTHONPATH"])
env_vars["PYTHONPATH"] = python_path
runtime_env["env_vars"] = env_vars
job_config.set_runtime_env(runtime_env)
serialized_runtime_env = job_config.get_serialized_runtime_env()
proc = start_ray_client_server(
self.redis_address,
specific_server.port,
stdout_file=output,
stderr_file=error,
fate_share=self.fate_share,
server_type="specific-server",
serialized_runtime_env=serialized_runtime_env,
session_dir=self.node.get_session_dir_path(),
redis_password=self._redis_password)
# Wait for the process being run transitions from the shim process
# to the actual RayClient Server.
pid = proc.process.pid
if sys.platform != "win32":
psutil_proc = psutil.Process(pid)
else:
psutil_proc = None
# Don't use `psutil` on Win32
while psutil_proc is not None:
if proc.process.poll() is not None:
logger.error(
f"SpecificServer startup failed for client: {client_id}")
break
cmd = psutil_proc.cmdline()
if _match_running_client_server(cmd):
break
logger.debug(
"Waiting for Process to reach the actual client server.")
time.sleep(0.5)
specific_server.set_result(proc)
logger.info(f"SpecificServer started on port: {specific_server.port} "
f"with PID: {pid} for client: {client_id}")
return proc.process.poll() is None