✨ add condition merge utils

util/conditions/getter.go

@@ -113,3 +113,61 @@ func GetLastTransitionTime(from Getter, t clusterv1.ConditionType) *metav1.Time
 	}
 	return nil
 }
+
+// Summary returns a Ready condition with the summary of all the conditions existing
+// on an object. If the object does not have other conditions, no summary condition is generated.
+func Summary(from Getter, options ...MergeOption) *clusterv1.Condition {
+	conditions := from.GetConditions()
+
+	conditionsInScope := make([]localizedCondition, 0, len(conditions))
+	for i := range conditions {
+		c := conditions[i]
+		if c.Type != clusterv1.ReadyCondition {
+			conditionsInScope = append(conditionsInScope, localizedCondition{
+				Condition: &c,
+				Getter:    from,
+			})
+		}
+	}
+
+	mergeOpt := &mergeOptions{}
+	for _, o := range options {
+		o(mergeOpt)
+	}
+	return merge(conditionsInScope, clusterv1.ReadyCondition, mergeOpt)
+}
+
+// Mirror mirrors the Ready condition from a dependent object into the target condition;
+// if the Ready condition does not exists in the source object, no target conditions is generated.
+func Mirror(from Getter, targetCondition clusterv1.ConditionType) *clusterv1.Condition {
+	condition := Get(from, clusterv1.ReadyCondition)
+
+	if condition != nil {
+		condition.Type = targetCondition
+	}
+
+	return condition
+}
+
+// Aggregates all the the Ready condition from a list of dependent objects into the target object;
+// if the Ready condition does not exists in one of the source object, the object is excluded from
+// the aggregation; if none of the source object have ready condition, no target conditions is generated.
+func Aggregate(from []Getter, targetCondition clusterv1.ConditionType, options ...MergeOption) *clusterv1.Condition {
+	conditionsInScope := make([]localizedCondition, 0, len(from))
+	for i := range from {
+		condition := Get(from[i], clusterv1.ReadyCondition)
+
+		conditionsInScope = append(conditionsInScope, localizedCondition{
+			Condition: condition,
+			Getter:    from[i],
+		})
+	}
+
+	mergeOpt := &mergeOptions{
+		stepCounter: len(from),
+	}
+	for _, o := range options {
+		o(mergeOpt)
+	}
+	return merge(conditionsInScope, targetCondition, mergeOpt)
+}

util/conditions/getter_test.go

@@ -91,6 +91,130 @@ func TestIsMethods(t *testing.T) {
 	g.Expect(GetLastTransitionTime(obj, "falseInfo1")).ToNot(BeNil())
 }
 
+func TestMirror(t *testing.T) {
+	foo := FalseCondition("foo", "reason foo", clusterv1.ConditionSeverityInfo, "message foo")
+	ready := TrueCondition(clusterv1.ReadyCondition)
+	readyBar := ready.DeepCopy()
+	readyBar.Type = "bar"
+
+	tests := []struct {
+		name string
+		from Getter
+		t    clusterv1.ConditionType
+		want *clusterv1.Condition
+	}{
+		{
+			name: "Returns nil when the ready condition does not exists",
+			from: getterWithConditions(foo),
+			want: nil,
+		},
+		{
+			name: "Returns ready condition from source",
+			from: getterWithConditions(ready, foo),
+			t:    "bar",
+			want: readyBar,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			g := NewWithT(t)
+
+			got := Mirror(tt.from, tt.t)
+			if tt.want == nil {
+				g.Expect(got).To(BeNil())
+				return
+			}
+			g.Expect(got).To(haveSameStateOf(tt.want))
+		})
+	}
+}
+
+func TestSummary(t *testing.T) {
+	foo := TrueCondition("foo")
+	bar := FalseCondition("bar", "reason falseInfo1", clusterv1.ConditionSeverityInfo, "message falseInfo1")
+	existingReady := FalseCondition(clusterv1.ReadyCondition, "reason falseError1", clusterv1.ConditionSeverityError, "message falseError1") //NB. existing ready has higher priority than other conditions
+
+	tests := []struct {
+		name string
+		from Getter
+		want *clusterv1.Condition
+	}{
+		{
+			name: "Returns nil when there are no conditions to summarize",
+			from: getterWithConditions(),
+			want: nil,
+		},
+		{
+			name: "Returns ready condition with the summary of existing conditions (with default options)",
+			from: getterWithConditions(foo, bar),
+			want: FalseCondition(clusterv1.ReadyCondition, "reason falseInfo1", clusterv1.ConditionSeverityInfo, "message falseInfo1"),
+		},
+		{
+			name: "Ignores existing Ready condition when computing the summary",
+			from: getterWithConditions(existingReady, foo, bar),
+			want: FalseCondition(clusterv1.ReadyCondition, "reason falseInfo1", clusterv1.ConditionSeverityInfo, "message falseInfo1"),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			g := NewWithT(t)
+
+			got := Summary(tt.from)
+			if tt.want == nil {
+				g.Expect(got).To(BeNil())
+				return
+			}
+			g.Expect(got).To(haveSameStateOf(tt.want))
+		})
+	}
+}
+
+func TestAggregate(t *testing.T) {
+	ready1 := TrueCondition(clusterv1.ReadyCondition)
+	ready2 := FalseCondition(clusterv1.ReadyCondition, "reason falseInfo1", clusterv1.ConditionSeverityInfo, "message falseInfo1")
+	bar := FalseCondition("bar", "reason falseError1", clusterv1.ConditionSeverityError, "message falseError1") //NB. bar has higher priority than other conditions
+
+	tests := []struct {
+		name string
+		from []Getter
+		t    clusterv1.ConditionType
+		want *clusterv1.Condition
+	}{
+		{
+			name: "Returns nil when there are no conditions to aggregate",
+			from: []Getter{},
+			want: nil,
+		},
+		{
+			name: "Returns foo condition with the aggregation of object's ready conditions",
+			from: []Getter{
+				getterWithConditions(ready1),
+				getterWithConditions(ready1),
+				getterWithConditions(ready2, bar),
+				getterWithConditions(),
+				getterWithConditions(bar),
+			},
+			t:    "foo",
+			want: FalseCondition("foo", "reason falseInfo1", clusterv1.ConditionSeverityInfo, "2 of 5 completed"),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			g := NewWithT(t)
+
+			got := Aggregate(tt.from, tt.t)
+			if tt.want == nil {
+				g.Expect(got).To(BeNil())
+				return
+			}
+			g.Expect(got).To(haveSameStateOf(tt.want))
+		})
+	}
+}
+
 func getterWithConditions(conditions ...*clusterv1.Condition) Getter {
 	obj := &clusterv1.Cluster{}
 	obj.SetConditions(conditionList(conditions...))

util/conditions/merge.go

@@ -0,0 +1,199 @@
+/*
+Copyright 2020 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package conditions
+
+import (
+	"sort"
+
+	corev1 "k8s.io/api/core/v1"
+	clusterv1 "sigs.k8s.io/cluster-api/api/v1alpha3"
+)
+
+// localizedCondition defines a condition with the information of the object the conditions
+// was originated from.
+type localizedCondition struct {
+	*clusterv1.Condition
+	Getter
+}
+
+// merge a list of condition into a single one.
+// This operation is designed to ensure visibility of the most relevant conditions for defining the
+// operational state of a component. E.g. If there is one error in the condition list, this one takes
+// priority over the other conditions and it is should be reflected in the target condition.
+//
+// More specifically:
+// 1. Conditions are grouped by status, severity
+// 2. The resulting condition groups are sorted according to the following priority:
+//   - P0 - Status=False, Severity=Error
+//   - P1 - Status=False, Severity=Warning
+//   - P2 - Status=False, Severity=Info
+//   - P3 - Status=True
+//   - P4 - Status=Unknown
+// 3. The group with highest priority is used to determine status, severity and other info of the target condition.
+//
+// Please note that the last operation includes also the task of computing the Reason and the Message for the target
+// condition; in order to complete such task some trade-off should be made, because there is no a golden rule
+// for summarizing many Reason/Message into single Reason/Message.
+// mergeOptions allows the user to adapt this process to the specific needs by exposing a set of merge strategies.
+func merge(conditions []localizedCondition, targetCondition clusterv1.ConditionType, options *mergeOptions) *clusterv1.Condition {
+	g := getConditionGroups(conditions)
+	if len(g) == 0 {
+		return nil
+	}
+
+	if g.TopGroup().status == corev1.ConditionTrue {
+		return TrueCondition(targetCondition)
+	}
+
+	targetReason := getReason(g, options)
+	targetMessage := getMessage(g, options)
+	if g.TopGroup().status == corev1.ConditionFalse {
+		return FalseCondition(targetCondition, targetReason, g.TopGroup().severity, targetMessage)
+	}
+	return UnknownCondition(targetCondition, targetReason, targetMessage)
+}
+
+// getConditionGroups groups a list of conditions according to status, severity values.
+// Additionally, the resulting groups are sorted by mergePriority.
+func getConditionGroups(conditions []localizedCondition) conditionGroups {
+	groups := conditionGroups{}
+
+	for i := range conditions {
+		condition := conditions[i]
+
+		if condition.Condition == nil {
+			continue
+		}
+
+		added := false
+		for i := range groups {
+			if groups[i].status == condition.Status && groups[i].severity == condition.Severity {
+				groups[i].conditions = append(groups[i].conditions, condition)
+				added = true
+				break
+			}
+		}
+		if !added {
+			groups = append(groups, conditionGroup{
+				conditions: []localizedCondition{condition},
+				status:     condition.Status,
+				severity:   condition.Severity,
+			})
+		}
+	}
+
+	// sort groups by priority
+	sort.Sort(groups)
+
+	// sorts conditions in the TopGroup so we ensure predictable result for merge strategies.
+	// condition are sorted using the same lexicographic order used by Set; in case two conditions
+	// have the same type, condition are sorted using according to the alphabetical order of the source object name.
+	if len(groups) > 0 {
+		sort.Slice(groups[0].conditions, func(i, j int) bool {
+			a := groups[0].conditions[i]
+			b := groups[0].conditions[j]
+			if a.Type != b.Type {
+				return lexicographicLess(a.Condition, b.Condition)
+			}
+			return a.GetName() < b.GetName()
+		})
+	}
+
+	return groups
+}
+
+// conditionGroups provides supports for grouping a list of conditions to be
+// merged into a single condition. ConditionGroups can be sorted by mergePriority.
+type conditionGroups []conditionGroup
+
+func (g conditionGroups) Len() int {
+	return len(g)
+}
+
+func (g conditionGroups) Less(i, j int) bool {
+	return g[i].mergePriority() < g[j].mergePriority()
+}
+
+func (g conditionGroups) Swap(i, j int) {
+	g[i], g[j] = g[j], g[i]
+}
+
+// TopGroup returns the the condition group with the highest mergePriority.
+func (g conditionGroups) TopGroup() *conditionGroup {
+	if len(g) == 0 {
+		return nil
+	}
+	return &g[0]
+}
+
+// TrueGroup returns the the condition group with status True, if any.
+func (g conditionGroups) TrueGroup() *conditionGroup {
+	return g.getByStatusAndSeverity(corev1.ConditionTrue, clusterv1.ConditionSeverityNone)
+}
+
+// ErrorGroup returns the the condition group with status False and severity Error, if any.
+func (g conditionGroups) ErrorGroup() *conditionGroup {
+	return g.getByStatusAndSeverity(corev1.ConditionFalse, clusterv1.ConditionSeverityError)
+}
+
+// WarningGroup returns the the condition group with status False and severity Warning, if any.
+func (g conditionGroups) WarningGroup() *conditionGroup {
+	return g.getByStatusAndSeverity(corev1.ConditionFalse, clusterv1.ConditionSeverityWarning)
+}
+
+func (g conditionGroups) getByStatusAndSeverity(status corev1.ConditionStatus, severity clusterv1.ConditionSeverity) *conditionGroup {
+	if len(g) == 0 {
+		return nil
+	}
+	for _, group := range g {
+		if group.status == status && group.severity == severity {
+			return &group
+		}
+	}
+	return nil
+}
+
+// conditionGroup define a group of conditions with the same status and severity,
+// and thus with the same priority when merging into a Ready condition.
+type conditionGroup struct {
+	status     corev1.ConditionStatus
+	severity   clusterv1.ConditionSeverity
+	conditions []localizedCondition
+}
+
+// mergePriority provides a priority value for the status and severity tuple that identifies this
+// condition group. The mergePriority value allows an easier sorting of conditions groups.
+func (g conditionGroup) mergePriority() int {
+	switch g.status {
+	case corev1.ConditionFalse:
+		switch g.severity {
+		case clusterv1.ConditionSeverityError:
+			return 0
+		case clusterv1.ConditionSeverityWarning:
+			return 1
+		case clusterv1.ConditionSeverityInfo:
+			return 2
+		}
+	case corev1.ConditionTrue:
+		return 3
+	case corev1.ConditionUnknown:
+		return 4
+	}
+
+	// this should never happen
+	return 99
+}