feat!: add Conditions to Projects

api/v1alpha1/conditions.go

@@ -36,6 +36,22 @@ const (
 	// reconciled.
 	ConditionTypeReconciling = "Reconciling"
 
+	// ConditionTypeStalled denotes that the reconciliation of the resource
+	// has stalled.
+	//
+	// This condition is used to indicate that the controller has stopped
+	// making progress on the resource, and further changes to the resource
+	// are not expected until the reason for the stall is resolved, which
+	// MAY require manual intervention. The condition is removed when the
+	// controller has resumed making progress on the resource.
+	//
+	// This is a "normal-false" or "negative polarity" condition, meaning
+	// that the presence of the condition with a status of "True" indicates
+	// that the resource has stalled, and the absence of the condition or
+	// a status of "False" indicates that the resource is operating as
+	// expected.
+	ConditionTypeStalled = "Stalled"
+
 	// ConditionTypeHealthy denotes that the resource is healthy.
 	//
 	// The meaning of "healthy" is specific to the resource type. For example,

api/v1alpha1/project_types.go

@@ -30,7 +30,8 @@
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:scope=Cluster
 // +kubebuilder:subresource:status
-// +kubebuilder:printcolumn:name=Phase,type=string,JSONPath=`.status.phase`
+// +kubebuilder:printcolumn:name="Ready",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].status"
+// +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.conditions[?(@.type==\"Ready\")].message"
 // +kubebuilder:printcolumn:name=Age,type=date,JSONPath=`.metadata.creationTimestamp`
 
 // Project is a resource type that reconciles to a specially labeled namespace
@@ -73,14 +74,33 @@
 
 // ProjectStatus describes a Project's current status.
 type ProjectStatus struct {
+	// Conditions contains the last observations of the Project's current
+	// state.
+	// +patchMergeKey=type
+	// +patchStrategy=merge
+	// +listType=map
+	// +listMapKey=type
+	Conditions []metav1.Condition `json:"conditions,omitempty" patchMergeKey:"type" patchStrategy:"merge" protobuf:"bytes,3,rep,name=conditions"`
 	// Phase describes the Project's current phase.
+	//
+	// Deprecated: Use the Conditions field instead.
 	Phase ProjectPhase `json:"phase,omitempty" protobuf:"bytes,1,opt,name=phase"`
 	// Message is a display message about the Project, including any errors
 	// preventing the Project from being reconciled. i.e. If the Phase field has a
 	// value of CreationFailed, this field can be expected to explain why.
+	//
+	// Deprecated: Use the Conditions field instead.
 	Message string `json:"message,omitempty" protobuf:"bytes,2,opt,name=message"`
 }
 
+func (w *ProjectStatus) GetConditions() []metav1.Condition {
+	return w.Conditions
+}
+
+func (w *ProjectStatus) SetConditions(conditions []metav1.Condition) {
+	w.Conditions = conditions
+}
+
 // +kubebuilder:object:root=true
 
 // ProjectList is a list of Project resources.

charts/kargo/resources/crds/kargo.akuity.io_projects.yaml

@@ -15,8 +15,11 @@ spec:
   scope: Cluster
   versions:
   - additionalPrinterColumns:
-    - jsonPath: .status.phase
-      name: Phase
+    - jsonPath: .status.conditions[?(@.type=="Ready")].status
+      name: Ready
+      type: string
+    - jsonPath: .status.conditions[?(@.type=="Ready")].message
+      name: Status
       type: string
     - jsonPath: .metadata.creationTimestamp
       name: Age
@@ -79,14 +82,96 @@ spec:
           status:
             description: Status describes the Project's current status.
             properties:
+              conditions:
+                description: |-
+                  Conditions contains the last observations of the Project's current
+                  state.
+                items:
+                  description: "Condition contains details for one aspect of the current
+                    state of this API Resource.\n---\nThis struct is intended for
+                    direct use as an array at the field path .status.conditions.  For
+                    example,\n\n\n\ttype FooStatus struct{\n\t    // Represents the
+                    observations of a foo's current state.\n\t    // Known .status.conditions.type
+                    are: \"Available\", \"Progressing\", and \"Degraded\"\n\t    //
+                    +patchMergeKey=type\n\t    // +patchStrategy=merge\n\t    // +listType=map\n\t
+                    \   // +listMapKey=type\n\t    Conditions []metav1.Condition `json:\"conditions,omitempty\"
+                    patchStrategy:\"merge\" patchMergeKey:\"type\" protobuf:\"bytes,1,rep,name=conditions\"`\n\n\n\t
+                    \   // other fields\n\t}"
+                  properties:
+                    lastTransitionTime:
+                      description: |-
+                        lastTransitionTime is the last time the condition transitioned from one status to another.
+                        This should be when the underlying condition changed.  If that is not known, then using the time when the API field changed is acceptable.
+                      format: date-time
+                      type: string
+                    message:
+                      description: |-
+                        message is a human readable message indicating details about the transition.
+                        This may be an empty string.
+                      maxLength: 32768
+                      type: string
+                    observedGeneration:
+                      description: |-
+                        observedGeneration represents the .metadata.generation that the condition was set based upon.
+                        For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
+                        with respect to the current state of the instance.
+                      format: int64
+                      minimum: 0
+                      type: integer
+                    reason:
+                      description: |-
+                        reason contains a programmatic identifier indicating the reason for the condition's last transition.
+                        Producers of specific condition types may define expected values and meanings for this field,
+                        and whether the values are considered a guaranteed API.
+                        The value should be a CamelCase string.
+                        This field may not be empty.
+                      maxLength: 1024
+                      minLength: 1
+                      pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
+                      type: string
+                    status:
+                      description: status of the condition, one of True, False, Unknown.
+                      enum:
+                      - "True"
+                      - "False"
+                      - Unknown
+                      type: string
+                    type:
+                      description: |-
+                        type of condition in CamelCase or in foo.example.com/CamelCase.
+                        ---
+                        Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be
+                        useful (see .node.status.conditions), the ability to deconflict is important.
+                        The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)
+                      maxLength: 316
+                      pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
+                      type: string
+                  required:
+                  - lastTransitionTime
+                  - message
+                  - reason
+                  - status
+                  - type
+                  type: object
+                type: array
+                x-kubernetes-list-map-keys:
+                - type
+                x-kubernetes-list-type: map
               message:
                 description: |-
                   Message is a display message about the Project, including any errors
                   preventing the Project from being reconciled. i.e. If the Phase field has a
                   value of CreationFailed, this field can be expected to explain why.
+
+
+                  Deprecated: Use the Conditions field instead.
                 type: string
               phase:
-                description: Phase describes the Project's current phase.
+                description: |-
+                  Phase describes the Project's current phase.
+
+
+                  Deprecated: Use the Conditions field instead.
                 type: string
             type: object
         type: object

internal/cli/cmd/get/projects.go

@@ -20,6 +20,7 @@
 	"github.com/akuity/kargo/internal/cli/io"
 	"github.com/akuity/kargo/internal/cli/kubernetes"
 	"github.com/akuity/kargo/internal/cli/templates"
+	"github.com/akuity/kargo/internal/conditions"
 	v1alpha1 "github.com/akuity/kargo/pkg/api/service/v1alpha1"
 )
 
@@ -134,10 +135,18 @@
 	rows := make([]metav1.TableRow, len(list.Items))
 	for i, item := range list.Items {
 		project := item.Object.(*kargoapi.Project) // nolint: forcetypeassert
+
+		var ready, status = string(metav1.ConditionUnknown), ""
+		if readyCond := conditions.Get(&project.Status, kargoapi.ConditionTypeReady); readyCond != nil {
+			ready = string(readyCond.Status)
+			status = readyCond.Message
+		}
+
 		rows[i] = metav1.TableRow{
 			Cells: []any{
 				project.Name,
-				project.Status.Phase,
+				ready,
+				status,
 				duration.HumanDuration(time.Since(project.CreationTimestamp.Time)),
 			},
 			Object: list.Items[i],
@@ -146,7 +155,8 @@
 	return &metav1.Table{
 		ColumnDefinitions: []metav1.TableColumnDefinition{
 			{Name: "Name", Type: "string"},
-			{Name: "Phase", Type: "string"},
+			{Name: "Ready", Type: "string"},
+			{Name: "Status", Type: "string"},
 			{Name: "Age", Type: "string"},
 		},
 		Rows: rows,