Update ResourceFlavor site documentation #4500

ChristianZaccaria · 2025-03-05T10:29:57Z

What type of PR is this?

/kind documentation

What this PR does / why we need it:

Update the ResourceFlavor site documentation to enhance readability and ensure a smoother user experience.

Which issue(s) this PR fixes:

Fixes #4499

Special notes for your reviewer:

Does this PR introduce a user-facing change?

NONE

k8s-ci-robot · 2025-03-05T10:30:08Z

Hi @ChristianZaccaria. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

netlify · 2025-03-05T10:30:16Z

✅ Deploy Preview for kubernetes-sigs-kueue ready!

Name	Link
🔨 Latest commit	`7865c80`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-sigs-kueue/deploys/67e2df5ca338650008b27683
😎 Deploy Preview	https://deploy-preview-4500--kubernetes-sigs-kueue.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

mbobrovskyi · 2025-03-05T10:39:47Z

/ok-to-test

mbobrovskyi · 2025-03-05T10:40:08Z

/release-note-edit

NONE

mimowo · 2025-03-05T10:54:31Z

/assgin @gabesaba
tentatively

kannon92 · 2025-03-05T18:16:34Z

site/content/en/docs/concepts/resource_flavor.md

+
+**Requires Kubernetes 1.23 or newer**
+
+This approach may be best for teams that wish to schedule pods onto the appropriate nodes automatically. However, a limitation arises when multiple types of specialized hardware are present, such as two different nvidia.com/gpu resources present in the cluster, i.e., T4 and A100 GPUs. The system may not differentiate between them, meaning the pods could be scheduled on any of both types of hardware.


TBH I tend to ask people to use new lines for each sentence as this gets hard to read in markdown.

Suggested change

This approach may be best for teams that wish to schedule pods onto the appropriate nodes automatically. However, a limitation arises when multiple types of specialized hardware are present, such as two different nvidia.com/gpu resources present in the cluster, i.e., T4 and A100 GPUs. The system may not differentiate between them, meaning the pods could be scheduled on any of both types of hardware.

This approach may be best for teams that wish to schedule pods onto the appropriate nodes automatically.

However, a limitation arises when multiple types of specialized hardware are present, such as two different nvidia.com/gpu resources present in the cluster, i.e., T4 and A100 GPUs.

The system may not differentiate between them, meaning the pods could be scheduled on any of both types of hardware.

Yes, I understand your point with Markdown. These docs will ultimately be read from the website which makes sense to have them in a single parragraph. - I could do a 'break' on each sentence, while keeping it in the same parragraph if that suits? - Please see latest commit as an example

Yea that is great.

kannon92 · 2025-03-05T18:16:56Z

site/content/en/docs/concepts/resource_flavor.md

+
+This approach may be best for teams that wish to schedule pods onto the appropriate nodes automatically. However, a limitation arises when multiple types of specialized hardware are present, such as two different nvidia.com/gpu resources present in the cluster, i.e., T4 and A100 GPUs. The system may not differentiate between them, meaning the pods could be scheduled on any of both types of hardware.
+
+To associate a ResourceFlavor with a subset of nodes of your cluster, you can configure the `.spec.nodeLabels` field with matching node labels that uniquely identify the nodes. If you are using [cluster autoscaler](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler) (or equivalent controllers), make sure that the controller is configured to add those labels when adding new nodes.


Suggested change

To associate a ResourceFlavor with a subset of nodes of your cluster, you can configure the `.spec.nodeLabels` field with matching node labels that uniquely identify the nodes. If you are using [cluster autoscaler](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler) (or equivalent controllers), make sure that the controller is configured to add those labels when adding new nodes.

To associate a ResourceFlavor with a subset of nodes of your cluster, you can configure the `.spec.nodeLabels` field with matching node labels that uniquely identify the nodes.

If you are using [cluster autoscaler](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler) (or equivalent controllers), make sure that the controller is configured to add those labels when adding new nodes.

kannon92 · 2025-03-05T18:18:12Z

site/content/en/docs/concepts/resource_flavor.md

+A sample ResourceFlavor of this type looks like the following:

 ```yaml
 apiVersion: kueue.x-k8s.io/v1beta1


Should we move this to a samples and use that here? That follows our code in workloads.

Do you mean like this for example?

kueue/site/content/en/docs/tasks/manage/monitor_pending_workloads/pending_workloads_in_status.md

Lines 38 to 42 in 92e194d

To install a simple setup of cluster queue, run the following command:

```shell

kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/kueue/main/site/static/examples/admin/single-clusterqueue-setup.yaml

```

My only concern with this, is that then the yaml and the fields are then not displayed in the docs. I could add both, the yaml and the file that can be applied. Does that sound good?

Something like: https://github.com/kubernetes-sigs/kueue/blob/main/site/content/en/docs/tasks/run/jobsets.md

Where we define the sample yaml in the static folder and import it in the docs. The website renders the YAML but we also have examples users can apply without reading the website.

Ohh I understand. Hmm, for this to be a "working" ResourceFlavor, we would need to know which nodeLabels to use in the YAML. nodeLabels being used to associate the ResourceFlavor with the node in the cluster. A generic one wouldn't work, so the user can't just apply the file and see real results. - The only way I see, is to instruct the user to add the label to the node before applying the file.

I think adding what you have for the example is sufficient for the website.

Added that now, including the empty flavor. Thanks :)

kannon92 · 2025-03-11T16:17:48Z

/lgtm

Nice addition!

/assign @mimowo @tenzen-y

k8s-ci-robot · 2025-03-11T16:17:57Z

LGTM label has been added.

Details

Git tree hash: 9cc9eb2207ce1b3225ea13fe5512351e9560a6fe

mimowo · 2025-03-20T09:25:25Z

/assign @gabesaba
for an additional pass

gabesaba

Changes look great! Only a couple of nits

gabesaba · 2025-03-25T11:01:18Z

site/content/en/docs/concepts/resource_flavor.md

+   This occurs if the Workload didn't specify the `ResourceFlavor` labels already as part of its nodeSelector.
+
+     For example, for a [batch/v1.Job](https://kubernetes.io/docs/concepts/workloads/controllers/job/), Kueue adds the labels to the `.spec.template.spec.nodeSelector` field.
+     This guarantees that the workload's Pods can only be scheduled on the nodes targeted by the flavor that Kueue assigned to the Workload.


nit: consistently capitalize Workload - here and elsewhere. I have a preference for Upper Case

Updated, thank you!

gabesaba · 2025-03-25T11:08:29Z

site/content/en/docs/concepts/resource_flavor.md

+{{< include "examples/admin/resource-flavor-tolerations.yaml" "yaml" >}}
+
+When defining a ResourceFlavor as above, you can set the following values:
+- The `.metadata.name` field to reference a ResourceFlavor from a [ClusterQueue](/docs/concepts/cluster_queue) in the `.spec.resourceGroups[*].flavors[*].name` field.


metadata.name is required, but it sounds optional here (and below in the resource-flavor-taints section).

Perhaps add something about how name is used to uniquely identify a ResourceFlavor (as you did with ClusterQueue)

I've made this more explicit, thank you!

gabesaba · 2025-03-25T11:09:04Z

site/content/en/docs/concepts/resource_flavor.md

+{{< include "examples/admin/resource-flavor-taints.yaml" "yaml" >}}
+
+When defining a ResourceFlavor as above, you can set the following values:
+- The `.metadata.name` field to reference a ResourceFlavor from a [ClusterQueue](/docs/concepts/cluster_queue) in the `.spec.resourceGroups[*].flavors[*].name` field.


see comment above

gabesaba · 2025-03-26T09:25:18Z

/lgtm

k8s-ci-robot · 2025-03-26T09:25:25Z

LGTM label has been added.

Details

Git tree hash: dd5dcc08356b1f5b6a4ead41e43c8e50de1d0b50

mimowo · 2025-03-26T09:46:53Z

I think docs is a super important area for adoption, but often neglected, unfortunately.

Thank you for keeping the lights on!

/approve
/cherry-pick website

k8s-infra-cherrypick-robot · 2025-03-26T09:46:55Z

@mimowo: once the present PR merges, I will cherry-pick it on top of website in a new PR and assign it to you.

Details

In response to this:

I think docs is a super important area for adoption, but often neglected, unfortunately.

Thank you for keeping the lights on!

/approve
/cherry-pick website

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

k8s-ci-robot · 2025-03-26T09:47:00Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: ChristianZaccaria, mimowo

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~site/OWNERS~~ [mimowo]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

ChristianZaccaria · 2025-03-26T09:55:25Z

@mimowo thank you for the continuous support and encouragement! Happy to contribute in any way I can :)

k8s-infra-cherrypick-robot · 2025-03-26T10:03:37Z

@mimowo: new pull request created: #4795

Details

In response to this:

I think docs is a super important area for adoption, but often neglected, unfortunately.

Thank you for keeping the lights on!

/approve
/cherry-pick website

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

k8s-ci-robot requested review from gabesaba and mimowo March 5, 2025 10:30

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Mar 5, 2025

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Mar 5, 2025

ChristianZaccaria mentioned this pull request Mar 5, 2025

Update ResourceFlavor site documentation #4499

Closed

ChristianZaccaria force-pushed the resourceflavor-docs branch from 084fdf4 to c2e2e0f Compare March 5, 2025 10:32

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Mar 5, 2025

k8s-ci-robot added release-note-none Denotes a PR that doesn't merit a release note. and removed do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. labels Mar 5, 2025

kannon92 reviewed Mar 5, 2025

View reviewed changes

ChristianZaccaria requested a review from kannon92 March 6, 2025 15:50

ChristianZaccaria force-pushed the resourceflavor-docs branch from 18f71de to 30778a5 Compare March 10, 2025 10:11

k8s-ci-robot assigned mimowo, tenzen-y and kannon92 Mar 11, 2025

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 11, 2025

k8s-ci-robot assigned gabesaba Mar 20, 2025

gabesaba reviewed Mar 25, 2025

View reviewed changes

ChristianZaccaria added 4 commits March 25, 2025 16:52

Update ResourceFlavor documentation

7a18ef2

Re-format ResourceFlavour markdown documentation

3791933

Formatting Markdown

86ffb50

Use Hugo shortcode to include YAML examples in ResourceFlavor site.

7865c80

ChristianZaccaria force-pushed the resourceflavor-docs branch from 30778a5 to 7865c80 Compare March 25, 2025 16:52

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 25, 2025

k8s-ci-robot requested review from gabesaba and tenzen-y March 25, 2025 16:52

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 26, 2025

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Mar 26, 2025

k8s-ci-robot merged commit 3df47f0 into kubernetes-sigs:main Mar 26, 2025
7 checks passed

k8s-ci-robot added this to the v0.12 milestone Mar 26, 2025

k8s-infra-cherrypick-robot mentioned this pull request Mar 26, 2025

[website] Update ResourceFlavor site documentation #4795

Merged


		Requires Kubernetes 1.23 or newer

		This approach may be best for teams that wish to schedule pods onto the appropriate nodes automatically. However, a limitation arises when multiple types of specialized hardware are present, such as two different nvidia.com/gpu resources present in the cluster, i.e., T4 and A100 GPUs. The system may not differentiate between them, meaning the pods could be scheduled on any of both types of hardware.


		This approach may be best for teams that wish to schedule pods onto the appropriate nodes automatically. However, a limitation arises when multiple types of specialized hardware are present, such as two different nvidia.com/gpu resources present in the cluster, i.e., T4 and A100 GPUs. The system may not differentiate between them, meaning the pods could be scheduled on any of both types of hardware.

		To associate a ResourceFlavor with a subset of nodes of your cluster, you can configure the `.spec.nodeLabels` field with matching node labels that uniquely identify the nodes. If you are using [cluster autoscaler](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler) (or equivalent controllers), make sure that the controller is configured to add those labels when adding new nodes.

	To associate a ResourceFlavor with a subset of nodes of your cluster, you can configure the `.spec.nodeLabels` field with matching node labels that uniquely identify the nodes. If you are using [cluster autoscaler](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler) (or equivalent controllers), make sure that the controller is configured to add those labels when adding new nodes.
	To associate a ResourceFlavor with a subset of nodes of your cluster, you can configure the `.spec.nodeLabels` field with matching node labels that uniquely identify the nodes.
	If you are using [cluster autoscaler](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler) (or equivalent controllers), make sure that the controller is configured to add those labels when adding new nodes.

	To install a simple setup of cluster queue, run the following command:

	```shell
	kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/kueue/main/site/static/examples/admin/single-clusterqueue-setup.yaml
	```

Update ResourceFlavor site documentation #4500

Update ResourceFlavor site documentation #4500

Uh oh!

Conversation

ChristianZaccaria commented Mar 5, 2025 • edited by k8s-ci-robot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for your reviewer:

Does this PR introduce a user-facing change?

Uh oh!

k8s-ci-robot commented Mar 5, 2025

Uh oh!

netlify bot commented Mar 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for kubernetes-sigs-kueue ready!

Uh oh!

mbobrovskyi commented Mar 5, 2025

Uh oh!

mbobrovskyi commented Mar 5, 2025

Uh oh!

mimowo commented Mar 5, 2025

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!

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!

kannon92 commented Mar 11, 2025

Uh oh!

k8s-ci-robot commented Mar 11, 2025

Uh oh!

mimowo commented Mar 20, 2025

Uh oh!

gabesaba left a comment

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!

gabesaba commented Mar 26, 2025

Uh oh!

k8s-ci-robot commented Mar 26, 2025

Uh oh!

mimowo commented Mar 26, 2025

Uh oh!

k8s-infra-cherrypick-robot commented Mar 26, 2025

Uh oh!

k8s-ci-robot commented Mar 26, 2025

Uh oh!

ChristianZaccaria commented Mar 26, 2025

Uh oh!

Uh oh!

k8s-infra-cherrypick-robot commented Mar 26, 2025

Uh oh!

Reviewers

Assignees

ChristianZaccaria commented Mar 5, 2025 •

edited by k8s-ci-robot

Loading

netlify bot commented Mar 5, 2025 •

edited

Loading