[runtime env] [Doc] Add concepts and basic workflows #20222

architkulkarni · 2021-11-10T19:00:05Z

Why are these changes needed?

Renaming the file made the diff hard to check, It might be easier to review by just scanning through the Buildkite docs build. (Or you can just check this commit 26676de)

Address followup comments from [Doc] [runtime env] Move runtime env section up one level, add inbound links #19863
Add short "Concepts" section
Add more section headings to break up the text
Add "Workflow: Local Files" example
Add "Workflow: Library development" example

TODO: Move new code samples to files that are tested in CI

Related issue number

Checks

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 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 :(

richardliaw · 2021-11-10T19:01:44Z

Hey @architkulkarni can you add a PR description?

richardliaw · 2021-11-10T19:01:52Z

also can I push directly?

architkulkarni · 2021-11-10T19:02:13Z

Adding one now, and yeah feel free to push

architkulkarni · 2021-11-10T19:16:36Z

doc/source/handling-dependencies.rst

+ - for running jobs, tasks and actors with different dependencies, all on the same Ray cluster.
+
+**Option 2.**  Alternatively, you can prepare your Ray cluster's environment when your cluster nodes start up, and modify it later from the command line.
+Packages can be installed using ``setup_commands`` in the Ray Cluster configuration file (:ref:`docs<cluster-configuration-setup-commands>`) and files can be pushed to the cluster using ``ray rsync_up`` (:ref:`docs<ray-rsync>`).


@rkooo567 I know we still need more here but I'm not quite sure what to put, do you have any ideas?

I think we should ask the autoscaler team to fill it up.

I think common problems are

Manual:

Link to autoscaler section that describes how to set up deps

env variables (setup commands)

System deps (setup commands)

Files (rsync up or manually copy and paste. Make sure they are all synced)

Python packages (setup commands)

Container

Same things (link to container deployment)

doc/examples/doc_code/runtime_env_example.py

richardliaw · 2021-11-13T01:57:17Z

doc/source/handling-dependencies.rst

+=====================
+
+Your Ray application may depend on environment variables, files, and Python packages.
+Ray provides two features to specify these dependencies when working with a remote cluster: Runtime environments, and the Ray cluster launcher commands


Suggested change

Ray provides two features to specify these dependencies when working with a remote cluster: Runtime environments, and the Ray cluster launcher commands

Ray provides two features to specify these dependencies when working with a Ray cluster: :ref:`runtime Environments<runtime-environments>`, and the :ref:`Ray cluster launcher commands <INSERT THE RIGHT LINK>`.

doc/source/handling-dependencies.rst

rkooo567 · 2021-11-14T08:15:40Z

doc/source/handling-dependencies.rst

+
+Your Ray application may depend on environment variables, files, and Python packages.
+Ray provides two features to specify these dependencies when working with a remote cluster: Runtime environments, and the Ray cluster launcher commands
+With these features, you no longer need to manually SSH into your cluster and set up your environment.


A little confused with this sentence. We don't need to manually SSH into your cluster for the existing solution now right? (it is handled by the setup commands)

Yeah, I meant to include setup commands in "Ray cluster launcher commands", which this doc describes as an existing feature. Let me make this more clear

rkooo567 · 2021-11-14T08:23:31Z

doc/source/handling-dependencies.rst

+Your Ray application may depend on environment variables, files, and Python packages.
+Ray provides two features to specify these dependencies when working with a remote cluster: Runtime environments, and the Ray cluster launcher commands
+With these features, you no longer need to manually SSH into your cluster and set up your environment.
+


I think we should start problem the highest problem to low level options here.

Maybe we can describe it in this way instead?

What's the environment in Ray?

Why environment matters in Ray?

And then we can say

There are 2 ways to set up your Ray environment (e.g., files, environment variables, python package dependencies, system dependencies and etc.)

Set up the same environment across machines. This is the most common way to configure environments in Ray. You can use autoscaler's setup commands or docker container deployment. Blah blah... All of Ray tasks and actors will use the same environment as all machines are configured with the same environment. Pro is X con is Y (e.g., all jobs have to use the same environment.)

Set up per job/task/actor environment. This is useful when X (e.g., Serve or multi tenant cluster). In this case you can use runtime environment API blah blah.. Pro is X con is Y.

I think we might need a section regarding how to setup environment when Ray client is used, and runtime environment can be used as a good solution as well (or you should mention the local machine / remote cluster should have the same environment).

I agree this is useful to have in the docs. Maybe we can put them in a top-level page under "Multi-Node Ray" which then links to this runtime env page.

rkooo567 · 2021-11-14T08:26:23Z

doc/source/handling-dependencies.rst

+ - for running jobs, tasks and actors with different dependencies, all on the same Ray cluster.
+
+**Option 2.**  Alternatively, you can prepare your Ray cluster's environment when your cluster nodes start up, and modify it later from the command line.
+Packages can be installed using ``setup_commands`` in the Ray Cluster configuration file (:ref:`docs<cluster-configuration-setup-commands>`) and files can be pushed to the cluster using ``ray rsync_up`` (:ref:`docs<ray-rsync>`).


I think common problems are

Manual:

Link to autoscaler section that describes how to set up deps

env variables (setup commands)

System deps (setup commands)

Files (rsync up or manually copy and paste. Make sure they are all synced)

Python packages (setup commands)

Container

Same things (link to container deployment)

doc/source/handling-dependencies.rst

rkooo567 · 2021-11-14T08:29:06Z

doc/source/handling-dependencies.rst

+Concepts
+--------
+
+- **Local machine** and **Cluster**.  The recommended way to connect to a remote Ray cluster is to use :ref:`Ray Client<ray-client>`, and we will call the machine running Ray Client your *local machine*.  Note: you can also start a single-node Ray cluster on your local machine---in this case your Ray cluster is not really “remote”, but any comments in this documentation referring to a “remote cluster” will also apply to this setup.


Is it true ray client is a recommended way? Afaik, it is a lot less stable to use ray client now than directly submitting the driver?

I got that from here https://docs.ray.io/en/latest/cluster/guide.html#deploying-an-application "The recommended way of connecting to a Ray cluster is to use the ray.init("ray://:") API and connect via the Ray Client."

I'm not sure which is more stable, but you're right that we should be clear about which one is recommended

doc/source/handling-dependencies.rst

rkooo567 · 2021-11-14T08:44:18Z

doc/source/handling-dependencies.rst

+
+    - ``my_module # Assumes my_module has already been imported, e.g. via 'import my_module'``
+
+  Note: Note: Setting options (1) and (3) per-task or per-actor is currently unsupported.


Maybe having a separate section to explain what APIs are supported for per job or per actor / tasks? Like;

Supported APIs:

Jobs

working dir

conda env

pymodule...

Per tasks/actors

conda env

doc/source/handling-dependencies.rst

rkooo567 · 2021-11-14T08:47:12Z

doc/source/using-ray.rst

@@ -13,7 +13,7 @@ Finally, we've also included some content on using core Ray APIs with `Tensorflo
   starting-ray.rst
   actors.rst
   namespaces.rst
-   dependency-management.rst
+   handling-dependencies.rst


What's the motivation of the name change here?

It was suggested here #19863 (comment) @richardliaw is it because "Dependency Management" already has a meaning that's too specific?

doc/examples/doc_code/runtime_env_example.py

Signed-off-by: Richard Liaw <[email protected]>

doc/source/handling-dependencies.rst

…into doc-py-modules

…py-modules

architkulkarni · 2021-11-19T17:11:34Z

I think the only remaining open question is how much to include about the cluster launcher approach (setup_commands, rsync, directly submitting driver script with address=auto, etc.). There seem to be different opinions here and it probably depends on what we want to promote as a best practice.

The current iteration of the PR doesn't mention the cluster launcher at all, but links to the Runtime Environments page from within "Multi-Node Ray > Ray Deployment Guide". I added some words in the cluster launcher section about environment variables and package installation.

richardliaw · 2021-11-19T17:24:48Z

That’s fine, I think we should limit this to mostly runtime envs as you have done so far and start moving the rest of the docs towards this as the golden path.

…

On Fri, Nov 19, 2021 at 9:11 AM architkulkarni ***@***.***> wrote: I think the only remaining open question is how much to include about the cluster launcher approach (setup_commands, rsync, directly submitting driver script with address=auto, etc.). There seem to be different opinions here and it probably depends on what we want to promote as a best practice. The current iteration of the PR doesn't mention the cluster launcher at all, but links to the Runtime Environments page from within "Multi-Node Ray > Ray Deployment Guide". I added some words in the cluster launcher section about environment variables and package installation. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#20222 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABCRZZKH34SBTU7O57KMFNDUM2ANDANCNFSM5HYUSZFA> .

Address followup comments from #19863 - Add short "Concepts" section - Add more section headings to break up the text - Add "Workflow: Local Files" example - Add "Workflow: Library development" example

architkulkarni added 2 commits November 9, 2021 11:22

dependency management -> handling dependencies

dd957c3

add concepts, add files and modules workflows

26676de

architkulkarni assigned richardliaw Nov 10, 2021

architkulkarni requested a review from ericl as a code owner November 10, 2021 19:00

architkulkarni assigned edoakes Nov 10, 2021

architkulkarni requested a review from fishbone as a code owner November 10, 2021 19:00

architkulkarni assigned rkooo567 Nov 10, 2021

architkulkarni commented Nov 10, 2021

View reviewed changes

richardliaw reviewed Nov 13, 2021

View reviewed changes

doc/examples/doc_code/runtime_env_example.py Outdated Show resolved Hide resolved

richardliaw reviewed Nov 13, 2021

View reviewed changes

doc/source/handling-dependencies.rst Outdated Show resolved Hide resolved

richardliaw reviewed Nov 13, 2021

View reviewed changes

doc/source/handling-dependencies.rst Outdated Show resolved Hide resolved

rkooo567 reviewed Nov 14, 2021

View reviewed changes

AmeerHajAli reviewed Nov 14, 2021

View reviewed changes

doc/examples/doc_code/runtime_env_example.py Show resolved Hide resolved

AmeerHajAli reviewed Nov 14, 2021

View reviewed changes

doc/examples/doc_code/runtime_env_example.py Show resolved Hide resolved

rkooo567 added the @author-action-required The PR author is responsible for the next step. Remove tag to send back to the reviewer. label Nov 15, 2021

architkulkarni requested a review from amogkam November 16, 2021 01:13

fix

ca25c47

Signed-off-by: Richard Liaw <[email protected]>

edoakes reviewed Nov 18, 2021

View reviewed changes

doc/source/handling-dependencies.rst Show resolved Hide resolved

doc/source/handling-dependencies.rst Outdated Show resolved Hide resolved

architkulkarni added 8 commits November 17, 2021 16:29

Merge branch 'master' into doc-py-modules

c02bbbb

add comments to code example

7e1d2b8

Merge branch 'doc-py-modules' of https://github.com/architkulkarni/ray …

1cd296c

…into doc-py-modules

typo

6f06a71

add compatibility warning

4ffeaa2

Merge branch 'master' of https://github.com/ray-project/ray into doc-…

e567539

…py-modules

merge in "Remote URIs" PR

4a56ece

formatting, add inheritance example

457e131

architkulkarni added 9 commits November 18, 2021 12:17

fix bullet

761d52d

works with address=auto

c15564b

define "Job".

caaa7d6

remove quotes

3288048

add conda pip workflow

44ab154

fix

cf9cb0e

fix

1d4e548

fix

703beff

Merge branch 'master' into doc-py-modules

61c0e12

architkulkarni changed the title ~~[runtime env] [Doc] Add concepts, py_modules, and two basic workflows~~ [runtime env] [Doc] Add concepts and basic workflows Nov 19, 2021

add more details in cluster launcher section

15e8809

trim concepts

95c016c

doc build wasn't updated, retriggering

96de58f

edoakes approved these changes Nov 19, 2021

View reviewed changes

ericl approved these changes Nov 19, 2021

View reviewed changes

ericl merged commit 42085fd into ray-project:master Nov 19, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[runtime env] [Doc] Add concepts and basic workflows #20222

[runtime env] [Doc] Add concepts and basic workflows #20222

architkulkarni commented Nov 10, 2021 •

edited

Loading

richardliaw commented Nov 10, 2021

richardliaw commented Nov 10, 2021

architkulkarni commented Nov 10, 2021

architkulkarni Nov 10, 2021

rkooo567 Nov 10, 2021

rkooo567 Nov 14, 2021

richardliaw Nov 13, 2021 •

edited

Loading

rkooo567 Nov 14, 2021

architkulkarni Nov 18, 2021

rkooo567 Nov 14, 2021

rkooo567 Nov 14, 2021

architkulkarni Nov 18, 2021

rkooo567 Nov 14, 2021

rkooo567 Nov 14, 2021

architkulkarni Nov 18, 2021

rkooo567 Nov 14, 2021 •

edited

Loading

rkooo567 Nov 14, 2021

architkulkarni Nov 17, 2021

architkulkarni commented Nov 19, 2021

richardliaw commented Nov 19, 2021 via email

	Ray provides two features to specify these dependencies when working with a remote cluster: Runtime environments, and the Ray cluster launcher commands
	Ray provides two features to specify these dependencies when working with a Ray cluster: :ref:`runtime Environments<runtime-environments>`, and the :ref:`Ray cluster launcher commands <INSERT THE RIGHT LINK>`.


		- ``my_module # Assumes my_module has already been imported, e.g. via 'import my_module'``

		Note: Note: Setting options (1) and (3) per-task or per-actor is currently unsupported.

[runtime env] [Doc] Add concepts and basic workflows #20222

[runtime env] [Doc] Add concepts and basic workflows #20222

Conversation

architkulkarni commented Nov 10, 2021 • edited Loading

Why are these changes needed?

Related issue number

Checks

richardliaw commented Nov 10, 2021

richardliaw commented Nov 10, 2021

architkulkarni commented Nov 10, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richardliaw Nov 13, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rkooo567 Nov 14, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

architkulkarni commented Nov 19, 2021

richardliaw commented Nov 19, 2021 via email

architkulkarni commented Nov 10, 2021 •

edited

Loading

richardliaw Nov 13, 2021 •

edited

Loading

rkooo567 Nov 14, 2021 •

edited

Loading