[DOC-127] MVP for OSS Ray labels #54254

dstrodtman · 2025-07-01T20:28:16Z

Why are these changes needed?

Related issue number

Checks

I've signed off every commit(by using the -s flag, i.e., git commit -s) in this PR.
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 added any new APIs to the API Reference. For example, if I added a
  method in Tune, I've added it in doc/source/tune/api/ under the
  corresponding .rst file.
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 :(

github-actions · 2025-07-16T00:41:33Z

This pull request has been automatically marked as stale because it has not had
any activity for 14 days. It will be closed in another 14 days if no further activity occurs.
Thank you for your contributions.

You can always ask for help on our discussion forum or Ray's public slack channel.

If you'd like to keep this open, just leave any comment, and the stale label will be removed.

github-actions · 2025-07-30T00:42:15Z

This pull request has been automatically closed because there has been no more activity in the 14 days
since being marked stale.

Please feel free to reopen or open a new pull request if you'd still like this to be addressed.

Again, you can always ask for help on our discussion forum or Ray's public slack channel.

Thanks again for your contribution!

MengjinYan · 2025-08-14T18:30:38Z

Not stale

MengjinYan · 2025-08-14T20:03:36Z

doc/source/ray-core/scheduling/index.rst

+
+- NodeAffinitySchedulingStrategy when `soft=false`. Use the default `ray.io/node-id` label instead.
+- The `accelerator_type` option for tasks and actors. Use the default `ray.io/accelerator-type` label instead.
+- Custom resources such as the `special_hardware` pattern. Use custom labels instead.


Nit: Just to be more specific, the pattern that we want to replace is mainly using custom resources as labels, mentioned in the section here.

Pointing this out mainly because the custom resource can still be useful when the resources are used as resources with a quantity attached.

Updating this to call out this behavior AND change the existing resources docs to point to labels in this instance.

doc/source/ray-core/scheduling/labels.md

MengjinYan

Added one more update regarding the autoscaler support.

doc/source/ray-core/scheduling/labels.md

dstrodtman · 2025-09-19T19:48:16Z

doc/source/ray-core/scheduling/index.rst

+
+- NodeAffinitySchedulingStrategy when `soft=false`. Use the default `ray.io/node-id` label instead.
+- The `accelerator_type` option for tasks and actors. Use the default `ray.io/accelerator-type` label instead.
+- Custom resources such as the `special_hardware` pattern. Use custom labels instead.


Updating this to call out this behavior AND change the existing resources docs to point to labels in this instance.

doc/source/ray-core/scheduling/labels.md

dstrodtman · 2025-09-19T20:07:14Z

doc/source/ray-core/scheduling/labels.md

+
+You can add custom labels to your nodes using the `--labels` or `--labels-file` parameter when running `ray start`. See the following examples:
+
+<!-- INSERT EXAMPLES -->


@janetli19 @MengjinYan Still haven't really seen much here beyond what you can accomplish with defaults.

Maybe an example where we mark something like CPU size to allow users to specify tasks to specific VM types in a heterogenous CPU environment?

Could use help coding something up as I'm pretty novice at Ray.

Just noticed that's exactly the example we give below. So here we just need to show define the config for that value?

I think one example we can give is to set cpu family to indicate that the node is with AMD CPU.

# Start a head node with label name "cpu-family" & value "amd" ray start --head --labels="cpu-family=amd"

doc/source/ray-core/scheduling/labels.md

MengjinYan

Just one last nit comment and a missed code example.

doc/source/ray-core/scheduling/index.rst

doc/source/ray-core/scheduling/labels.md

MengjinYan · 2025-09-30T18:20:39Z

doc/source/ray-core/scheduling/labels.md

+
+(defaults)=
+## Default node labels 
+


By the offline discussion, we might want to add some disclaimer similar to the following:

Ray reserves all labels ray.io and anyscale.io namespaces.

anyscale.com?

should be anyscale.com not io

why would Ray reserve anyscale.com labels though?

Actually, that's a good point. From Ray's perspective, we should only reserve ray.io namespace.

this reminds me we should add validation that users can't set ray.io/ labels if we haven't already @ryanaoleary

@edoakes We previously had that for NodeLabelSchedulingPolic here, but we loosened this restriction for labels passed in with the new API (--labels and --labels-file) since I think we discussed passing labels from KubeRay with the ray.io/ prefix in the rayStartParams for autoscaling. For ray-project/kuberay#4106, should we require that labels passed to the top-level Labels field can't begin with ray.io/?

@MengjinYan LMK if this needs to happen for this release or you want to add later.

@dstrodtman I think for this release, we should still say that ray.io is reserved but we probably don't need to mention user shouldn't set ray.io label if we haven't set it already.

ryanaoleary · 2025-10-03T09:17:40Z

doc/source/ray-core/scheduling/labels.md

+Autoscaler V2 supports label-based scheduling. To enable autoscaler to scale up nodes to fulfill label requirements, you need to create multiple worker groups for different label requirement combinations and specify the all the corresponding labels in the `rayStartParams` field in the Ray cluster configuration. For example:
+
+```{python}
+    rayStartParams: {


When ray-project/kuberay#4106 is merged we can direct users to specify the top-level Labels field under the worker or head group with their desired labels with KubeRay v1.5+, but for now rayStartParams is the only option.

@MengjinYan LMK if this needs to happen for this release or you want to add later.

@dstrodtman I think we can add it later.

ryanaoleary

Read through and everything LGTM!

dstrodtman · 2025-10-03T17:53:16Z

This is passing in my local build, and I think ready to merge.

Note there's an open PR to resolve some docs issues that might fail some tests here: #57163

doc/source/ray-core/scheduling/labels.md

MengjinYan

One last suggestion on the namespace reservation. Thanks for fixing the build error!

doc/source/ray-core/scheduling/labels.md

Co-authored-by: Mengjin Yan <[email protected]> Signed-off-by: Douglas Strodtman <[email protected]>

MengjinYan · 2025-10-08T01:54:32Z

@jjyao @edoakes @angelinalg ping to merge

(cherry picked from commit 44a9732)

(cherry picked from commit 44a9732) Co-authored-by: Douglas Strodtman <[email protected]>

Signed-off-by: Josh Kodi <[email protected]>

dstrodtman requested a review from a team as a code owner July 1, 2025 20:28

edoakes requested review from MengjinYan, edoakes and ryanaoleary July 1, 2025 20:53

github-actions bot added the stale The issue is stale. It will be closed within 7 days unless there are further conversation label Jul 16, 2025

github-actions bot closed this Jul 30, 2025

MengjinYan reopened this Aug 14, 2025

MengjinYan requested a review from a team as a code owner August 14, 2025 18:30

github-actions bot added unstale A PR that has been marked unstale. It will not get marked stale again if this label is on it. and removed stale The issue is stale. It will be closed within 7 days unless there are further conversation labels Aug 15, 2025

ray-gardener bot added the core Issues that should be addressed in Ray Core label Aug 15, 2025

MengjinYan reviewed Sep 15, 2025

View reviewed changes

MengjinYan reviewed Sep 17, 2025

View reviewed changes

doc/source/ray-core/scheduling/labels.md Outdated Show resolved Hide resolved

dstrodtman commented Sep 19, 2025

View reviewed changes

angelinalg reviewed Sep 20, 2025

View reviewed changes

doc/source/ray-core/scheduling/labels.md Outdated Show resolved Hide resolved

doc/source/ray-core/scheduling/labels.md Outdated Show resolved Hide resolved

doc/source/ray-core/scheduling/labels.md Show resolved Hide resolved

MengjinYan mentioned this pull request Sep 24, 2025

[Core] Ray Label Selector API Implementation Tracker #51564

Open

32 tasks

dstrodtman added go add ONLY when ready to merge, run all tests and removed go add ONLY when ready to merge, run all tests labels Sep 25, 2025

dstrodtman commented Sep 25, 2025

View reviewed changes

doc/source/ray-core/scheduling/labels.md Outdated Show resolved Hide resolved

This comment was marked as outdated.

Sign in to view

dstrodtman added the go add ONLY when ready to merge, run all tests label Sep 25, 2025

MengjinYan reviewed Sep 26, 2025

View reviewed changes

doc/source/ray-core/scheduling/index.rst Outdated Show resolved Hide resolved

doc/source/ray-core/scheduling/labels.md Show resolved Hide resolved

MengjinYan reviewed Sep 30, 2025

View reviewed changes

ryanaoleary reviewed Oct 3, 2025

View reviewed changes

ryanaoleary approved these changes Oct 3, 2025

View reviewed changes

dstrodtman commented Oct 3, 2025

View reviewed changes

doc/source/ray-core/scheduling/labels.md Outdated Show resolved Hide resolved

dstrodtman requested review from a team, SongGuyang, WangTaoTheTonic, aslonnie, kfstorm and raulchen as code owners October 6, 2025 20:35

Merge branch 'master' into doc-127-ray-labels

64c1379

aslonnie removed request for a team and aslonnie October 6, 2025 20:37

dstrodtman and others added 3 commits October 7, 2025 11:11

bad x-ref

aa2d496

Merge branch 'master' into doc-127-ray-labels

29535ea

Merge branch 'master' into doc-127-ray-labels

a1cef9c

MengjinYan approved these changes Oct 7, 2025

View reviewed changes

doc/source/ray-core/scheduling/labels.md Outdated Show resolved Hide resolved

dstrodtman and others added 2 commits October 7, 2025 13:38

Update doc/source/ray-core/scheduling/labels.md

a5a4e46

Co-authored-by: Mengjin Yan <[email protected]> Signed-off-by: Douglas Strodtman <[email protected]>

Merge branch 'master' into doc-127-ray-labels

dfb1fa9

jjyao merged commit 44a9732 into master Oct 8, 2025
6 checks passed

jjyao deleted the doc-127-ray-labels branch October 8, 2025 04:56

MengjinYan pushed a commit to MengjinYan/ray that referenced this pull request Oct 8, 2025

[DOC-127] MVP for OSS Ray labels (ray-project#54254)

06b7dc3

(cherry picked from commit 44a9732)

aslonnie pushed a commit that referenced this pull request Oct 9, 2025

[DOC-127] Cherry-pick (#54254): MVP for OSS Ray labels (#57547)

fc4510f

(cherry picked from commit 44a9732) Co-authored-by: Douglas Strodtman <[email protected]>

liulehui pushed a commit to liulehui/ray that referenced this pull request Oct 9, 2025

[DOC-127] MVP for OSS Ray labels (ray-project#54254)

cff6455

joshkodi pushed a commit to joshkodi/ray that referenced this pull request Oct 13, 2025

[DOC-127] MVP for OSS Ray labels (ray-project#54254)

f588ccf

Signed-off-by: Josh Kodi <[email protected]>


		You can add custom labels to your nodes using the `--labels` or `--labels-file` parameter when running `ray start`. See the following examples:

		<!-- INSERT EXAMPLES -->

[DOC-127] MVP for OSS Ray labels #54254

[DOC-127] MVP for OSS Ray labels #54254

Conversation

dstrodtman commented Jul 1, 2025

Why are these changes needed?

Related issue number

Checks

Uh oh!

github-actions bot commented Jul 16, 2025

Uh oh!

github-actions bot commented Jul 30, 2025

Uh oh!

MengjinYan commented Aug 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MengjinYan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

MengjinYan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MengjinYan Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryanaoleary Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryanaoleary left a comment

Choose a reason for hiding this comment

Uh oh!

MengjinYan Oct 3, 2025 •

edited

Loading

ryanaoleary Oct 3, 2025 •

edited

Loading