chore: publish richer InstanceSet instance status

apis/workloads/v1/instance_types.go

@@ -146,8 +146,8 @@ type InstanceSpec struct {
 
 // InstanceStatus2 defines the observed state of Instance
 type InstanceStatus2 struct {
-	// observedGeneration is the most recent generation observed for this InstanceSet. It corresponds to the
-	// InstanceSet's generation, which is updated on mutation by the API Server.
+	// observedGeneration is the most recent generation observed for this Instance. It corresponds to the
+	// Instance's generation, which is updated on mutation by the API Server.
 	//
 	// +optional
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
@@ -158,12 +158,18 @@ type InstanceStatus2 struct {
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// currentRevision, if not empty, indicates the version of the Instance used to generate pod.
+	// Represents whether the Pod managed by this Instance is currently present, terminating, or absent.
+	//
+	// +optional
+	// +kubebuilder:validation:Enum=Present;Terminating;Absent
+	CurrentState InstanceCurrentState `json:"currentState,omitempty"`
+
+	// currentRevision, if not empty, identifies the revision currently used by the Pod.
 	//
 	// +optional
 	CurrentRevision string `json:"currentRevision,omitempty"`
 
-	// updateRevision, if not empty, indicates the version of the Instance used to generate pod.
+	// updateRevision, if not empty, identifies the revision desired for the Pod.
 	//
 	// +optional
 	UpdateRevision string `json:"updateRevision,omitempty"`

apis/workloads/v1/instanceset_types.go

@@ -568,28 +568,117 @@ type ConfigTemplate struct {
 }
 
 type InstanceStatus struct {
-	// Represents the name of the pod.
+	// PodName is the stable instance identity allocated by the InstanceSet and the name used by its Pod when present.
 	//
 	// +kubebuilder:validation:Required
 	// +kubebuilder:default=Unknown
 	PodName string `json:"podName"`
 
-	// Represents the role of the instance observed.
+	// TemplateName is the instance template assigned to this instance.
+	// nil means that the template is unknown, while an empty string identifies the default template.
+	//
+	// +optional
+	TemplateName *string `json:"templateName,omitempty"`
+
+	// DesiredState describes whether this identity should have a running Pod (Active), is retained without a
+	// desired running Pod (Offline), or is no longer allocated and is kept only until its current Pod disappears (Released).
+	// An empty value from an older object is treated as Active.
+	//
+	// +optional
+	// +kubebuilder:validation:Enum=Active;Offline;Released
+	DesiredState InstanceDesiredState `json:"desiredState,omitempty"`
+
+	// CurrentState describes whether the Pod for this instance is currently present, terminating, or absent.
+	// An empty value from an older object is treated as Present because those entries were produced from observed Pods.
+	//
+	// +optional
+	// +kubebuilder:validation:Enum=Present;Terminating;Absent
+	CurrentState InstanceCurrentState `json:"currentState,omitempty"`
+
+	// CurrentRevision identifies the revision currently used by the Pod for this instance.
+	// It is empty when CurrentState is Absent.
+	//
+	// +optional
+	CurrentRevision string `json:"currentRevision,omitempty"`
+
+	// UpdateRevision identifies the Pod revision desired for an Active instance.
+	// It is empty for Offline and Released instances.
+	//
+	// +optional
+	UpdateRevision string `json:"updateRevision,omitempty"`
+
+	// UpToDate indicates that the workload owner has observed the Active instance fully applied the current
+	// InstanceSet desired state, including changes intentionally excluded from revision hashes.
+	// It can be true only when DesiredState is Active and CurrentState is Present.
+	//
+	// +optional
+	UpToDate bool `json:"upToDate,omitempty"`
+
+	// Ready indicates whether the current Present Pod is ready to serve requests.
+	//
+	// +optional
+	Ready bool `json:"ready,omitempty"`
+
+	// Available indicates whether the current Present Pod has remained ready for the required minimum duration.
+	// Available can be true only when Ready is true.
+	//
+	// +optional
+	Available bool `json:"available,omitempty"`
+
+	// Failed indicates whether the current Present Pod reports a terminal failure state. It is independent of
+	// desired-state convergence.
+	//
+	// +optional
+	Failed bool `json:"failed,omitempty"`
+
+	// Represents the role observed from the current Present Pod.
 	//
 	// +optional
 	Role string `json:"role,omitempty"`
 
-	// The status of configs.
+	// The config status observed from the current Present Pod.
 	//
 	// +optional
 	Configs []InstanceConfigStatus `json:"configs,omitempty"`
 
-	// Represents whether the instance is in volume expansion.
+	// Represents whether storage for the current Present Pod is being expanded.
 	//
 	// +optional
 	VolumeExpansion bool `json:"volumeExpansion,omitempty"`
 }
 
+type InstanceDesiredState string
+
+const (
+	InstanceDesiredStateActive   InstanceDesiredState = "Active"
+	InstanceDesiredStateOffline  InstanceDesiredState = "Offline"
+	InstanceDesiredStateReleased InstanceDesiredState = "Released"
+)
+
+type InstanceCurrentState string
+
+const (
+	InstanceCurrentStatePresent     InstanceCurrentState = "Present"
+	InstanceCurrentStateTerminating InstanceCurrentState = "Terminating"
+	InstanceCurrentStateAbsent      InstanceCurrentState = "Absent"
+)
+
+// EffectiveDesiredState returns DesiredState with the compatibility default for older persisted status entries.
+func (s *InstanceStatus) EffectiveDesiredState() InstanceDesiredState {
+	if s == nil || s.DesiredState == "" {
+		return InstanceDesiredStateActive
+	}
+	return s.DesiredState
+}
+
+// EffectiveCurrentState returns CurrentState with the compatibility default for older persisted status entries.
+func (s *InstanceStatus) EffectiveCurrentState() InstanceCurrentState {
+	if s == nil || s.CurrentState == "" {
+		return InstanceCurrentStatePresent
+	}
+	return s.CurrentState
+}
+
 type InstanceConfigStatus struct {
 	// The name of the config.
 	//
@@ -729,10 +818,98 @@ func (r *InstanceSet) IsRoleProbeDone() bool {
 		replicas = 0
 	}
 	cnt := 0
-	for _, inst := range r.Status.InstanceStatus {
+	for _, inst := range r.ActivePresentInstanceStatuses() {
 		if len(inst.Role) > 0 {
 			cnt++
 		}
 	}
 	return cnt == replicas
 }
+
+// FindInstanceStatus returns the status entry for podName.
+func (r *InstanceSet) FindInstanceStatus(podName string) *InstanceStatus {
+	if r == nil {
+		return nil
+	}
+	for i := range r.Status.InstanceStatus {
+		if r.Status.InstanceStatus[i].PodName == podName {
+			return &r.Status.InstanceStatus[i]
+		}
+	}
+	return nil
+}
+
+// ActiveInstanceStatuses returns the allocated instances that should be online.
+func (r *InstanceSet) ActiveInstanceStatuses() []*InstanceStatus {
+	return r.instanceStatusesByDesiredState(InstanceDesiredStateActive)
+}
+
+// OfflineInstanceStatuses returns the allocated instances retained offline.
+func (r *InstanceSet) OfflineInstanceStatuses() []*InstanceStatus {
+	return r.instanceStatusesByDesiredState(InstanceDesiredStateOffline)
+}
+
+// RetainedInstanceStatuses returns all instances whose identity is retained by the InstanceSet.
+func (r *InstanceSet) RetainedInstanceStatuses() []*InstanceStatus {
+	if r == nil {
+		return nil
+	}
+	result := make([]*InstanceStatus, 0, len(r.Status.InstanceStatus))
+	for i := range r.Status.InstanceStatus {
+		status := &r.Status.InstanceStatus[i]
+		if desiredState := status.EffectiveDesiredState(); desiredState == InstanceDesiredStateActive || desiredState == InstanceDesiredStateOffline {
+			result = append(result, status)
+		}
+	}
+	return result
+}
+
+// ActivePresentInstanceStatuses returns Active instances whose Pod is currently present.
+func (r *InstanceSet) ActivePresentInstanceStatuses() []*InstanceStatus {
+	if r == nil {
+		return nil
+	}
+	result := make([]*InstanceStatus, 0, len(r.Status.InstanceStatus))
+	for i := range r.Status.InstanceStatus {
+		status := &r.Status.InstanceStatus[i]
+		if status.EffectiveDesiredState() == InstanceDesiredStateActive && status.EffectiveCurrentState() == InstanceCurrentStatePresent {
+			result = append(result, status)
+		}
+	}
+	return result
+}
+
+// PresentInstanceStatuses returns instances whose current state is Present.
+func (r *InstanceSet) PresentInstanceStatuses() []*InstanceStatus {
+	if r == nil {
+		return nil
+	}
+	result := make([]*InstanceStatus, 0, len(r.Status.InstanceStatus))
+	for i := range r.Status.InstanceStatus {
+		status := &r.Status.InstanceStatus[i]
+		if status.EffectiveCurrentState() == InstanceCurrentStatePresent {
+			result = append(result, status)
+		}
+	}
+	return result
+}
+
+// HasPresentInstance reports whether instanceName currently identifies a Present instance.
+func (r *InstanceSet) HasPresentInstance(instanceName string) bool {
+	status := r.FindInstanceStatus(instanceName)
+	return status != nil && status.EffectiveCurrentState() == InstanceCurrentStatePresent
+}
+
+func (r *InstanceSet) instanceStatusesByDesiredState(desiredState InstanceDesiredState) []*InstanceStatus {
+	if r == nil {
+		return nil
+	}
+	result := make([]*InstanceStatus, 0, len(r.Status.InstanceStatus))
+	for i := range r.Status.InstanceStatus {
+		status := &r.Status.InstanceStatus[i]
+		if status.EffectiveDesiredState() == desiredState {
+			result = append(result, status)
+		}
+	}
+	return result
+}

config/crd/bases/workloads.kubeblocks.io_instances.yaml

@@ -10338,13 +10338,21 @@ spec:
                   type: object
                 type: array
               currentRevision:
-                description: currentRevision, if not empty, indicates the version
-                  of the Instance used to generate pod.
+                description: currentRevision, if not empty, identifies the revision
+                  currently used by the Pod.
+                type: string
+              currentState:
+                description: Represents whether the Pod managed by this Instance is
+                  currently present, terminating, or absent.
+                enum:
+                - Present
+                - Terminating
+                - Absent
                 type: string
               observedGeneration:
                 description: |-
-                  observedGeneration is the most recent generation observed for this InstanceSet. It corresponds to the
-                  InstanceSet's generation, which is updated on mutation by the API Server.
+                  observedGeneration is the most recent generation observed for this Instance. It corresponds to the
+                  Instance's generation, which is updated on mutation by the API Server.
                 format: int64
                 type: integer
               ready:
@@ -10357,8 +10365,8 @@ spec:
                 description: Represents whether the instance is up-to-date.
                 type: boolean
               updateRevision:
-                description: updateRevision, if not empty, indicates the version of
-                  the Instance used to generate pod.
+                description: updateRevision, if not empty, identifies the revision
+                  desired for the Pod.
                 type: string
               volumeExpansion:
                 description: Represents whether the instance is in volume expansion.

config/crd/bases/workloads.kubeblocks.io_instancesets.yaml

@@ -11660,8 +11660,14 @@ spec:
                 description: Provides the status of each instance in the ITS.
                 items:
                   properties:
+                    available:
+                      description: |-
+                        Available indicates whether the current Present Pod has remained ready for the required minimum duration.
+                        Available can be true only when Ready is true.
+                      type: boolean
                     configs:
-                      description: The status of configs.
+                      description: The config status observed from the current Present
+                        Pod.
                       items:
                         properties:
                           configHash:
@@ -11675,15 +11681,67 @@ spec:
                         - name
                         type: object
                       type: array
+                    currentRevision:
+                      description: |-
+                        CurrentRevision identifies the revision currently used by the Pod for this instance.
+                        It is empty when CurrentState is Absent.
+                      type: string
+                    currentState:
+                      description: |-
+                        CurrentState describes whether the Pod for this instance is currently present, terminating, or absent.
+                        An empty value from an older object is treated as Present because those entries were produced from observed Pods.
+                      enum:
+                      - Present
+                      - Terminating
+                      - Absent
+                      type: string
+                    desiredState:
+                      description: |-
+                        DesiredState describes whether this identity should have a running Pod (Active), is retained without a
+                        desired running Pod (Offline), or is no longer allocated and is kept only until its current Pod disappears (Released).
+                        An empty value from an older object is treated as Active.
+                      enum:
+                      - Active
+                      - Offline
+                      - Released
+                      type: string
+                    failed:
+                      description: |-
+                        Failed indicates whether the current Present Pod reports a terminal failure state. It is independent of
+                        desired-state convergence.
+                      type: boolean
                     podName:
                       default: Unknown
-                      description: Represents the name of the pod.
+                      description: PodName is the stable instance identity allocated
+                        by the InstanceSet and the name used by its Pod when present.
                       type: string
+                    ready:
+                      description: Ready indicates whether the current Present Pod
+                        is ready to serve requests.
+                      type: boolean
                     role:
-                      description: Represents the role of the instance observed.
+                      description: Represents the role observed from the current Present
+                        Pod.
+                      type: string
+                    templateName:
+                      description: |-
+                        TemplateName is the instance template assigned to this instance.
+                        nil means that the template is unknown, while an empty string identifies the default template.
+                      type: string
+                    upToDate:
+                      description: |-
+                        UpToDate indicates that the workload owner has observed the Active instance fully applied the current
+                        InstanceSet desired state, including changes intentionally excluded from revision hashes.
+                        It can be true only when DesiredState is Active and CurrentState is Present.
+                      type: boolean
+                    updateRevision:
+                      description: |-
+                        UpdateRevision identifies the Pod revision desired for an Active instance.
+                        It is empty for Offline and Released instances.
                       type: string
                     volumeExpansion:
-                      description: Represents whether the instance is in volume expansion.
+                      description: Represents whether storage for the current Present
+                        Pod is being expanded.
                       type: boolean
                   required:
                   - podName