docsy(v2): document Ray autoscaler_options (AutoscalerOptionsConfig) (#1463)

* docs: document Ray autoscaler_options / AutoscalerOptionsConfig

The Ray page documented enable_autoscaling, the on/off switch, but nothing that
configures it: no autoscaler_options row and no mention of
AutoscalerOptionsConfig anywhere. The generated reference already carries the
class (content/api-reference/integrations/ray/autoscaleroptionsconfig.md, added
by regen #1442), so only the narrative lagged. Its generated parameter table has
empty descriptions, since the generator does not parse the docstring field list,
which is why the narrative table is worth having.

New in v2.6.1: autoscaler_options has 0 occurrences in
v2.6.0:plugins/ray/src/flyteplugins/ray/task.py and 4 in v2.6.1.

Three behaviors documented because they are not inferable from the signature:

- autoscaler_options does not enable autoscaling. The Go plugin sets
  EnableInTreeAutoscaling and AutoscalerOptions as independent fields on the
  RayCluster spec (flyteorg/flyte ray.go:267-268), and KubeRay creates the
  sidecar only when in-tree autoscaling is on, so options alone do nothing.
- Unset fields keep KubeRay defaults rather than being zeroed:
  buildAutoscalerOptions applies idle_timeout_seconds only when > 0 and
  upscaling_mode only when not UNSPECIFIED (ray.go:208-236).
- resources takes tuples for request/limit pairs.

Upscaling mode uses the SDK spelling (CONSERVATIVE), not the KubeRay string the
plugin maps it to ("Conservative").

Must rebase onto #1458 before merge: it is editing the same section of this page.

Co-Authored-By: docsy <docsy@union.ai>
Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>

* docs: correct two false claims about autoscaler_options

The "unset keeps the KubeRay default" sentence was false for resources.
buildAutoscalerOptions assigns Resources inside an `err == nil` guard that
cannot fail: ToK8sResourceRequirements(nil) returns a non-nil empty struct
with a nil error (utils.go:53-55), so Resources is always non-nil whenever
autoscaler_options is passed. KubeRay then takes the replace branch at
pod.go:730-731 and overwrites its 500m/512Mi request and limit defaults
wholesale. env is assigned unguarded too, but KubeRay appends it behind a
len > 0 check (pod.go:739-740), so an empty env really is a no-op.

The upscaling_mode table listed four graded options. Ray maps DEFAULT and
AGGRESSIVE to the same upscaling_speed of 1000 and calls the second branch
redundant in its own source (autoscaling_config.py:107-116). UNSPECIFIED
never reaches the CR: ray.go:143 drops it. Only CONSERVATIVE differs, at
upscaling_speed 1, which caps a scale-up step at the current node count
rather than imposing a ceiling.

Co-Authored-By: docsy <docsy@union.ai>
Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>

* docs: make the autoscaler snippet runnable and state the idle timeout default

The block opens with an import line, so it reads as self-contained, but
flyte.Resources had nothing importing flyte. Matches the convention used
by the reusable-cluster snippet further down the page.

idle_timeout_seconds defaults to 60 in KubeRay (raycluster_types.go:226-228,
v1.6.2). An explicit 0 does not disable idle removal: buildAutoscalerOptions
guards the assignment on `> 0` (ray.go:140), so a 0 is dropped and the
KubeRay default applies.

Co-Authored-By: docsy <docsy@union.ai>
Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>

* docs: import flyte in the Ray configuration snippet too

Pre-existing, not introduced here, but fixing only the autoscaler snippet
left the page with two import-opening blocks where one imported flyte and
one did not. This block opens with an import line and calls
flyte.TaskEnvironment, so it has the same defect.

The page rule is now uniform: a block that opens with imports and uses
flyte.* imports flyte. The three blocks that open mid-expression are
fragments by design and are left alone.

Co-Authored-By: docsy <docsy@union.ai>
Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>

---------

Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>
Co-authored-by: docsy <docsy@union.ai>

Author: ppiegaze

content/integrations/ray/_index.md

@@ -51,6 +51,7 @@ image = (
 Create a `RayJobConfig` and pass it as `plugin_config` to a `TaskEnvironment`:
 
 ```python
+import flyte
 from flyteplugins.ray import HeadNodeConfig, RayJobConfig, WorkerNodeConfig
 
 ray_config = RayJobConfig(
@@ -76,6 +77,7 @@ ray_env = flyte.TaskEnvironment(
 | `worker_node_config` | `List[WorkerNodeConfig]` | **Required.** List of worker group configurations |
 | `head_node_config` | `HeadNodeConfig` | Head node configuration (optional) |
 | `enable_autoscaling` | `bool` | Enable Ray autoscaler (default: `False`) |
+| `autoscaler_options` | `AutoscalerOptionsConfig` | Tune the autoscaler sidecar. Has no effect unless `enable_autoscaling` is `True` |
 | `runtime_env` | `dict` | Ray runtime environment (pip packages, env vars, etc.) |
 | `address` | `str` | Connect to an existing Ray cluster instead of provisioning one |
 | `shutdown_after_job_finishes` | `bool` | Shut down the cluster after the job completes (default: `False`) |
@@ -118,6 +120,40 @@ ready: if the dashboard cannot start, `ray start --head` fails and KubeRay recyc
 the head pod in a loop. A head pod at 1 CPU and 1000Mi has been observed failing
 this way.
 
+### `AutoscalerOptionsConfig` parameters
+
+Setting `enable_autoscaling=True` runs the Ray autoscaler with KubeRay's defaults. Pass `autoscaler_options` to tune it:
+
+```python
+import flyte
+from flyteplugins.ray import AutoscalerOptionsConfig, RayJobConfig, WorkerNodeConfig
+
+ray_config = RayJobConfig(
+    worker_node_config=[
+        WorkerNodeConfig(group_name="ray-group", replicas=1, min_replicas=1, max_replicas=5)
+    ],
+    enable_autoscaling=True,
+    autoscaler_options=AutoscalerOptionsConfig(
+        upscaling_mode=AutoscalerOptionsConfig.UpscalingMode.CONSERVATIVE,
+        idle_timeout_seconds=120,
+        resources=flyte.Resources(cpu=("500m", "1"), memory=("512Mi", "1Gi")),
+    ),
+)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `upscaling_mode` | `AutoscalerOptionsConfig.UpscalingMode` | Rate limiting on adding nodes. `CONSERVATIVE` holds the number of pending worker pods to at most the current cluster size. `DEFAULT` and `AGGRESSIVE` are the same setting: no rate limit. Leaving the field unset, or passing `UNSPECIFIED`, also means no rate limit |
+| `idle_timeout_seconds` | `int` | Seconds a node may sit idle before the autoscaler removes it (default: 60). An explicit `0` is dropped and the default applies |
+| `image` | `str` | Container image for the autoscaler sidecar |
+| `env` | `Dict[str, str]` | Environment variables for the autoscaler container |
+| `resources` | `Resources` | Requests and limits for the autoscaler sidecar |
+
+Every field is optional. Leaving `upscaling_mode`, `idle_timeout_seconds`, `image`, or `env` unset keeps the KubeRay default. `resources` is the exception: whenever you pass `autoscaler_options`, whatever you give for `resources` replaces the sidecar's default 500m CPU and 512Mi memory requests and limits outright. Omit it and the sidecar runs with no requests or limits at all; set only a request and it also loses the default limits. Set `resources` explicitly, on both sides. It accepts tuples to set a request and a limit together, as in `flyte.Resources(cpu=("500m", "1"))`.
+
+> [!NOTE] The options do not switch autoscaling on
+> `autoscaler_options` only configures the autoscaler sidecar, and the sidecar is created only when `enable_autoscaling` is `True`. Passing options on their own changes nothing.
+
 ### Connecting to an existing cluster
 
 To connect to an existing Ray cluster instead of provisioning a new one, set the `address` parameter: