revise API

Signed-off-by: Wantong Jiang <wantjian@microsoft.com>

Author: jwtty

apis/placement/v1beta1/clusterresourceplacement_types.go

@@ -813,6 +813,7 @@ type RollingUpdateConfig struct {
 // ClusterResourcePlacementStatus defines the observed state of the ClusterResourcePlacement object.
 type ClusterResourcePlacementStatus struct {
 	// SelectedResources contains a list of resources selected by ResourceSelectors.
+	// This field is only meaningful if the `ObservedResourceIndex` is not empty.
 	// +kubebuilder:validation:Optional
 	SelectedResources []ResourceIdentifier `json:"selectedResources,omitempty"`
 
@@ -822,17 +823,16 @@ type ClusterResourcePlacementStatus struct {
 	// One resource snapshot can contain multiple clusterResourceSnapshots CRs in order to store large amount of resources.
 	// To get clusterResourceSnapshot of a given resource index, use the following command:
 	// `kubectl get ClusterResourceSnapshot --selector=kubernetes-fleet.io/resource-index=$ObservedResourceIndex `
-	// During rollout, clusters may run different versions of the resource snapshot concurrently.
-	// In this case, ObservedResourceIndex represents the index of the latest resource snapshot installed across all clusters.
-	// Note that this may differ from the index of the latest resource snapshot available in the hub cluster depending on the rollout strategy.
 	// ObservedResourceIndex is the resource index that the conditions in the ClusterResourcePlacementStatus observe.
 	// For example, a condition of `ClusterResourcePlacementWorkSynchronized` type
 	// is observing the synchronization status of the resource snapshot with the resource index $ObservedResourceIndex.
+	// If the rollout strategy type is `RollingUpdate`, `ObservedResourceIndex` is the default-latest resource snapshot index.
+	// If the rollout strategy type is `External`, rollout and version control are managed by an external controller, and this field remains empty.
 	// +kubebuilder:validation:Optional
 	ObservedResourceIndex string `json:"observedResourceIndex,omitempty"`
 
 	// PlacementStatuses contains a list of placement status on the clusters that are selected by PlacementPolicy.
-	// Each selected cluster according to the latest resource placement is guaranteed to have a corresponding placementStatuses.
+	// Each selected cluster according to the observed resource placement is guaranteed to have a corresponding placementStatuses.
 	// In the pickN case, there are N placement statuses where N = NumberOfClusters; Or in the pickFixed case, there are
 	// N placement statuses where N = ClusterNames.
 	// In these cases, some of them may not have assigned clusters when we cannot fill the required number of clusters.
@@ -957,7 +957,7 @@ type ResourcePlacementStatus struct {
 	// +kubebuilder:validation:MaxItems=100
 	DiffedPlacements []DiffedResourcePlacement `json:"diffedPlacements,omitempty"`
 
-	// ObservedResourceIndex is the index of the resource snapshot that is currently rolled out on the given cluster.
+	// ObservedResourceIndex is the index of the resource snapshot that is currently being rolled out to the given cluster.
 	// During rollout, depending on the rollout strategy, clusters may observe different resource indices.
 	// ObservedResourceIndex is the resource snapshot index observed by the conditions in the ResourcePlacementStatus.
 	// This field is only meaningful if the `ClusterName` is not empty.

config/crd/bases/placement.kubernetes-fleet.io_clusterresourceplacements.yaml

@@ -2044,17 +2044,16 @@ spec:
                   One resource snapshot can contain multiple clusterResourceSnapshots CRs in order to store large amount of resources.
                   To get clusterResourceSnapshot of a given resource index, use the following command:
                   `kubectl get ClusterResourceSnapshot --selector=kubernetes-fleet.io/resource-index=$ObservedResourceIndex `
-                  During rollout, clusters may run different versions of the resource snapshot concurrently.
-                  In this case, ObservedResourceIndex represents the index of the latest resource snapshot installed across all clusters.
-                  Note that this may differ from the index of the latest resource snapshot available in the hub cluster depending on the rollout strategy.
                   ObservedResourceIndex is the resource index that the conditions in the ClusterResourcePlacementStatus observe.
                   For example, a condition of `ClusterResourcePlacementWorkSynchronized` type
                   is observing the synchronization status of the resource snapshot with the resource index $ObservedResourceIndex.
+                  If the rollout strategy type is `RollingUpdate`, `ObservedResourceIndex` is the default-latest resource snapshot index.
+                  If the rollout strategy type is `External`, rollout and version control are managed by an external controller, and this field remains empty.
                 type: string
               placementStatuses:
                 description: |-
                   PlacementStatuses contains a list of placement status on the clusters that are selected by PlacementPolicy.
-                  Each selected cluster according to the latest resource placement is guaranteed to have a corresponding placementStatuses.
+                  Each selected cluster according to the observed resource placement is guaranteed to have a corresponding placementStatuses.
                   In the pickN case, there are N placement statuses where N = NumberOfClusters; Or in the pickFixed case, there are
                   N placement statuses where N = ClusterNames.
                   In these cases, some of them may not have assigned clusters when we cannot fill the required number of clusters.
@@ -2505,16 +2504,17 @@ spec:
                       type: array
                     observedResourceIndex:
                       description: |-
-                        ObservedResourceIndex is the index of the resource snapshot that is currently rolled out on the given cluster.
+                        ObservedResourceIndex is the index of the resource snapshot that is currently being rolled out to the given cluster.
                         During rollout, depending on the rollout strategy, clusters may observe different resource indices.
                         ObservedResourceIndex is the resource snapshot index observed by the conditions in the ResourcePlacementStatus.
                         This field is only meaningful if the `ClusterName` is not empty.
                       type: string
                   type: object
                 type: array
               selectedResources:
-                description: SelectedResources contains a list of resources selected
-                  by ResourceSelectors.
+                description: |-
+                  SelectedResources contains a list of resources selected by ResourceSelectors.
+                  This field is only meaningful if the `ObservedResourceIndex` is not empty.
                 items:
                   description: ResourceIdentifier identifies one Kubernetes resource.
                   properties: