From 0f788af54ba8262a6cc6157444b2317dec79800c Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Sun, 3 Mar 2019 10:20:36 -0800 Subject: [PATCH] update with pr comments --- keps/sig-cli/kustomize-ordering.md | 117 +++++++++++++++++++++-------- 1 file changed, 84 insertions(+), 33 deletions(-) diff --git a/keps/sig-cli/kustomize-ordering.md b/keps/sig-cli/kustomize-ordering.md index b73471c04514..863ac87c46ed 100644 --- a/keps/sig-cli/kustomize-ordering.md +++ b/keps/sig-cli/kustomize-ordering.md @@ -54,51 +54,97 @@ sorting by Resource Type is insufficient. ### Goals -- Provide the ability for users to break glass and override Kustomize's sort ordering. +- Provide the ability for users to override the order that Kustomize emits Resources + - Used by `kubectl apply` or order Resource operations + - Used to override creation order for meta-Resources such as Namespaces ### Non-Goals -## Proposal +- Ensure certain Resources are *Settled* or *Ready* before other Resources + - Ensure dependencies between Workloads -Add a new field `resourceOrdering` that is a list of `key, value, type` tuples to define the ordering. +## Proposal +Provide a simple mechanism allowing users to override the order that +Resource operations are Applied. Add a new field `sortOrder` that is +a list of `ResourceSelector`s which match Resources based +off their annotations. + +```go + +type Kustomization struct { + // ... + + // sortOrder defines a precedence for ordering Resources. Resources + // will be sorted in the order the match a ResourecSelector before + // they are emitted. + SortOrder []ResourceSelector `json:"sortOrder"` + + // ... +} + +// ResourceSelector selects Resources that it matches +type ResourceSelector struct { + // annotationSelector matches Resources based on their Annotations. + AnnotationSelector AnnotationSelector `json:"annotationSelector"` +} + +// A annotation selector is a annotation query over a set of resources. The results of matchAnnotations is ANDed. +// An empty annotation selector matches all objects. A null annotation selector matches no objects. +type AnnotationSelector struct { + // matchAnnotations is a map of {key,value} pairs. A Resource matches if it has + // *all* of the annotations in matchAnnotations appear in the Resource metaData. + // Null and empty values are not allowed. + // +optional + MatchAnnotations map[string]string `json:"matchAnnotations,omitempty"` + + // TODO: Consider adding field: MatchExpressions []AnnotationSelectorRequirement +} +``` Example: ``` -resourceOrdering: -- name: first - - type: label - key: some-label-name-1 - value: some-label-value-1 - - type: annotation - key: some-annotation-name-a - value: some-label-value-a -- name: second - - type: annotation - key: some-annotation-name-b - value: some-annotation-value-b -- name: third - type: label - key: some-label-name-2 - value: some-label-value-2 +sortOrder: +- annotationSelector: + some-annotation-name-1: some-annotation-value-1 + some-annotation-name-a: some-label-value-a +- annotationSelector: + some-annotation-name-1: some-annotation-value-1 +- annotationSelector: + some-annotation-name-2: some-annotation-value-2 ``` -The explicit user defined ordering using labels and annotations would take precedence over the - ordering based off types. Types would be used as a secondary sorting function. +The explicit user defined ordering using annotations will take precedence over the type based +orderings. Types would be used as a fallback sorting function amongst Resource with equal +precedence in the explicit ordering. -- Resources labeled with `some-label-name-1=some-label-value-1` *and* annotated - with `some-annotation-name-a=some-label-value-a` are first +- Resources annotated with `some-annotation-name-1: some-annotation-value-1` *and* annotated + with `some-annotation-name-a: some-annotation-value-a` are first - These Resources are sorted by type -- Resources annotated with `some-annotation-name-a=some-annotation-value-b` are second +- Resources annotated with `some-annotation-name-1=some-annotation-value-1` + (without `some-annotation-name-a: some-annotation-value-a`) appear second - These Resources are sorted by type -- Resources labeled with `some-label-name-2=some-label-value-2` are third +- Resources annotated with `some-annotation-name-2=some-annotation-value-2` - These Resources are sorted by type -- Resources not matching any label or annotation are last +- Resources not matching any annotation are last - These Resources are sorted by type -Resources matching multiple orderings (e.g. have multiple matching labels and annotations) appear +Resources matching multiple orderings (e.g. have multiple matching annotations) appear in the position matching the earliest label / annotation. +**Note:** Throw an error if there is a selector that selects a superset of another selector +and it appears first. e.g. this should throw an error because the first selector will match +everything that the second selector does, and it will have no effect. + +``` +sortOrder: +- annotationSelector: + some-annotation-name-1: some-annotation-value-1 +- annotationSelector: + some-annotation-name-1: some-annotation-value-1 + some-annotation-name-a: some-label-value-a +``` + ### Risks and Mitigations Risk: Users build complex orderings that are hard to reason about. @@ -106,7 +152,11 @@ Mitigation: Good documentation and recommendations about how to keep things simp ## Graduation Criteria -NA +Use customer feedback to determine if we should support: + +- `LabelSelectors` +- `AnnotationSelectorRequirement` (like `LabelSelectorRequirement` but for annotations) +- Explicitly ordering things ## Docs @@ -117,13 +167,14 @@ Update Kubectl Book and Kustomize Documentation Unit Tests for: -- [ ] Resources with labels and annotations follow the ordering override semantics +- [ ] Resources with annotations follow the ordering override semantics - [ ] Resources matching multiple orderings land in the right spot +- [ ] Throw an error if a superset selector appears after its subset (e.g. a more restrict selector appears later) + - This will have no effect, as everything will have already been matched - [ ] Resources are sorted by type as a secondary factor -- [ ] Having multiple labels / annotations with the same key and different values works correctly -- [ ] Having multiple labels / annotations with different keys and the same values works correctly -- [ ] Mixing labels and annotations works -- [ ] Unrecognized type values throw and error +- [ ] Having multiple annotations with the same key and different values works correctly +- [ ] Having multiple annotations with different keys and the same values works correctly +- [ ] Empty and Null `MatchAnnotations` throw an error - [ ] Resources that don't appear in the ordering overrides appear last and are sorted by type ### Version Skew Tests