Merge pull request #39456 from kannon92/job-labels-off-dev-1-27

labels and job updates to mention new labels
kubernetes · Apr 1, 2023 · 94b30e7 · 94b30e7
2 parents 0faa93c + 7b6e694
commit 94b30e7
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 28 deletions.
diff --git a/content/en/docs/concepts/workloads/controllers/job.md b/content/en/docs/concepts/workloads/controllers/job.md
@@ -54,22 +54,22 @@ Check on the status of the Job with `kubectl`:
 
 {{< tabs name="Check status of Job" >}}
 {{< tab name="kubectl describe job pi" codelang="bash" >}}
-Name:             pi
-Namespace:        default
-Selector:         controller-uid=0cd26dd5-88a2-4a5f-a203-ea19a1d5d578
-Labels:           controller-uid=0cd26dd5-88a2-4a5f-a203-ea19a1d5d578
-                  job-name=pi
-Annotations:      batch.kubernetes.io/job-tracking: 
-Parallelism:      1
-Completions:      1
-Completion Mode:  NonIndexed
-Start Time:       Fri, 28 Oct 2022 13:05:18 +0530
-Completed At:     Fri, 28 Oct 2022 13:05:21 +0530
-Duration:         3s
-Pods Statuses:    0 Active / 1 Succeeded / 0 Failed
+Name:           pi
+Namespace:      default
+Selector:       batch.kubernetes.io/controller-uid=c9948307-e56d-4b5d-8302-ae2d7b7da67c
+Labels:         batch.kubernetes.io/controller-uid=c9948307-e56d-4b5d-8302-ae2d7b7da67c
+                batch.kubernetes.io/job-name=pi
+                ...
+Annotations:    batch.kubernetes.io/job-tracking: ""
+Parallelism:    1
+Completions:    1
+Start Time:     Mon, 02 Dec 2019 15:20:11 +0200
+Completed At:   Mon, 02 Dec 2019 15:21:16 +0200
+Duration:       65s
+Pods Statuses:  0 Running / 1 Succeeded / 0 Failed
 Pod Template:
-  Labels:  controller-uid=0cd26dd5-88a2-4a5f-a203-ea19a1d5d578
-           job-name=pi
+  Labels:  batch.kubernetes.io/controller-uid=c9948307-e56d-4b5d-8302-ae2d7b7da67c
+           batch.kubernetes.io/job-name=pi
   Containers:
    pi:
     Image:      perl:5.34.0
@@ -93,15 +93,13 @@ Events:
 apiVersion: batch/v1
 kind: Job
 metadata:
-  annotations:
-    batch.kubernetes.io/job-tracking: ""
-    kubectl.kubernetes.io/last-applied-configuration: |
-      {"apiVersion":"batch/v1","kind":"Job","metadata":{"annotations":{},"name":"pi","namespace":"default"},"spec":{"backoffLimit":4,"template":{"spec":{"containers":[{"command":["perl","-Mbignum=bpi","-wle","print bpi(2000)"],"image":"perl:5.34.0","name":"pi"}],"restartPolicy":"Never"}}}}
+  annotations: batch.kubernetes.io/job-tracking: ""
+             ...  
   creationTimestamp: "2022-11-10T17:53:53Z"
   generation: 1
   labels:
-    controller-uid: 204fb678-040b-497f-9266-35ffa8716d14
-    job-name: pi
+    batch.kubernetes.io/controller-uid: 863452e6-270d-420e-9b94-53a54146c223
+    batch.kubernetes.io/job-name: pi
   name: pi
   namespace: default
   resourceVersion: "4751"
@@ -113,14 +111,14 @@ spec:
   parallelism: 1
   selector:
     matchLabels:
-      controller-uid: 204fb678-040b-497f-9266-35ffa8716d14
+      batch.kubernetes.io/controller-uid: 863452e6-270d-420e-9b94-53a54146c223
   suspend: false
   template:
     metadata:
       creationTimestamp: null
       labels:
-        controller-uid: 204fb678-040b-497f-9266-35ffa8716d14
-        job-name: pi
+        batch.kubernetes.io/controller-uid: 863452e6-270d-420e-9b94-53a54146c223
+        batch.kubernetes.io/job-name: pi
     spec:
       containers:
       - command:
@@ -152,7 +150,7 @@ To view completed Pods of a Job, use `kubectl get pods`.
 To list all the Pods that belong to a Job in a machine readable form, you can use a command like this:
 
 ```shell
-pods=$(kubectl get pods --selector=job-name=pi --output=jsonpath='{.items[*].metadata.name}')
+pods=$(kubectl get pods --selector=batch.kubernetes.io/job-name=pi --output=jsonpath='{.items[*].metadata.name}')
 echo $pods
 ```
 
@@ -171,6 +169,12 @@ View the standard output of one of the pods:
 kubectl logs $pods
 ```
 
+Another way to view the logs of a Job:
+
+```shell
+kubectl logs jobs/pi
+```
+
 The output is similar to this:
 
 ```
@@ -192,6 +196,10 @@ characters.
 
 A Job also needs a [`.spec` section](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status).
 
+### Job Labels
+
+Job labels will have `batch.kubernetes.io/` prefix for `job-name` and `controller-uid`.
+
 ### Pod Template
 
 The `.spec.template` is the only required field of the `.spec`.
@@ -689,12 +697,12 @@ metadata:
 spec:
   selector:
     matchLabels:
-      controller-uid: a8f3d00d-c6d2-11e5-9f87-42010af00002
+      batch.kubernetes.io/controller-uid: a8f3d00d-c6d2-11e5-9f87-42010af00002
   ...
 ```
 
 Then you create a new Job with name `new` and you explicitly specify the same selector.
-Since the existing Pods have label `controller-uid=a8f3d00d-c6d2-11e5-9f87-42010af00002`,
+Since the existing Pods have label `batch.kubernetes.io/controller-uid=a8f3d00d-c6d2-11e5-9f87-42010af00002`,
 they are controlled by Job `new` as well.
 
 You need to specify `manualSelector: true` in the new Job since you are not using
@@ -709,7 +717,7 @@ spec:
   manualSelector: true
   selector:
     matchLabels:
-      controller-uid: a8f3d00d-c6d2-11e5-9f87-42010af00002
+      batch.kubernetes.io/controller-uid: a8f3d00d-c6d2-11e5-9f87-42010af00002
   ...
 ```
 

diff --git a/content/en/docs/reference/labels-annotations-taints/_index.md b/content/en/docs/reference/labels-annotations-taints/_index.md
@@ -711,6 +711,47 @@ Kubernetes 1.27 and newer will ignore this annotation and always track Jobs
 using finalizers.
 {{< /note >}}
 
+### job-name (deprecated) {#job-name}
+
+Example: `job-name: "pi"`
+
+Used on: Jobs and Pods controlled by Jobs
+
+{{< note >}}
+Starting from Kubernetes 1.27, this label is deprecated.
+Kubernetes 1.27 and newer ignore this label and use the prefixed `job-name` label.
+{{< /note >}}
+
+### controller-uid (deprecated) {#controller-uid}
+
+Example: `controller-uid: "$UID"`
+
+Used on: Jobs and Pods controlled by Jobs
+
+{{< note >}}
+Starting from Kubernetes 1.27, this label is deprecated.
+Kubernetes 1.27 and newer ignore this label and use the prefixed `controller-uid` label.
+{{< /note >}}
+
+### batch.kubernetes.io/job-name {#batchkubernetesio-job-name}
+
+Example: `batch.kubernetes.io/job-name: "pi"`
+
+Used on: Jobs and Pods controlled by Jobs
+
+This label is used as a user-friendly way to get Pods corresponding to a Job.
+The `job-name` comes from the `name` of the Job and allows for an easy way to get Pods corresponding to the Job.
+
+### batch.kubernetes.io/controller-uid {#batchkubernetesio-controller-uid}
+
+Example: `batch.kubernetes.io/controller-uid: "$UID"`
+
+Used on: Jobs and Pods controlled by Jobs
+
+This label is used as a programmatic way to get all Pods corresponding to a Job.  
+The `controller-uid` is a unique identifer that gets set in the `selector` field so the Job controller
+can get all the corresponding Pods.
+
 ### scheduler.alpha.kubernetes.io/defaultTolerations {#scheduleralphakubernetesio-defaulttolerations}
 
 Example: `scheduler.alpha.kubernetes.io/defaultTolerations: '[{"operator": "Equal", "value": "value1", "effect": "NoSchedule", "key": "dedicated-node"}]'`