revise

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

Author: jwtty

apis/placement/v1beta1/clusterresourceplacement_types.go

@@ -822,12 +822,10 @@ type ClusterResourcePlacementStatus struct {
 	// Each snapshot has a different resource index.
 	// 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 `
-	// 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.
+	// `kubectl get ClusterResourceSnapshot --selector=kubernetes-fleet.io/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.
+	// If the rollout strategy type is `External`, rollout and version control are managed by an external controller,
+	// and this field is not empty only if all targeted clusters observe the same resource index in `PlacementStatuses`.
 	// +kubebuilder:validation:Optional
 	ObservedResourceIndex string `json:"observedResourceIndex,omitempty"`
 
@@ -846,6 +844,11 @@ type ClusterResourcePlacementStatus struct {
 	// +listMapKey=type
 
 	// Conditions is an array of current observed conditions for ClusterResourcePlacement.
+	// All conditions except `ClusterResourcePlacementScheduled` correspond to the resource snapshot at the index specified by `ObservedResourceIndex`.
+	// For example, a condition of `ClusterResourcePlacementWorkSynchronized` type
+	// is observing the synchronization status of the resource snapshot with index `ObservedResourceIndex`.
+	// If the rollout strategy type is `External`, and `ObservedResourceIndex` is unset due to clusters reporting different resource indices,
+	// conditions except `ClusterResourcePlacementScheduled` will be empty or set to Unknown.
 	// +kubebuilder:validation:Optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 }
@@ -958,13 +961,13 @@ type ResourcePlacementStatus struct {
 	DiffedPlacements []DiffedResourcePlacement `json:"diffedPlacements,omitempty"`
 
 	// 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 snapshot 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.
 	// +kubebuilder:validation:Optional
 	ObservedResourceIndex string `json:"observedResourceIndex,omitempty"`
 
-	// Conditions is an array of current observed conditions for ResourcePlacementStatus.
+	// Conditions is an array of current observed conditions on the cluster.
+	// Each condition corresponds to the resource snapshot at the index specified by `ObservedResourceIndex`.
+	// For example, the condition of type `RolloutStarted` is observing the rollout status of the resource snapshot with index `ObservedResourceIndex`.
 	// +kubebuilder:validation:Optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 }

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

@@ -1976,8 +1976,13 @@ spec:
             description: The observed status of ClusterResourcePlacement.
             properties:
               conditions:
-                description: Conditions is an array of current observed conditions
-                  for ClusterResourcePlacement.
+                description: |-
+                  Conditions is an array of current observed conditions for ClusterResourcePlacement.
+                  All conditions except `ClusterResourcePlacementScheduled` correspond to the resource snapshot at the index specified by `ObservedResourceIndex`.
+                  For example, a condition of `ClusterResourcePlacementWorkSynchronized` type
+                  is observing the synchronization status of the resource snapshot with index `ObservedResourceIndex`.
+                  If the rollout strategy type is `External`, and `ObservedResourceIndex` is unset due to clusters reporting different resource indices,
+                  conditions except `ClusterResourcePlacementScheduled` will be empty or set to Unknown.
                 items:
                   description: Condition contains details for one aspect of the current
                     state of this API Resource.
@@ -2043,12 +2048,10 @@ spec:
                   Each snapshot has a different resource index.
                   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 `
-                  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.
+                  `kubectl get ClusterResourceSnapshot --selector=kubernetes-fleet.io/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.
+                  If the rollout strategy type is `External`, rollout and version control are managed by an external controller,
+                  and this field is not empty only if all targeted clusters observe the same resource index in `PlacementStatuses`.
                 type: string
               placementStatuses:
                 description: |-
@@ -2099,8 +2102,10 @@ spec:
                         If it is not empty, its value should be unique cross all placement decisions for the Placement.
                       type: string
                     conditions:
-                      description: Conditions is an array of current observed conditions
-                        for ResourcePlacementStatus.
+                      description: |-
+                        Conditions is an array of current observed conditions on the cluster.
+                        Each condition corresponds to the resource snapshot at the index specified by `ObservedResourceIndex`.
+                        For example, the condition of type `RolloutStarted` is observing the rollout status of the resource snapshot with index `ObservedResourceIndex`.
                       items:
                         description: Condition contains details for one aspect of
                           the current state of this API Resource.
@@ -2505,8 +2510,6 @@ spec:
                     observedResourceIndex:
                       description: |-
                         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 snapshot 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