address comments

apis/placement/v1alpha1/stagedupdate_types.go

@@ -23,6 +23,7 @@ import (
 // unselected after all the stages explicitly defined in the updateStrategy complete.
 // Each StagedUpdateRun object corresponds to a single "release" of a certain version of the resources.
 // The release is abandoned if the StagedUpdateRun object is deleted or the scheduling decision (i.e., the selected clusters) changes.
+// The name of the StagedUpdateRun needs to conform to [RFC 1123](https://tools.ietf.org/html/rfc1123).
 type StagedUpdateRun struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -37,8 +38,8 @@ type StagedUpdateRun struct {
 	Status StagedUpdateRunStatus `json:"status,omitempty"`
 }
 
-// StagedUpdateRunSpec defines the desired the update strategy and the snapshot indices
-// on which the update is based.
+// StagedUpdateRunSpec defines the desired rollout strategy and the snapshot indices of the resources to be updated.
+// It specifies a stage-by-stage update process across selected clusters for the given ResourcePlacement object.
 type StagedUpdateRunSpec struct {
 	// A reference to the placement that this update run is applied to.
 	// There can be multiple active update runs for each placement but
@@ -78,8 +79,8 @@ type StagedUpdateStrategy struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	// Stage configurations for each update stage.
-	// +kubebuilder:validation:MaxItems=127
+	// Stage specifies the configuration for each update stage.
+	// +kubebuilder:validation:MaxItems=31
 	// +kubebuilder:validation:Required
 	Stages []StageConfig `json:"stages"`
 }
@@ -98,6 +99,8 @@ type StagedUpdateStrategyList struct {
 // We will stop the update if any of the updates fail.
 type StageConfig struct {
 	// The name of the stage. This MUST be unique within the same StagedUpdateStrategy.
+	// +kubebuilder:validation:MaxLength=63
+	// +kubebuilder:validation:Pattern="[A-Za-z0-9]+$"
 	// +kubebuilder:validation:Required
 	Name string `json:"name"`
 
@@ -116,6 +119,7 @@ type StageConfig struct {
 
 	// The collection of tasks that each stage needs to complete successfully before moving to the next stage.
 	// Each task is executed in parallel and there can not be more than one task of the same type.
+	// +kubebuilder:validation:MaxItems=2
 	// +kubebuilder:validation:Optional
 	AfterStageTasks []AfterStageTask `json:"afterStageTasks,omitempty"`
 }
@@ -131,7 +135,7 @@ type AfterStageTask struct {
 	// We create the full name of the approval request by concatenating the prefix to the stagedUpdateRunName and the stageName.
 	// For example, if the approvalRequestPrefix is "myApproval", the name of the approval request for the stage "stage1"
 	// in the update run "updateRun1" is "myApproval-updateRun1-stage1".
-	// We will generate the name of the approval request by default if the prefix is absent.
+	// The name of the approval request is "updateRun1-stage1" if the prefix is absent.
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:Pattern="[A-Za-z0-9]+$"
 	// +kubebuilder:validation:MaxLength=32
@@ -148,28 +152,15 @@ type AfterStageTask struct {
 // StagedUpdateRunStatus defines the observed state of the StagedUpdateRun.
 type StagedUpdateRunStatus struct {
 	// UpdateRunStrategy is the collection of the stageConfig in the StagedUpdateStrategy that we are going to use for the update.
-	// +kubebuilder:validation:Required
-	// +kubebuilder:validation:MaxItems=128
+	// +kubebuilder:validation:MaxItems=32
+	// +kubebuilder:validation:Optional
 	UpdateRunStrategy []StageConfig `json:"updateRunStrategy"`
 
 	// ApplyStrategy is the apply strategy that the stagedUpdateRun is using.
 	// It is the same as the apply strategy in the CRP when we first start the staged update run.
 	// We will NOT update the apply strategy during the update run even if the apply strategy changes in the CRP.
-	// +kubebuilder:validation:Required
-	ApplyStrategy v1beta1.ApplyStrategy `json:"appliedStrategy"`
-
-	// ResourceOverrideSnapshots is a list of ResourceOverride snapshots associated with the selected resources.
-	// The list computed as the beginning of the update run and not updated during the update run.
-	// The list is empty if there are no resource overrides associated with the selected resources.
-	// +kubebuilder:validation:Optional
-	ResourceOverrideSnapshots []v1beta1.NamespacedName `json:"resourceOverrideSnapshots,omitempty"`
-
-	// ClusterResourceOverrides contains a list of applicable ClusterResourceOverride snapshot names associated with the
-	// selected resources.
-	// The list computed as the beginning of the update run and not updated during the update run.
-	// The list is empty if there are no cluster overrides associated with the selected resources.
 	// +kubebuilder:validation:Optional
-	ClusterResourceOverrideSnapshots []string `json:"clusterResourceOverrideSnapshots,omitempty"`
+	ApplyStrategy v1beta1.ApplyStrategy `json:"appliedStrategy"`
 
 	// CurrentUpdatingStage is the name of the stage that is in the middle of the update.
 	// If the update run is not started, the value is an empty string.
@@ -212,6 +203,7 @@ type StageStatus struct {
 	Clusters []ClusterUpdateStatus `json:"clusters"`
 
 	// The status of the post update tasks that are associated with current stage.
+	// +kubebuilder:validation:MaxItems=2
 	// +kubebuilder:validation:Optional
 	AfterStageTaskStatus []AfterStageTaskStatus `json:"currentPostStageTaskStatus,omitempty"`
 }
@@ -222,6 +214,19 @@ type ClusterUpdateStatus struct {
 	// +kubebuilder:validation:Required
 	ClusterName string `json:"clusterName"`
 
+	// ResourceOverrideSnapshots is a list of ResourceOverride snapshots associated with the cluster.
+	// The list is computed at the beginning of the update run and not updated during the update run.
+	// The list is empty if there are no resource overrides associated with the cluster.
+	// +kubebuilder:validation:Optional
+	ResourceOverrideSnapshots []v1beta1.NamespacedName `json:"resourceOverrideSnapshots,omitempty"`
+
+	// ClusterResourceOverrides contains a list of applicable ClusterResourceOverride snapshot names
+	// associated with the cluster.
+	// The list is computed at the beginning of the update run and not updated during the update run.
+	// The list is empty if there are no cluster overrides associated with the cluster.
+	// +kubebuilder:validation:Optional
+	ClusterResourceOverrideSnapshots []string `json:"clusterResourceOverrideSnapshots,omitempty"`
+
 	// The status of the update run in the stage.
 	// +kubebuilder:validation:Required
 	Status UpdateStatus `json:"status"`
@@ -231,7 +236,7 @@ type ClusterUpdateStatus struct {
 type UpdateStatus struct {
 	// The status of the update on the cluster.
 	// +kubebuilder:validation:Required
-	// +kubebuilder:validation:Enum=NotStarted;Running;Completed;Failed;WaitingForApproval
+	// +kubebuilder:validation:Enum=NotStarted;Running;Completed;Failed;Waiting
 	State UpdateState `json:"state"`
 
 	// Message is a human readable message containing details about the update status.
@@ -241,10 +246,14 @@ type UpdateStatus struct {
 
 	// The time when the update started on the resource.
 	// +kubebuilder:validation:Optional
+	// +kubebuilder:validation:Pattern="^0|([0-9]+(\\.[0-9]+)?(s|m|h))+$"
+	// +kubebuilder:validation:Type=string
 	StartTime *metav1.Time `json:"startTime,omitempty"`
 
 	// The time when the update completed on the resource.
 	// +kubebuilder:validation:Optional
+	// +kubebuilder:validation:Pattern="^0|([0-9]+(\\.[0-9]+)?(s|m|h))+$"
+	// +kubebuilder:validation:Type=string
 	CompletedTime *metav1.Time `json:"completedTime,omitempty"`
 
 	// The error detail if the update failed on the resource.
@@ -270,8 +279,9 @@ const (
 	// UpdateStateFailed indicates the update run is failed on this resource.
 	UpdateStateFailed UpdateState = "Failed"
 
-	// UpdateStateWaitingForApproval indicates the update run is waiting for approval on this resource.
-	UpdateStateWaitingForApproval UpdateState = "WaitingForApproval"
+	// UpdateStateWaiting indicates the update run is waiting for approval or
+	// wait for the wait time to elapse on this resource.
+	UpdateStateWaiting UpdateState = "Waiting"
 )
 
 type AfterStageTaskStatus struct {
@@ -280,6 +290,11 @@ type AfterStageTaskStatus struct {
 	// +kubebuilder:validation:Required
 	Type AfterStageTaskType `json:"type"`
 
+	// The name of the approval request object that is created for this stage.
+	// Only valid if the AfterStageTaskType is Approval.
+	// +kubebuilder:validation:Optional
+	ApprovalRequestName string `json:"approvalRequestName,omitempty"`
+
 	// +patchMergeKey=type
 	// +patchStrategy=merge
 	// +listType=map
@@ -333,6 +348,13 @@ const (
 type StagedUpdateRunConditionType string
 
 const (
+	// StagedUpdateRunConditionInitialized indicates whether the staged update run is initialized which means it
+	// has computed all the stages according to the referenced strategy and is ready to start the update.
+	// Its condition status can be one of the following:
+	// - "True" means the staged update run is initialized.
+	// - "False" means the staged update run encountered an error during initialization.
+	StagedUpdateRunConditionInitialized StagedUpdateRunConditionType = "Initialized"
+
 	// StagedUpdateRunConditionRunning indicates whether the staged update run is proceeding normally.
 	// Its condition status can be one of the following:
 	// - "True" means the staged update run is proceeding normally.
@@ -346,6 +368,12 @@ const (
 	// - "False" means the staged update run is not waiting between stages.
 	// - "Unknown" means it is unknown.
 	StagedUpdateRunConditionWaitingBetweenStage StagedUpdateRunConditionType = "WaitingBetweenStage"
+
+	// StagedUpdateRunConditionCompleted indicates whether the staged update run is completed.
+	// Its condition status can be one of the following:
+	// - "True" means the staged update run is completed successfully.
+	// - "False" means the staged update run encountered an error during running.
+	StagedUpdateRunConditionCompleted StagedUpdateRunConditionType = "Completed"
 )
 
 // StagedUpdateRunList contains a list of StagedUpdateRun.