Update to selector generation design

docs/proposals/selector-generation.md → docs/design/selector-generation.md

@@ -48,16 +48,22 @@ Make it really hard to accidentally create a job which has an overlapping select
 
 # Proposed changes
 
-## APIserver
+## API
 
 `extensions/v1beta1 Job` remains the same. `batch/v1 Job` changes change as follows.
 
-There are two allowed usage modes:
+Field `job.spec.manualSelector` is added.  It controls whether selectors are automatically
+generated.  In automatic mode, user cannot make the mistake of creating non-unique selectors.
+In manual mode, certain rare use cases are supported.
+
+Validation is not changed.  A selector must be provided, and it must select the pod template.
+
+Defaulting changes.  Defaulting happens in one of two modes:
 
 ### Automatic Mode
 
 - User does not specify `job.spec.selector`.
-- User is probably unaware of the `job.spec.noAutoSelector` field and does not think about it.
+- User is probably unaware of the `job.spec.manualSelector` field and does not think about it.
 - User optionally puts labels on pod template (optional).  user does not think about uniqueness, just labeling for user's own reasons.
 - Defaulting logic sets `job.spec.selector` to `matchLabels["controller-uid"]="$UIDOFJOB"`
 - Defaulting logic  appends 2 labels to the `.spec.template.metadata.labels`.
@@ -68,14 +74,10 @@ There are two allowed usage modes:
 
 - User means User or Controller for the rest of this list.
 - User does specify `job.spec.selector`.
-- User does specify `job.spec.noAutoSelector=true`
+- User does specify `job.spec.manualSelector=true`
 - User puts a unique label or label(s) on pod template (required).  user does think carefully about uniqueness.
 - No defaulting of pod labels or the selector happen.
 
-### Common to both modes
-
-- Validation code ensures that the selector on the job selects the labels on the pod template, and rejects if not.
-
 ### Rationale
 
 UID is better than Name in that:
@@ -89,13 +91,17 @@ Commands like  `kubectl get pods -l job-name=myjob` should do exactly what is wa
 
 Using both gets the benefits of both, at the cost of some label verbosity.
 
+The field is a `*bool`.  Since false is expected to be much more common,
+and since the feature is complex, it is better to leave it unspecified so that
+users looking at a stored pod spec do not need to be aware of this field.
+
 ### Overriding Unique Labels
 
-If user does specify `job.spec.selector` then the user must also specify `job.spec.noAutoSelector`.
+If user does specify `job.spec.selector` then the user must also specify `job.spec.manualSelector`.
 This ensures the user knows that what he is doing is not the normal thing to do.
 
-To prevent users from copying the `job.spec.noAutoSelector` flag from existing jobs, it will be
-optional and default to false, which means when you ask GET and existing job back that didn't use this feature, you don't even see the  `job.spec.noAutoSelector` flag, so you are not tempted to wonder if you should fiddle with it.
+To prevent users from copying the `job.spec.manualSelector` flag from existing jobs, it will be
+optional and default to false, which means when you ask GET and existing job back that didn't use this feature, you don't even see the  `job.spec.manualSelector` flag, so you are not tempted to wonder if you should fiddle with it.
 
 ## Job Controller
 
@@ -113,9 +119,9 @@ Recommend `kubectl get jobs -l job-name=name` as the way to find pods of a job.
 
 # Cross Version Compat
 
-`v1beta1` will not have a `job.spec.noAutoSelector` and will not provide a default selector.
+`v1beta1` will not have a `job.spec.manualSelector` and will not provide a default selector.
 
-Conversion from v1beta1 to v1 will use the user-provided selector and set `job.spec.noAutoSelector=true`.
+Conversion from v1beta1 to v1 will use the user-provided selector and set `job.spec.manualSelector=true`.
 
 # Future Work
 
@@ -128,6 +134,8 @@ We probably want as much as possible the same behavior for Job and ReplicationCo
 
 
 
+
+
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
-[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/proposals/selector-generation.md?pixel)]()
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/design/selector-generation.md?pixel)]()
 <!-- END MUNGE: GENERATED_ANALYTICS -->

docs/proposals/job.md

@@ -185,7 +185,7 @@ Below are the possible future extensions to the Job controller:
   [this comment](https://github.com/kubernetes/kubernetes/issues/1624#issuecomment-97622142))
 * Be able to inspect Pods running a Job, especially after a Job has finished, e.g.
   by providing pointers to Pods in the JobStatus ([see comment](https://github.com/kubernetes/kubernetes/pull/11746/files#r37142628)).
-* help users avoid non-unique label selectors ([see this proposal](selector-generation.md))
+* help users avoid non-unique label selectors ([see this proposal](../../docs/design/selector-generation.md))
 
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->