diff --git a/docs/proposals/selector-generation.md b/docs/design/selector-generation.md similarity index 84% rename from docs/proposals/selector-generation.md rename to docs/design/selector-generation.md index 27107c31291..545de9cf309 100644 --- a/docs/proposals/selector-generation.md +++ b/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 + + -[![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)]() diff --git a/docs/proposals/job.md b/docs/proposals/job.md index 36e7a760605..d2d728a5b36 100644 --- a/docs/proposals/job.md +++ b/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))