[Doc] [Core] [runtime env] Add runtime env doc #16290
Conversation
doc/source/advanced.rst
Outdated
|
|
||
| .. code-block:: python | ||
|
|
||
| my_actor = MyActor.options(runtime_env={"conda_env": "my_env"}).remote() | ||
| ray.init(job_config=ray.job_config.JobConfig(runtime_env=runtime_env)) |
There was a problem hiding this comment.
We should definitely decouple this from jobconfig before GA'ing the feature, this is very ugly!
doc/source/advanced.rst
Outdated
|
|
||
| To start a specific task or an actor in an existing conda environment, pass in the environment name to your task or | ||
| actor via the ``runtime_env`` parameter as follows: | ||
| Examples: |
There was a problem hiding this comment.
The flow here is a little weird that we're showing examples with different features before introducing the actual options that are supported. Should we reverse the order? Or maybe just show how you can pass it in without showing the details yet?
doc/source/advanced.rst
Outdated
| - Examples | ||
|
|
||
| - ``"." # cwd`` | ||
|
|
||
| - ``"local_project.zip" # Archive is unpacked into the directory.`` | ||
|
|
||
| Note: Setting this option per-task or per-actor is currently unsupported. | ||
|
|
||
| - ``pip`` (List[str] | str): Either a list of pip packages, or a string containing the path to a pip “requirements.txt” file. This will be dynamically installed in the ``runtime_env``. | ||
|
|
||
| - Example: ``["requests==1.0.0", "aiohttp"]`` | ||
|
|
||
| - Example: ``"./requirements.txt"`` | ||
|
|
||
| - ``conda`` (dict | str): Either a dict representing the conda environment YAML, a string containing the path to a | ||
| `conda “environment.yaml” <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually>`_ file, | ||
| or the name of a local conda env already installed on each node in your cluster (e.g., ``"pytorch_p36"``). | ||
| In the first two cases, the Ray and Python dependencies will be automatically injected into the environment to ensure compatibility, so there is no need to manually include them. | ||
| Note that the ``conda`` and ``pip`` keys of ``runtime_env`` cannot both be specified at the same time--to use them together, please add your conda dependencies under the ``"pip"`` entry in your conda ``environment.yaml``. | ||
|
|
||
| - Example: ``{"conda": {"dependencies": ["pytorch", “torchvision”, "pip", {"pip": ["chess"]}]}}`` | ||
|
|
||
| - Example: ``"./environment.yml"`` | ||
|
|
||
| - Example: ``"pytorch_p36"`` | ||
|
|
||
| - ``env_vars`` (Dict[str, str]): Environment variables to set. | ||
|
|
||
| - Example: ``{"OMP_NUM_THREADS": "32", "TF_WARNINGS": "none"}`` | ||
|
|
||
| The runtime env is inheritable, so it will apply to all tasks/actors within a job and all child tasks/actors of a task or actor, once set. |
There was a problem hiding this comment.
I feel like all of this should just be coming from the docstring of runtime_env -- is there a way we can just do the documentation for the individual options there and embed it here?
There was a problem hiding this comment.
I agree this makes sense as a long term solution, but right now runtime_env is a simple Python dict, so it doesn't have a docstring. The RuntimeEnvDict class in the code has a docstring, but it's an internal object so I don't think we want to expose it. I looked for a way for Sphinx to only grab the docstring of RuntimeEnvDict without having the class name appearing in the docs, but couldn't find one.
AmeerHajAli
added
the
@author-action-required
doc/source/advanced.rst
Outdated
|
|
||
| .. code-block:: python | ||
|
|
||
| runtime_env = {"working_dir": "local_project.zip", "pip": ["chess==1.5.0"]} |
There was a problem hiding this comment.
Right now we don't support working_dir as a zip. It should be a local dir.
ray will pack it into zip and unpack it automatically.
|
I added a test for the conda runtime_env code sample, both for the job_config case and the per-task and per-actor case. I verified that the test is running in CI: https://buildkite.com/ray-project/ray-builders-pr/builds/6762#e4425484-2aae-42bf-be9a-a9c63a37a398/6-10401 Adding a test for the Ray Client and |
architkulkarni
added
tests-ok
|
@architkulkarni , when you merge this can you please close "Missing documentation for runtime envs in open source anyscale/product#4680 " |
Why are these changes needed?
Adds documentation for runtime envs. Some code samples from these docs are drawn from a script which is tested in CI.
Related issue number
Checks
scripts/format.shto lint the changes in this PR.