Merge branch 'main' into support/migrate-config-manager-to-kbagent

Author: leon-ape

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.
@@ -641,9 +641,9 @@ type ClusterSharding struct {
 	// between the desired and actual number of shards.
 	// KubeBlocks provides lifecycle management for sharding, including:
 	//
-	// - Executing the shardProvision Action defined in the ShardingDefinition when the number of shards increases.
+	// - Executing the shardAdd Action defined in the ShardingDefinition when the number of shards increases.
 	//   This allows for custom actions to be performed after a new shard is provisioned.
-	// - Executing the shardTerminate Action defined in the ShardingDefinition when the number of shards decreases.
+	// - Executing the shardRemove Action defined in the ShardingDefinition when the number of shards decreases.
 	//   This enables custom cleanup or data migration tasks to be executed before a shard is terminated.
 	//   Resources and data associated with the corresponding Component will also be deleted.
 	//
@@ -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

@@ -345,6 +345,11 @@ type ComponentSpec struct {
 	//
 	// +optional
 	EnableInstanceAPI *bool `json:"enableInstanceAPI,omitempty"`
+
+	// Specifies custom actions that can be performed on the Component.
+	//
+	// +optional
+	CustomActions []CustomAction `json:"customActions,omitempty"`
 }
 
 // ComponentStatus represents the observed state of a Component within the Cluster.
@@ -407,6 +412,20 @@ type Sidecar struct {
 	SidecarDef string `json:"sidecarDef"`
 }
 
+type CustomAction struct {
+	// Name specifies the unique name of the custom action.
+	//
+	// The name will be used as the action name when invoking the action.
+	//
+	// +kubebuilder:validation:Required
+	Name string `json:"name"`
+
+	// Specifies the action to be performed.
+	//
+	// +kubebuilder:validation:Required
+	Action *Action `json:"action"`
+}
+
 // ComponentPhase defines the phase of the Component within the .status.phase field.
 //
 // +enum

apis/apps/v1/shardingdefinition_types.go

@@ -166,39 +166,50 @@ 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.
 	//
 	// +optional
-	PostProvision *Action `json:"postProvision,omitempty"`
+	PostProvision *ShardingAction `json:"postProvision,omitempty"`
 
 	// 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
-	PreTerminate *Action `json:"preTerminate,omitempty"`
+	PreTerminate *ShardingAction `json:"preTerminate,omitempty"`
 
 	// Specifies the hook to be executed after a shard added.
 	//
+	// The container executing this action has access to following variables:
+	//
+	// - KB_ADD_SHARD_NAME: The name of the shard being added.
+	//
 	// Note: This field is immutable once it has been set.
 	//
 	// +optional
-	ShardAdd *Action `json:"shardAdd,omitempty"`
+	ShardAdd *ShardingAction `json:"shardAdd,omitempty"`
 
 	// Specifies the hook to be executed prior to remove a shard.
 	//
+	// The container executing this action has access to following variables:
+	//
+	// - KB_REMOVE_SHARD_NAME: The name of the shard being removed.
+	//
 	// Note: This field is immutable once it has been set.
 	//
 	// +optional
-	ShardRemove *Action `json:"shardRemove,omitempty"`
+	ShardRemove *ShardingAction `json:"shardRemove,omitempty"`
 }
 
 type ShardingSystemAccount struct {
@@ -221,3 +232,31 @@ type ShardingTLS struct {
 	// +optional
 	Shared *bool `json:"shared,omitempty"`
 }
+
+type ShardingAction struct {
+	Action `json:",inline"`
+
+	// 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.
+	//
+	// 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.
+	//
+	// +optional
+	TargetShardSelector TargetShardSelector `json:"targetShardSelector,omitempty"`
+}
+
+// TargetShardSelector defines how to select shard(s) to execute an Action.
+// +enum
+// +kubebuilder:validation:Enum={Any,All}
+type TargetShardSelector string
+
+const (
+	AnyShard  TargetShardSelector = "Any"
+	AllShards TargetShardSelector = "All"
+)