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,8 +40,10 @@ 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
+                maxItems: 100
                 items:
                   description: ClusterDecision represents a decision from a placement
                     An empty ClusterDecision indicates it is not scheduled yet.
@@ -57,8 +54,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,15 @@ 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 if
+	// 1) No ManagedClusterSetBinding is found in the placement namespace;
+	// 2) ClusterSets in spec is specified and none of them is bound to the placement namespace;
+	// 3) No memeber ManagedCluster is found for all eligible ManagedClusterSets; A ManagedClusterSet
+	//    is eligible for a placement if
+	//    a) It is bound to the placement namespace;
+	//    b) And if ClusterSets in spec is specified, it is in the list;
+	// 4) No ManagedCluster matches any of the cluster predicates of the placement;
+	// 5) NumberOfClusters in spec is specified and NumberOfSelectedClusters in status is less than it;
 	PlacementConditionSatisfied string = "PlacementSatisfied"
 )
 
@@ -303,13 +310,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,17 +322,19 @@ 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
+	// +kubebuilder:validation:MaxItems=100
 	// +required
 	Decisions []ClusterDecision `json:"decisions"`
 }
 
 // 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"`