chore: refine the sharding action

apis/apps/v1/cluster_types.go

@@ -226,7 +226,7 @@ type ClusterStatus struct {
 	// Records the current status information of all shardings within the Cluster.
 	//
 	// +optional
-	Shardings map[string]ClusterComponentStatus `json:"shardings,omitempty"`
+	Shardings map[string]ClusterShardingStatus `json:"shardings,omitempty"`
 
 	// Represents a list of detailed status of the Cluster object.
 	// Each condition in the list provides real-time information about certain aspect of the Cluster object.
@@ -924,3 +924,95 @@ type ClusterComponentStatus struct {
 	// +optional
 	UpToDate bool `json:"upToDate,omitempty"`
 }
+
+// ClusterShardingStatus records a sharding status.
+type ClusterShardingStatus struct {
+	// Specifies the current state of the sharding.
+	//
+	// +optional
+	Phase ComponentPhase `json:"phase,omitempty"`
+
+	// Records detailed information about the sharding in its current phase.
+	//
+	// +optional
+	Message map[string]string `json:"message,omitempty"`
+
+	// Indicates the most recent generation of the sharding state observed.
+	//
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
+	// Indicates whether the sharding state observed is up-to-date with the desired state.
+	//
+	// +optional
+	UpToDate bool `json:"upToDate,omitempty"`
+
+	// Records the name of the sharding definition used.
+	//
+	// +optional
+	ShardingDef string `json:"shardingDef,omitempty"`
+
+	// PostProvision records the status of the sharding post-provision action.
+	//
+	// +optional
+	PostProvision *LifecycleActionStatus `json:"postProvision,omitempty"`
+
+	// PreTerminate records the status of the sharding pre-terminate action.
+	//
+	// +optional
+	PreTerminate *LifecycleActionStatus `json:"preTerminate,omitempty"`
+}
+
+// LifecycleActionStatus records the observed state of a lifecycle-related action.
+type LifecycleActionStatus struct {
+	// Phase is the current phase of the lifecycle action.
+	//
+	// +optional
+	Phase LifecycleActionPhase `json:"phase,omitempty"`
+
+	// Reason is a programmatic identifier indicating the reason for the current phase.
+	// e.g., 'PreconditionNotMet' for Pending phase or 'PrerequisiteFailed' for Skipped phase.
+	//
+	// +optional
+	// Reason string `json:"reason,omitempty"`
+
+	// Message is a human-readable message providing details about the current phase.
+	//
+	// +optional
+	Message string `json:"message,omitempty"`
+
+	// StartTime records the time when the action started execution.
+	//
+	// +optional
+	StartTime *metav1.Time `json:"startTime,omitempty"`
+
+	// CompletionTime records the time when the action reached a terminal state (Succeeded, Failed, or Skipped).
+	//
+	// +optional
+	CompletionTime *metav1.Time `json:"completionTime,omitempty"`
+}
+
+// LifecycleActionPhase describes the current phase of a lifecycle-related action.
+//
+// +enum
+// +kubebuilder:validation:Enum={Pending,Running,Succeeded,Failed,Skipped}
+type LifecycleActionPhase string
+
+const (
+	// LifecycleActionPending indicates the action is registered and waiting to be triggered or
+	// waiting for its dynamic preconditions to be met.
+	LifecycleActionPending LifecycleActionPhase = "Pending"
+
+	// LifecycleActionRunning indicates the preconditions are met and the action is currently being executed.
+	LifecycleActionRunning LifecycleActionPhase = "Running"
+
+	// LifecycleActionSucceeded indicates the action has completed successfully.
+	LifecycleActionSucceeded LifecycleActionPhase = "Succeeded"
+
+	// LifecycleActionFailed indicates the action has failed during execution or timed out.
+	LifecycleActionFailed LifecycleActionPhase = "Failed"
+
+	// LifecycleActionSkipped indicates the action was intentionally bypassed.
+	// Usually occurs if a prerequisite action failed or a permanent condition was not met.
+	LifecycleActionSkipped LifecycleActionPhase = "Skipped"
+)

apis/apps/v1/component_types.go

@@ -348,9 +348,6 @@ type ComponentSpec struct {
 
 	// Specifies custom actions that can be performed on the Component.
 	//
-	// Each custom action defines a specific operation that can be executed,
-	// will be merged with ComponentLifecycleActions defined in referenced ComponentDefinition.
-	//
 	// +optional
 	CustomActions []CustomAction `json:"customActions,omitempty"`
 }

apis/apps/v1/shardingdefinition_types.go

@@ -166,7 +166,7 @@ type ShardingLifecycleActions struct {
 	//
 	// With `ComponentReady` being the default.
 	//
-	// The PostProvision Action is intended to run only once.
+	// The PostProvision action is intended to run only once.
 	//
 	// Note: This field is immutable once it has been set.
 	//
@@ -175,12 +175,15 @@ type ShardingLifecycleActions struct {
 
 	// Specifies the hook to be executed prior to terminating a sharding.
 	//
-	// The PreTerminate Action is intended to run only once.
+	// The PreTerminate action is intended to run only once.
 	//
 	// This action is executed immediately when a terminate operation for the sharding is initiated.
 	// The actual termination and cleanup of the sharding and its associated resources will not proceed
 	// until the PreTerminate action has completed successfully.
 	//
+	// If a PostProvision action is defined, this action will only execute if PostProvision reaches
+	// the 'Succeeded' phase. If the defined PostProvision fails, this action will be skipped.
+	//
 	// Note: This field is immutable once it has been set.
 	//
 	// +optional
@@ -233,12 +236,14 @@ type ShardingTLS struct {
 type ShardingAction struct {
 	Action `json:",inline"`
 
-	// Defines the criteria used to select the target Shard(s) for executing the Action.
-	// It allows for precise control over which Shard(s) the Action should run in.
+	// Defines the criteria used to select the target shard(s) for executing the Action.
+	// It provides precise control over which shard(s) should be targeted.
 	//
-	// For shardAdd or shardRemove, the Action will be executed in the Shard where the Action is triggered.
-	// For other actions, you can choose to execute the action randomly on one shard or on all shards,
-	// if not specified, a shard is randomly selected by default.
+	// The default selection logic (when this field is omitted) is context-dependent:
+	// 1. Contextual Default: If the Action is triggered by or originates from a specific shard,
+	//    that shard is selected as the default target.
+	// 2. Global Default: In other cases (where no specific shard context exists),
+	//    one shard is selected randomly by default.
 	//
 	// This field cannot be updated.
 	//

config/crd/bases/apps.kubeblocks.io_clusters.yaml

@@ -18037,21 +18037,21 @@ spec:
                 type: string
               shardings:
                 additionalProperties:
-                  description: ClusterComponentStatus records Component status.
+                  description: ClusterShardingStatus records a sharding status.
                   properties:
                     message:
                       additionalProperties:
                         type: string
-                      description: Records detailed information about the Component
+                      description: Records detailed information about the sharding
                         in its current phase.
                       type: object
                     observedGeneration:
-                      description: Indicates the most recent generation of the component
+                      description: Indicates the most recent generation of the sharding
                         state observed.
                       format: int64
                       type: integer
                     phase:
-                      description: Specifies the current state of the Component.
+                      description: Specifies the current state of the sharding.
                       enum:
                       - Creating
                       - Deleting
@@ -18062,9 +18062,70 @@ spec:
                       - Stopped
                       - Failed
                       type: string
+                    postProvision:
+                      description: PostProvision records the status of the sharding
+                        post-provision action.
+                      properties:
+                        completionTime:
+                          description: CompletionTime records the time when the action
+                            reached a terminal state (Succeeded, Failed, or Skipped).
+                          format: date-time
+                          type: string
+                        message:
+                          description: Message is a human-readable message providing
+                            details about the current phase.
+                          type: string
+                        phase:
+                          description: Phase is the current phase of the lifecycle
+                            action.
+                          enum:
+                          - Pending
+                          - Running
+                          - Succeeded
+                          - Failed
+                          - Skipped
+                          type: string
+                        startTime:
+                          description: StartTime records the time when the action
+                            started execution.
+                          format: date-time
+                          type: string
+                      type: object
+                    preTerminate:
+                      description: PreTerminate records the status of the sharding
+                        pre-terminate action.
+                      properties:
+                        completionTime:
+                          description: CompletionTime records the time when the action
+                            reached a terminal state (Succeeded, Failed, or Skipped).
+                          format: date-time
+                          type: string
+                        message:
+                          description: Message is a human-readable message providing
+                            details about the current phase.
+                          type: string
+                        phase:
+                          description: Phase is the current phase of the lifecycle
+                            action.
+                          enum:
+                          - Pending
+                          - Running
+                          - Succeeded
+                          - Failed
+                          - Skipped
+                          type: string
+                        startTime:
+                          description: StartTime records the time when the action
+                            started execution.
+                          format: date-time
+                          type: string
+                      type: object
+                    shardingDef:
+                      description: Records the name of the sharding definition used.
+                      type: string
                     upToDate:
-                      description: Indicates whether the component state observed
-                        is up-to-date with the desired state.
+                      description: Indicates whether the sharding state observed is
+                        up-to-date with the desired state.
                       type: boolean
                   type: object
                 description: Records the current status information of all shardings

config/crd/bases/apps.kubeblocks.io_components.yaml

@@ -619,12 +619,8 @@ spec:
                   type: object
                 type: array
               customActions:
-                description: |-
-                  Specifies custom actions that can be performed on the Component.
-
-
-                  Each custom action defines a specific operation that can be executed,
-                  will be merged with ComponentLifecycleActions defined in referenced ComponentDefinition.
+                description: Specifies custom actions that can be performed on the
+                  Component.
                 items:
                   properties:
                     action: