[Doc] Make runtimeEnvYAML more prominent in docs (#44326)

When using Ray Jobs, it's better to specify the runtime_env in the Job spec, rather than in ray.init() in the entrypoint script. The reason is that it's simpler; in the first case the entrypoint script runs in the runtime env (as well as any tasks/actors), whereas in the second case only the tasks and actors run in the runtime env.

Some users are still using runtime_env in ray.init(). One possible reason is that it's not prominent enough in the docs. This PR adds a reference to KubeRay RayJob in the Ray Core runtime env docs, and also adds a code snippet to make it more friendly for users to copy and paste.

---------

Signed-off-by: Archit Kulkarni <[email protected]>
Co-authored-by: angelinalg <[email protected]>

doc/source/cluster/kubernetes/getting-started/rayjob-quick-start.md

@@ -30,7 +30,20 @@ To understand the following content better, you should understand the difference
  * `rayClusterSpec` - Defines the **RayCluster** custom resource to run the Ray job on.
 * Ray job configuration
  * `entrypoint` - The submitter runs `ray job submit --address ... --submission-id ... -- $entrypoint` to submit a Ray job to the RayCluster.
- * `runtimeEnvYAML` (Optional): A runtime environment that describes the dependencies the Ray job needs to run, including files, packages, environment variables, and more. Provide the configuration as a multi-line YAML string. See {ref}`Runtime Environments <runtime-environments>` for more details. _(New in KubeRay version 1.0.0)_
+ * `runtimeEnvYAML` (Optional): A runtime environment that describes the dependencies the Ray job needs to run, including files, packages, environment variables, and more. Provide the configuration as a multi-line YAML string.
+ Example:
+
+ ```yaml
+ spec:
+ runtimeEnvYAML: |
+ pip:
+ - requests==2.26.0
+ - pendulum==2.1.2
+ env_vars:
+ KEY: "VALUE"
+ ```
+
+ See {ref}`Runtime Environments <runtime-environments>` for more details. _(New in KubeRay version 1.0.0)_
  * `jobId` (Optional): Defines the submission ID for the Ray job. If not provided, KubeRay generates one automatically. See {ref}`Ray Jobs CLI API Reference <ray-job-submission-cli-ref>` for more details about the submission ID.
  * `metadata` (Optional): See {ref}`Ray Jobs CLI API Reference <ray-job-submission-cli-ref>` for more details about the `--metadata-json` option.
  * `entrypointNumCpus` / `entrypointNumGpus` / `entrypointResources` (Optional): See {ref}`Ray Jobs CLI API Reference <ray-job-submission-cli-ref>` for more details.

doc/source/ray-core/handling-dependencies.rst

@@ -118,7 +118,7 @@ There are two primary scopes for which you can specify a runtime environment:
 Specifying a Runtime Environment Per-Job
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can specify a runtime environment for your whole job, whether running a script directly on the cluster, using the :ref:`Ray Jobs API <jobs-overview>`:
+You can specify a runtime environment for your whole job, whether running a script directly on the cluster, using the :ref:`Ray Jobs API <jobs-overview>`, or submitting a :ref:`KubeRay RayJob <kuberay-rayjob-quickstart>`:
 
 .. literalinclude:: /ray-core/doc_code/runtime_env_example.py
  :language: python
@@ -142,6 +142,18 @@ You can specify a runtime environment for your whole job, whether running a scri
  # Option 3: Using Ray Jobs API (CLI). (Note: can use --runtime-env to pass a YAML file instead of an inline JSON string.)
  $ ray job submit --address="http:https://<head-node-ip>:8265" --runtime-env-json='{"working_dir": "/data/my_files", "pip": ["emoji"]}' -- python my_ray_script.py
 
+.. code-block:: yaml
+
+ # Option 4: Using KubeRay RayJob. You can specify the runtime environment in the RayJob YAML manifest.
+ # [...]
+ spec:
+ runtimeEnvYAML: |
+ pip:
+ - requests==2.26.0
+ - pendulum==2.1.2
+ env_vars:
+ KEY: "VALUE"
+
 .. warning::
 
  Specifying the ``runtime_env`` argument in the ``submit_job`` or ``ray job submit`` call ensures the runtime environment is installed on the cluster before the entrypoint script is run.