update placement doc

Signed-off-by: Yang Le <[email protected]>

Author: elgnay

cluster/v1alpha1/0000_04_clusters.open-cluster-management.io_placementdecisions.crd.yaml

@@ -15,14 +15,9 @@ spec:
   - name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: "PlacementDecision indicates a decision from a placement PlacementDecision
+        description: PlacementDecision indicates a decision from a placement PlacementDecision
           should has a label cluster.open-cluster-management.io/placement={placement
-          name} to reference a certain placement. \n If a placement has spec.numberOfClusters
-          specified, the total number of decisions contained in status.decisions of
-          PlacementDecisions should always be NumberOfClusters; otherwise, the total
-          number of decisions should be the number of ManagedClusters which match
-          the placement requirements. \n Some of the decisions might be empty when
-          there are no enough ManagedClusters meet the placement requirements."
+          name} to reference a certain placement.
         type: object
         properties:
           apiVersion:
@@ -45,7 +40,8 @@ spec:
             properties:
               decisions:
                 description: Decisions is a slice of decisions according to a placement
-                  The number of decisions should not be larger than 100
+                  The number of decisions should not be larger than 100. The slice
+                  should not include any empty ClusterDecision.
                 type: array
                 items:
                   description: ClusterDecision represents a decision from a placement
@@ -57,8 +53,8 @@ spec:
                   properties:
                     clusterName:
                       description: ClusterName is the name of the ManagedCluster.
-                        If it is not empty, its value should be unique cross all placement
-                        decisions for the Placement.
+                        Its value should be unique cross all placement decisions for
+                        a certian Placement.
                       type: string
                     reason:
                       description: Reason represents the reason why the ManagedCluster

cluster/v1alpha1/types.go

@@ -276,8 +276,9 @@ type PlacementStatus struct {
 
 const (
 	// PlacementConditionSatisfied means Placement requirements are satisfied.
-	// A placement is not satisfied only if there is empty ClusterDecision in the status.decisions
-	// of PlacementDecisions.
+	// A placement is not satisfied only if
+	// 1) NumberOfClusters in spec is specified;
+	// 2) NumberOfSelectedClusters in status is less than NumberOfClusters in spec;
 	PlacementConditionSatisfied string = "PlacementSatisfied"
 )
 
@@ -303,13 +304,6 @@ type PlacementList struct {
 // PlacementDecision indicates a decision from a placement
 // PlacementDecision should has a label cluster.open-cluster-management.io/placement={placement name}
 // to reference a certain placement.
-//
-// If a placement has spec.numberOfClusters specified, the total number of decisions contained in
-// status.decisions of PlacementDecisions should always be NumberOfClusters; otherwise, the total
-// number of decisions should be the number of ManagedClusters which match the placement requirements.
-//
-// Some of the decisions might be empty when there are no enough ManagedClusters meet the placement
-// requirements.
 type PlacementDecision struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -322,7 +316,8 @@ type PlacementDecision struct {
 // PlacementDecisionStatus represents the current status of the PlacementDecision.
 type PlacementDecisionStatus struct {
 	// Decisions is a slice of decisions according to a placement
-	// The number of decisions should not be larger than 100
+	// The number of decisions should not be larger than 100.
+	// The slice should not include any empty ClusterDecision.
 	// +kubebuilder:validation:Required
 	// +required
 	Decisions []ClusterDecision `json:"decisions"`
@@ -331,8 +326,8 @@ type PlacementDecisionStatus struct {
 // ClusterDecision represents a decision from a placement
 // An empty ClusterDecision indicates it is not scheduled yet.
 type ClusterDecision struct {
-	// ClusterName is the name of the ManagedCluster. If it is not empty, its value should be unique cross all
-	// placement decisions for the Placement.
+	// ClusterName is the name of the ManagedCluster. Its value should be unique cross all
+	// placement decisions for a certian Placement.
 	// +kubebuilder:validation:Required
 	// +required
 	ClusterName string `json:"clusterName"`