Document labels, annotations and taints for JobSet #47383

Adarsh-verma-14 · 2024-08-07T17:11:44Z

Adding labels and annotation for JobSet in https://github.com/kubernetes/website/blob/main/content/en/docs/reference/labels-annotations-taints/_index.md

Fixes #47373

/language en

Adarsh-verma-14 · 2024-08-07T17:14:41Z

Hi @sftim ,could you review on these changes if anythings need to change let me know .

netlify · 2024-08-07T17:19:44Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`fc4c0c7`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/6703725bf718730008f25363
😎 Deploy Preview	https://deploy-preview-47383--kubernetes-io-main-staging.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.

kannon92 · 2024-08-08T16:03:22Z

cc @ahg-g @danielvegamyhre

content/en/docs/reference/labels-annotations-taints/_index.md

sftim · 2024-08-08T16:09:14Z

content/en/docs/reference/labels-annotations-taints/_index.md

+
+Used on: Jobs, Pods
+
+This label is used to store the name of the JobSet to which a job or pod belongs.


Suggested change

This label is used to store the name of the JobSet to which a job or pod belongs.

This label is used to store the name of the JobSet to which a Job or Pod belongs.

JobSet is an extension API that you can deploy into your Kubernetes cluster.

I have done this change as suggested.

content/en/docs/reference/labels-annotations-taints/_index.md

danielvegamyhre

Thanks for working on this @kannon92, I added a couple comments

content/en/docs/reference/labels-annotations-taints/_index.md

kannon92 · 2024-08-08T17:07:11Z

Thanks for working on this @kannon92, I added a couple comments

@Adarsh-verma-14 is the one who worked on this.

sftim · 2024-08-08T17:07:20Z

content/en/docs/reference/labels-annotations-taints/_index.md

+Type: Annotation
+
+Example: `alpha.jobset.sigs.k8s.io/no-schedule: "true"`
+
+Used on: Jobs
+
+This annotation prevents the job from being scheduled.


Suggested change

Type: Annotation

Example: `alpha.jobset.sigs.k8s.io/no-schedule: "true"`

Used on: Jobs

This annotation prevents the job from being scheduled.

Type: Taint

Example: `alpha.jobset.sigs.k8s.io/no-schedule: NoSchedule`

Used on: Nodes

The JobSet controller uses this taint to support its node labeling exclusive placement strategy.

JobSet is an extension API that you can deploy into your Kubernetes cluster.

(aside: I'd rename this to jobset.sigs.k8s.io/exclusive-use or jobset.kubernetes.io/exclusive-use)

I have done this changes but is there need to change name (jobset.sigs.k8s.io/exclusive-use or jobset.kubernetes.io/exclusive-use) let me know.

sftim · 2024-08-08T17:08:58Z

There is also one taint, so:

/retitle Document labels, annotations and taints for JobSet

sftim · 2024-08-08T17:09:07Z

/sig apps

danielvegamyhre · 2024-08-08T21:04:09Z

Thanks for working on this @kannon92, I added a couple comments

@Adarsh-verma-14 is the one who worked on this.

Woops, sorry about that @Adarsh-verma-14! Thanks for the contribution :)

sftim

Very nearly LGTM for docs

content/en/docs/reference/labels-annotations-taints/_index.md

sftim · 2024-08-11T23:21:45Z

content/en/docs/reference/labels-annotations-taints/_index.md

+
+Used on: JobSets
+
+This annotation acts as a flag. When set, the JobSet controller injects nodeSelectors for the `JobSetNameKey` label (e.g., `jobset.sigs.k8s.io/jobset-name`) to ensure exclusive job placement per topology.


I think we could tidy the explanation here.

This annotation acts as a flag. When it's set, the JobSet controller adds nodeSelectors for the JobSetNameKey label (like jobset.sigs.k8s.io/jobset-name), so jobs are placed according to a specific topology.

@sftim it would be better or not ?

What does the JobSet controller mutate based on this annotation?

JobSets

Jobs

Pods
?

It's not clear.

got it your point @sftim , I will update this accordingly.

I have update this accordingly. Now, i think is clear. PTAL!!

tengqm · 2024-09-22T02:35:50Z

Sorry, I'm against this change because

JobSet is not something we can get from vanilla Kubernetes. Yes. The mentioned labels or annotations all carry the k8s.io domain name, which is reserved. But this doesn't mean that they are "official".
We could add notes (or warnings) to all these labels or annotations -- you can use them only when you deployed the jobset related manifests. They are not available by default on your cluster.
Or, better yet, document these labels/annotations on a different page. The current page is already lengthy (>2400 lines). Without differentiating builtin labels/annotations from those from other projects, we will end up with a huge file pretty soon.

sftim · 2024-09-22T11:48:27Z

Thanks for the comment @tengqm, but JobSet is part of the Kubernetes project. I don't think we should force SIG Apps to reorganize a long page just to register their labels and annotations, even if that work is a good idea for the long term.

danielvegamyhre

Looks good, just a couple more small changes

danielvegamyhre · 2024-09-27T01:40:58Z

content/en/docs/reference/labels-annotations-taints/_index.md

+
+Used on: Jobs, Pods
+
+This label/annotation is used to store the name of the JobSet to which a Job or Pod belongs.


Suggested change

This label/annotation is used to store the name of the JobSet to which a Job or Pod belongs.

This label/annotation is used to store the name of the JobSet that a Job or Pod belongs to.

content/en/docs/reference/labels-annotations-taints/_index.md

danielvegamyhre · 2024-09-29T16:09:19Z

/lgtm for JobSet

@sftim this is ready for SIG docs review

sftim

There's no API kind called ReplicatedJob, right?

If that's true, try these changes. We main use the UpperCamelCase notation for actual API kinds.

/lgtm cancel

content/en/docs/reference/labels-annotations-taints/_index.md

sftim · 2024-09-29T20:26:43Z

content/en/docs/reference/labels-annotations-taints/_index.md

+
+Used on: Jobs, Pods
+
+This label/annotation is set by the JobSet controller on child Jobs and Pods of a JobSet. The value will be the SHA256 hash of the namespaced Job name.


Suggested change

This label/annotation is set by the JobSet controller on child Jobs and Pods of a JobSet. The value will be the SHA256 hash of the namespaced Job name.

The JobSet controller sets this label (and also an annotation with the same key) on child Jobs and

Pods of a JobSet. The value is the SHA256 hash of the namespaced Job name.

content/en/docs/reference/labels-annotations-taints/_index.md

danielvegamyhre · 2024-10-04T05:27:16Z

@Adarsh-verma-14 can you address sftim@'s comments as soon as you can please? The JobSet blog post PR is blocked by this one, so we are hoping to get it merged as soon as possible :)

Adarsh-verma-14 · 2024-10-04T18:36:04Z

@Adarsh-verma-14 can you address sftim@'s comments as soon as you can please? The JobSet blog post PR is blocked by this one, so we are hoping to get it merged as soon as possible :)

sure

k8s-ci-robot · 2024-10-07T05:32:16Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from sftim. For more information see the Kubernetes Code Review Process.

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

Needs approval from an approver in each of these files:

content/en/docs/OWNERS

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

Adarsh-verma-14 · 2024-10-07T05:34:48Z

Hi , I have updated these changes as suggested by @sftim . PTAL!!

ahg-g · 2024-10-20T02:06:48Z

Friendly ping @sftim

sftim · 2024-10-20T10:51:25Z

content/en/docs/reference/labels-annotations-taints/_index.md

+
+Example: `jobset.sigs.k8s.io/replicatedjob-replicas: "5"`
+
+Used on: ReplicatedJobs


Is there definitely an API kind named ReplicatedJob? If so, what API group would I find this in?

sftim · 2024-10-20T10:51:32Z

content/en/docs/reference/labels-annotations-taints/_index.md

+
+Example: `alpha.jobset.sigs.k8s.io/exclusive-topology: "zone"`
+
+Used on: JobSets, ReplicatedJobs


Is there definitely an API kind named ReplicatedJob? If so, what API group would I find this in?

There is no API kind named ReplicatedJob, but the annotation can be used on the JobTemplate defined inside the ReplicatedJob struct

OK, so Used on: would be JobSet, Job I think.
JobTemplate is also not an API kind (unlike say the unusual case of PodTemplate)

sftim · 2024-10-20T10:52:18Z

content/en/docs/reference/labels-annotations-taints/_index.md

+
+Type: Label, Annotation
+
+Example: `alpha.jobset.sigs.k8s.io/node-selector-strategy=true`


Suggested change

Example: `alpha.jobset.sigs.k8s.io/node-selector-strategy=true`

Example: `alpha.jobset.sigs.k8s.io/node-selector-strategy: "true"`

sftim · 2024-10-20T10:52:39Z

content/en/docs/reference/labels-annotations-taints/_index.md

+
+Type: Annotation, Label
+
+Example: `alpha.jobset.sigs.k8s.io/default_myjobset-replicatedjob-0`


There should be a value for the label.

Suggested change

Example: `alpha.jobset.sigs.k8s.io/default_myjobset-replicatedjob-0`

Example: `alpha.jobset.sigs.k8s.io/namespaced-job: default_myjobset-replicatedjob-0`

As an aside, this will run into name length issues. The JobSet and Namespace can both have names that are up to 63 characters long, so the concatenation won't always fit into a label value.

(but not really relevant to this PR).

sftim · 2024-10-20T10:53:44Z

content/en/docs/reference/labels-annotations-taints/_index.md

+
+Type: Label, Annotation
+
+Example: `jobset.sigs.k8s.io/job-key=0f1e93893c4cb372080804ddb9153093cb0d20cefdd37f653e739c232d363feb`


Suggested change

Example: `jobset.sigs.k8s.io/job-key=0f1e93893c4cb372080804ddb9153093cb0d20cefdd37f653e739c232d363feb`

Example: `jobset.sigs.k8s.io/job-key: 0f1e93893c4cb372080804ddb9153093cb0d20cefdd37f653e739c232d363feb`

This doesn't look right. Is 0f1e93893c4cb372080804ddb9153093cb0d20cefdd37f653e739c232d363feb definitely a valid label value? It looks longer than is allowed.

It is, we set the value as the SHA256 hash of the namespaced job name here.

OK, but a SHA256 hash is 64 UTF-8 (or ASCII) characters, and conformant label values are documented as being up to 63 characters long.

Something doesn't add up. Maybe there's an off-by-one in the API server (I hope not).

Sorry, it's SHA1 not SHA256, my mistake. So it's only 40 characters.

OK. Minor docs bug then; we can merge this with or without a fix (still would need a post-merge fixup).

sftim · 2024-10-20T10:53:56Z

content/en/docs/reference/labels-annotations-taints/_index.md

+
+Used on: Jobs, Pods
+
+This label/annotation is set by the JobSet controller on child Jobs and Pods. It contains the index of the Job replica within its parent ReplicatedJob.


Is there definitely an API kind named ReplicatedJob? If so, what API group would I find this in?

There's no ReplicatedJob API, it is just part of the JobSet API: https://github.com/kubernetes-sigs/jobset/blob/b92cbdcbe77f168a82cf12c9f349bdd053d2ae5c/api/jobset/v1alpha2/jobset_types.go#L85

OK, this needs fixing.

content/en/docs/reference/labels-annotations-taints/_index.md

sftim

We mainly just want to document what's there even if it's a bit awry. This is close but not yet right, though, and I think it does need another round of corrections.

content/en/docs/reference/labels-annotations-taints/_index.md

danielvegamyhre · 2024-10-25T15:31:13Z

@Adarsh-verma-14 can you address the last few comments here? Thanks!

ahg-g · 2024-11-18T01:04:17Z

Hello, anything blocking this one?

sftim · 2024-11-18T09:51:01Z

There's a lot of pending feedback. I noticed #47383 (comment)

ahg-g · 2024-11-19T03:46:46Z

since @Adarsh-verma-14 is not responding, I will clone it and submit a PR tomorrow to close this

Adarsh-verma-14 · 2024-12-13T09:07:59Z

sorry for late response, due to some engagement with my other work. it will take more time meanwhile if anyone wants to work on it, can work.

ahg-g · 2024-12-23T17:24:10Z

I created #49217

adding labels and annotation for JobSet

099e386

k8s-ci-robot added language/en Issues or PRs related to English language cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Aug 7, 2024

k8s-ci-robot requested review from salaxander and sftim August 7, 2024 17:11

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Aug 7, 2024

kannon92 reviewed Aug 8, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

sftim reviewed Aug 8, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

sftim reviewed Aug 8, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

sftim reviewed Aug 8, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

sftim reviewed Aug 8, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

sftim reviewed Aug 8, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

sftim reviewed Aug 8, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

sftim reviewed Aug 8, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

sftim reviewed Aug 8, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

sftim reviewed Aug 8, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

danielvegamyhre reviewed Aug 8, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

content/en/docs/reference/labels-annotations-taints/_index.md Outdated Show resolved Hide resolved

sftim reviewed Aug 8, 2024

View reviewed changes

k8s-ci-robot changed the title ~~Adding labels and annotation for JobSet~~ Document labels, annotations and taints for JobSet Aug 8, 2024

k8s-ci-robot added the sig/apps Categorizes an issue or PR as relevant to SIG Apps. label Aug 8, 2024

update description for labels/annotaionand taint also

0d815b6

sftim reviewed Aug 11, 2024

View reviewed changes

drackpack mentioned this pull request Sep 22, 2024

Add a desc #48035

Closed

danielvegamyhre reviewed Sep 27, 2024

View reviewed changes

Modified some sentence

d21c85e

sftim reviewed Sep 29, 2024

View reviewed changes

k8s-ci-robot assigned sftim Sep 29, 2024

update description for exclusive-topology

fc4c0c7

sftim reviewed Oct 20, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Show resolved Hide resolved

sftim reviewed Oct 20, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Show resolved Hide resolved

sftim reviewed Oct 20, 2024

View reviewed changes

content/en/docs/reference/labels-annotations-taints/_index.md Show resolved Hide resolved

ahg-g mentioned this pull request Dec 23, 2024

Document labels, annotations and taints for JobSet #49217

Open


		Used on: Jobs, Pods

		This label is used to store the name of the JobSet to which a job or pod belongs.

	This label is used to store the name of the JobSet to which a job or pod belongs.
	This label is used to store the name of the JobSet to which a Job or Pod belongs.
	JobSet is an extension API that you can deploy into your Kubernetes cluster.

-Type: Annotation
-Example: `alpha.jobset.sigs.k8s.io/no-schedule: "true"`
-Used on: Jobs
-This annotation prevents the job from being scheduled.
+Type: Taint
+Example: `alpha.jobset.sigs.k8s.io/no-schedule: NoSchedule`
+Used on: Nodes
+The JobSet controller uses this taint to support its node labeling exclusive placement strategy.
+JobSet is an extension API that you can deploy into your Kubernetes cluster.


		Used on: JobSets

		This annotation acts as a flag. When set, the JobSet controller injects nodeSelectors for the `JobSetNameKey` label (e.g., `jobset.sigs.k8s.io/jobset-name`) to ensure exclusive job placement per topology.


		Used on: Jobs, Pods

		This label/annotation is used to store the name of the JobSet to which a Job or Pod belongs.


		Used on: Jobs, Pods

		This label/annotation is set by the JobSet controller on child Jobs and Pods of a JobSet. The value will be the SHA256 hash of the namespaced Job name.

	This label/annotation is set by the JobSet controller on child Jobs and Pods of a JobSet. The value will be the SHA256 hash of the namespaced Job name.
	The JobSet controller sets this label (and also an annotation with the same key) on child Jobs and
	Pods of a JobSet. The value is the SHA256 hash of the namespaced Job name.


		Example: `jobset.sigs.k8s.io/replicatedjob-replicas: "5"`

		Used on: ReplicatedJobs


		Example: `alpha.jobset.sigs.k8s.io/exclusive-topology: "zone"`

		Used on: JobSets, ReplicatedJobs


		Type: Label, Annotation

		Example: `alpha.jobset.sigs.k8s.io/node-selector-strategy=true`


		Type: Annotation, Label

		Example: `alpha.jobset.sigs.k8s.io/default_myjobset-replicatedjob-0`

	Example: `alpha.jobset.sigs.k8s.io/default_myjobset-replicatedjob-0`
	Example: `alpha.jobset.sigs.k8s.io/namespaced-job: default_myjobset-replicatedjob-0`


		Type: Label, Annotation

		Example: `jobset.sigs.k8s.io/job-key=0f1e93893c4cb372080804ddb9153093cb0d20cefdd37f653e739c232d363feb`

	Example: `jobset.sigs.k8s.io/job-key=0f1e93893c4cb372080804ddb9153093cb0d20cefdd37f653e739c232d363feb`
	Example: `jobset.sigs.k8s.io/job-key: 0f1e93893c4cb372080804ddb9153093cb0d20cefdd37f653e739c232d363feb`

Document labels, annotations and taints for JobSet #47383

Are you sure you want to change the base?

Document labels, annotations and taints for JobSet #47383

Conversation

Adarsh-verma-14 commented Aug 7, 2024

Adarsh-verma-14 commented Aug 7, 2024

netlify bot commented Aug 7, 2024 • edited Loading

✅ Pull request preview available for checking

kannon92 commented Aug 8, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danielvegamyhre left a comment

Choose a reason for hiding this comment

kannon92 commented Aug 8, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim commented Aug 8, 2024

sftim commented Aug 8, 2024

danielvegamyhre commented Aug 8, 2024

sftim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tengqm commented Sep 22, 2024

sftim commented Sep 22, 2024

danielvegamyhre left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danielvegamyhre commented Sep 29, 2024

sftim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danielvegamyhre commented Oct 4, 2024

Adarsh-verma-14 commented Oct 4, 2024

k8s-ci-robot commented Oct 7, 2024

Adarsh-verma-14 commented Oct 7, 2024

ahg-g commented Oct 20, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim left a comment

Choose a reason for hiding this comment

danielvegamyhre commented Oct 25, 2024

ahg-g commented Nov 18, 2024

sftim commented Nov 18, 2024

ahg-g commented Nov 19, 2024

Adarsh-verma-14 commented Dec 13, 2024

ahg-g commented Dec 23, 2024

netlify bot commented Aug 7, 2024 •

edited

Loading