[docs] Add a Kubernetes and Ray scheduling orientation guide

[dstrodtman]

Description

Running Ray on Kubernetes involves two schedulers. Kubernetes places pods on machines, and Ray places tasks and actors on pods. The docs cover each layer well on its own, but nothing explains how they relate or which one to investigate when a workload doesn't start.

The closest existing page is k8s-autoscaler.md, but it's scoped to autoscaling and marked advanced, so a user debugging a pending actor is unlikely to find it.

This PR adds a user guide that:

• Names the two layers and what each one places.
• Documents how KubeRay derives Ray's logical resource capacity from the container spec, which is where the two layers most often disagree.
• Maps pod state to the layer worth investigating.
• Defers all mechanism to the existing Ray Core scheduling, RayCluster config, and autoscaler pages rather than restating them.

It also adds a pointer to the new page from the autoscaler guide.

The KubeRay resource-derivation details are drawn from user-guides/config.md (container limits, the CPU-request fallback as of KubeRay 1.3.0, integer rounding, and ignored memory and GPU requests).

Related issues

None. This came out of a documentation gap audit, not a filed issue.

Additional information

Not a duplicate

Searched open PRs against ray-project/ray for "kubernetes scheduling", "scheduling overview", and related area keywords. No open PR covers this. No existing page in doc/source joins the two scheduling layers.

Testing

Source verification against the KubeRay implementation. Every claim about how KubeRay derives Ray's logical capacity was checked against ray-operator/controllers/ray/common/pod.go in ray-project/kuberay, not just against the existing docs:

• generateRayStartCommand reads resource.Limits[ResourceCPU] for num-cpus, and falls back to resource.Requests[ResourceCPU] when the limit is zero.
• The CPU-request fallback landed in kuberay commit ba50bfa8 (Add 0.5 release notes. #2365). It's absent from v1.2.1 and present in v1.3.0, which confirms the "starting with KubeRay 1.3.0" attribution.
• Integer rounding follows from Quantity.Value(), which rounds up away from zero, so a 500m limit becomes one logical CPU.
• Memory reads Limits[ResourceMemory] only, with no request fallback, and accelerators go through addWellKnownAcceleratorResources(rayStartParams, resource.Limits). Both confirm that requests are ignored for memory and GPU.

Other checks:

• vale doc/source/cluster/kubernetes/user-guides/scheduling.md — remaining errors are Vale.Spelling on "tolerations" and "autoscalers" (standard terms used throughout the existing KubeRay docs, absent from the Vale vocabulary) and one Google.OxfordComma false positive on a two-item disjunction. The existing k8s-autoscaler.md reports a comparable baseline.
• pre-commit run on the staged files — every hook reports "no files to check". No pre-commit hook currently covers Markdown under doc/source/.
• Every {ref} target used on the page was verified to exist by grepping for its label definition.
• A full Sphinx docs build was not run locally. Link resolution and toctree wiring rely on CI. Flagging this explicitly rather than implying broader verification than was performed.

Self-review findings already fixed

A critical pass before requesting review caught that the page claimed Ray integrates with four batch schedulers. There are five: the kubernetes-sigs/scheduler-plugins integration provides gang scheduling for RayCluster through the PodGroup API as of KubeRay v1.4.0. Corrected, with the fifth link added.

AI assistance

AI assistance was used to draft this page. The content is grounded in the repository sources cited above rather than generated from prior knowledge. It still needs a final human review pass before it should be considered ready, which is why this is opened as a draft.