Merge pull request #21776 from erictune/job-sel-gen

Selector generation for batch/v1 Job
2016-02-26 11:58:21 -08:00
parent 456fd7f43a 095a85e76e
commit 3dab166da4
38 changed files with 1078 additions and 324 deletions
--- a/docs/api-reference/extensions/v1beta1/definitions.html
+++ b/docs/api-reference/extensions/v1beta1/definitions.html
@@ -4437,7 +4437,7 @@ Populated by the system when a graceful deletion is requested. Read-only. More i
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">completions</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Completions specifies the desired number of successfully finished pods the job should be run with.  Setting to nil means that the success of any pod signals the success of all pods, and allows parallelism to have any positive value.  Setting to 1 means that parallelism is limited to 1 and the success of that pod signals the success of the job.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Completions specifies the desired number of successfully finished pods the job should be run with.  Setting to nil means that the success of any pod signals the success of all pods, and allows parallelism to have any positive value.  Setting to 1 means that parallelism is limited to 1 and the success of that pod signals the success of the job. More info: <a href="http://releases.k8s.io/HEAD/docs/user-guide/jobs.md">http://releases.k8s.io/HEAD/docs/user-guide/jobs.md</a></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">integer (int32)</p></td>
 <td class="tableblock halign-left valign-top"></td>
@@ -4451,12 +4451,19 @@ Populated by the system when a graceful deletion is requested. Read-only. More i
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">selector</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Selector is a label query over pods that should match the pod count. More info: <a href="http://releases.k8s.io/HEAD/docs/user-guide/labels.md#label-selectors">http://releases.k8s.io/HEAD/docs/user-guide/labels.md#label-selectors</a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Selector is a label query over pods that should match the pod count. Normally, the system sets this field for you. More info: <a href="http://releases.k8s.io/HEAD/docs/user-guide/labels.md#label-selectors">http://releases.k8s.io/HEAD/docs/user-guide/labels.md#label-selectors</a></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_v1beta1_labelselector">v1beta1.LabelSelector</a></p></td>
 <td class="tableblock halign-left valign-top"></td>
 </tr>
 <tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">autoSelector</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">AutoSelector controls generation of pod labels and pod selectors. It was not present in the original extensions/v1beta1 Job definition, but exists to allow conversion from batch/v1 Jobs, where it corresponds to, but has the opposite meaning as, ManualSelector. More info: <a href="http://releases.k8s.io/HEAD/docs/design/selector-generation.md">http://releases.k8s.io/HEAD/docs/design/selector-generation.md</a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
+</tr>
+<tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">template</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">Template is the object that describes the pod that will be created when executing a job. More info: <a href="http://releases.k8s.io/HEAD/docs/user-guide/jobs.md">http://releases.k8s.io/HEAD/docs/user-guide/jobs.md</a></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
--- a/docs/user-guide/job.yaml
+++ b/docs/user-guide/job.yaml
@@ -1,16 +1,11 @@
-apiVersion: extensions/v1beta1
+apiVersion: batch/v1
 kind: Job
 metadata:
  name: pi
 spec:
-  selector:
-    matchLabels:
-      app: pi
  template:
    metadata:
      name: pi
-      labels:
-        app: pi
    spec:
      containers:
      - name: pi
--- a/docs/user-guide/jobs.md
+++ b/docs/user-guide/jobs.md
@@ -47,6 +47,8 @@ Documentation for other releases can be found at
      - [Controlling Parallelism](#controlling-parallelism)
  - [Handling Pod and Container Failures](#handling-pod-and-container-failures)
  - [Job Patterns](#job-patterns)
+  - [Advanced Usage](#advanced-usage)
+    - [Specifying your own pod selector](#specifying-your-own-pod-selector)
  - [Alternatives](#alternatives)
    - [Bare Pods](#bare-pods)
    - [Replication Controller](#replication-controller)
@@ -76,19 +78,14 @@ It takes around 10s to complete.
 <!-- BEGIN MUNGE: EXAMPLE job.yaml -->

 ```yaml
-apiVersion: extensions/v1beta1
+apiVersion: batch/v1
 kind: Job
 metadata:
  name: pi
 spec:
-  selector:
-    matchLabels:
-      app: pi
  template:
    metadata:
      name: pi
-      labels:
-        app: pi
    spec:
      containers:
      - name: pi
@@ -170,21 +167,9 @@ Only a [`RestartPolicy`](pod-states.md) equal to `Never` or `OnFailure` are allo

 ### Pod Selector

-The `.spec.selector` field is a label query over a set of pods.
+The `.spec.selector` field is optional.  In almost all cases you should not specify it.
+See section [specifying your own pod selector](#specifying-your-own-pod-selector).

-The `spec.selector` is an object consisting of two fields:
-* `matchLabels` - works the same as the `.spec.selector` of a [ReplicationController](replication-controller.md)
-* `matchExpressions` - allows to build more sophisticated selectors by specifying key,
-  list of values and an operator that relates the key and values.
-
-When the two are specified the result is ANDed.
-
-If `.spec.selector` is unspecified, `.spec.selector.matchLabels` will be defaulted to
-`.spec.template.metadata.labels`.
-
-Also you should not normally create any pods whose labels match this selector, either directly,
-via another Job, or via another controller such as ReplicationController.  Otherwise, the Job will
-think that those pods were created by it.  Kubernetes will not stop you from doing this.

 ### Parallel Jobs

@@ -323,6 +308,70 @@ Here, `W` is the number of work items.
 | Single Job with Static Work Assignment                                     |          W          |        any           |


+## Advanced Usage
+
+### Specifying your own pod selector
+
+Normally, when you create a job object, you do not specify `spec.selector`.
+The system defaulting logic adds this field when the job is created.
+It picks a selector value that will not overlap with any other jobs.
+
+However, in some cases, you might need to override this automatically set selector.
+To do this, you can specify the `spec.selector` of the job.
+
+Be very careful when doing this.  If you specify a label selector which is not
+unique to the pods of that job, and which matches unrelated pods, then pods of the unrelated
+job may be deleted, or this job may count other pods as completing it, or one or both
+of the jobs may refuse to create pods or run to completion.  If a non-unique selector is
+chosen, then other controllers (e.g. ReplicationController) and their pods may behave
+in unpredicatable ways too.  Kubernetes will not stop you from making a mistake when
+specifying `spec.selector`.
+
+Here is an example of a case when you might want to use this feature.
+
+Say job `old` is already running.  You want existing pods
+to keep running, but you want the rest of the pods it creates
+to use a different pod template and for the job to have a new name.
+You cannot update the job because these fields are not updatable.
+Therefore, you delete job `old` but leave its pods
+running, using `kubectl delete jobs/old-one --cascade=false`.
+Before deleting it, you make a note of what selector it uses:
+
+```
+kind: Job
+metadata:
+  name: old
+  ...
+spec:
+  selector:
+    matchLabels:
+      job-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 `job-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
+the selector that the system normally generates for you automatically.
+
+```
+kind: Job
+metadata:
+  name: new
+  ...
+spec:
+  manualSelector: true
+  selector:
+    matchLabels:
+      job-uid: a8f3d00d-c6d2-11e5-9f87-42010af00002
+  ...
+```
+
+The new Job itself will have a different uid from `a8f3d00d-c6d2-11e5-9f87-42010af00002`.  Setting
+`manualSelector: true` tells the system to that you know what you are doing and to allow this
+mismatch.

 ## Alternatives