feat: Update MC & IMC API comments (Azure#262)

* Update MC & IMC API comments * address comments * address comments Co-authored-by: Ryan Zhang <[email protected]>
michaelawyu · Sep 6, 2022 · 45ad25a · 45ad25a
1 parent 5c86e71
commit 45ad25a
Show file tree

Hide file tree

Showing 19 changed files with 209 additions and 180 deletions.
diff --git a/apis/v1alpha1/commons.go b/apis/v1alpha1/commons.go
@@ -5,7 +5,10 @@ Licensed under the MIT license.
 
 package v1alpha1
 
-import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+import (
+	v1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
 
 type ClusterState string
 
@@ -18,15 +21,29 @@ const (
 	MemberClusterKind                = "MemberCluster"
 	MemberClusterResource            = "memberclusters"
 	InternalMemberClusterKind        = "InternalMemberCluster"
-	ClusterResourcePlacementKind     = "ClusterResourcePlacement"
 	ClusterResourcePlacementResource = "clusterresourceplacements"
 )
 
-// AgentType defines agent/binary running in the member cluster.
+// ResourceUsage contains the observed resource usage of a member cluster.
+type ResourceUsage struct {
+	// Capacity represents the total resource capacity of all the nodes on a member cluster.
+	// +optional
+	Capacity v1.ResourceList `json:"capacity,omitempty"`
+
+	// Allocatable represents the total resources of all the nodes on a member cluster that are available for scheduling.
+	// +optional
+	Allocatable v1.ResourceList `json:"allocatable,omitempty"`
+
+	// When the resource usage is observed.
+	// +optional
+	ObservationTime metav1.Time `json:"observationTime,omitempty"`
+}
+
+// AgentType defines a type of agent/binary running in a member cluster.
 type AgentType string
 
 const (
-	// MemberAgent (core) handles the join/unjoin and work orchestration of the multi-clusters.
+	// MemberAgent (core) handles member cluster joining/leaving as well as k8s object placement from hub to member clusters.
 	MemberAgent AgentType = "MemberAgent"
 	// MultiClusterServiceAgent (networking) is responsible for exposing multi-cluster services via L4 load
 	// balancer.
@@ -35,17 +52,17 @@ const (
 	ServiceExportImportAgent AgentType = "ServiceExportImportAgent"
 )
 
-// AgentStatus contains status information received for the particular agent type.
+// AgentStatus defines the observed status of the member agent of the given type.
 type AgentStatus struct {
-	// Type of agent type.
+	// Type of the member agent.
 	// +required
 	Type AgentType `json:"type"`
 
-	// Conditions field contains the different condition statuses for this member cluster, eg join and health status.
+	// Conditions is an array of current observed conditions for the member agent.
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 
-	// Last time we got the heartbeat.
+	// Last time we received a heartbeat from the member agent.
 	// +optional
 	LastReceivedHeartbeat metav1.Time `json:"lastReceivedHeartbeat,omitempty"`
 }
@@ -54,10 +71,14 @@ type AgentStatus struct {
 type AgentConditionType string
 
 const (
-	// AgentJoined is used to track the join state of the agent.
-	// Its conditionStatus can be "True" == Joined, "Unknown" == Joining/Leaving, "False" == Left.
+	// AgentJoined indicates the join condition of the given member agent. Its condition status can be one of the following:
+	// "True" means the member agent has joined.
+	// "False" means the member agent has left.
+	// "Unknown" means the member agent is joining or leaving or in an unknown status.
 	AgentJoined AgentConditionType = "Joined"
-	// AgentHealthy is used to track the Health state of the agent.
-	// Its conditionStatus can be "True" == Healthy, "False" == UnHealthy. "Unknown" is unused.
+	// AgentHealthy indicates the health condition of the given member agent. Its condition status can be one of the following:
+	// "True" means the member agent is healthy.
+	// "False" means the member agent is unhealthy.
+	// "Unknown" means the member agent has an unknown health status.
 	AgentHealthy AgentConditionType = "Healthy"
 )
diff --git a/apis/v1alpha1/internalmembercluster_types.go b/apis/v1alpha1/internalmembercluster_types.go
@@ -6,18 +6,16 @@ Licensed under the MIT license.
 package v1alpha1
 
 import (
-	v1 "k8s.io/api/core/v1"
 	"k8s.io/apimachinery/pkg/api/meta"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// InternalMemberCluster is used by the hub agent to control the member cluster state.
-// Member agent watches this CR and updates its status.
-
 // +kubebuilder:object:root=true
-// +kubebuilder:resource:scope=Namespaced,categories={fleet},shortName=internalcluster
+// +kubebuilder:resource:scope=Namespaced,categories={fleet},shortName=imc
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:JSONPath=`.metadata.creationTimestamp`,name="Age",type=date
+
+// InternalMemberCluster is used by hub agent to notify the member agents about the member cluster state changes, and is used by the member agents to report their status.
 type InternalMemberCluster struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -26,46 +24,34 @@ type InternalMemberCluster struct {
 	Status InternalMemberClusterStatus `json:"status,omitempty"`
 }
 
-// InternalMemberClusterSpec defines the desired state of InternalMemberCluster for the hub agent.
+// InternalMemberClusterSpec defines the desired state of InternalMemberCluster. Set by the hub agent.
 type InternalMemberClusterSpec struct {
-	// State indicates the state of the member cluster.
-
 	// +kubebuilder:validation:Required,Enum=Join;Leave
+
+	// The desired state of the member cluster. Possible values: Join, Leave.
+	// +required
 	State ClusterState `json:"state"`
 
-	// HeartbeatPeriodSeconds indicates how often (in seconds) for the member cluster to send a heartbeat. Default to 60 seconds. Minimum value is 1.
+	// +kubebuilder:default=60
+	// +kubebuilder:validation:Minimum:1
+	// +kubebuilder:validation:Maximum:600
 
+	// How often (in seconds) for the member cluster to send a heartbeat to the hub cluster. Default: 60 seconds. Min: 1 second. Max: 10 minutes.
 	// +optional
-	// +kubebuilder:default=60
-	HeartbeatPeriodSeconds int32 `json:"leaseDurationSeconds,omitempty"`
+	HeartbeatPeriodSeconds int32 `json:"heartbeatPeriodSeconds,omitempty"`
 }
 
 // InternalMemberClusterStatus defines the observed state of InternalMemberCluster.
 type InternalMemberClusterStatus struct {
-	// Resource usage collected from member cluster.
+	// The current observed resource usage of the member cluster. It is populated by the member agent.
 	// +optional
 	ResourceUsage ResourceUsage `json:"resourceUsage,omitempty"`
 
-	// AgentStatus field contains the status for each agent running in the member cluster.
+	// AgentStatus is an array of current observed status, each corresponding to one member agent running in the member cluster.
 	// +optional
 	AgentStatus []AgentStatus `json:"agentStatus,omitempty"`
 }
 
-// ResourceUsage represents the resource usage collected from the member cluster and its observation time.
-type ResourceUsage struct {
-	// Capacity represents the total resource capacity from all nodeStatues on the member cluster.
-	// +optional
-	Capacity v1.ResourceList `json:"capacity,omitempty"`
-
-	// Allocatable represents the total allocatable resources on the member cluster.
-	// +optional
-	Allocatable v1.ResourceList `json:"allocatable,omitempty"`
-
-	// The time we observe the member cluster resource usage, including capacity and allocatable.
-	// +optional
-	ObservationTime metav1.Time `json:"observationTime,omitempty"`
-}
-
 //+kubebuilder:object:root=true
 
 // InternalMemberClusterList contains a list of InternalMemberCluster.

diff --git a/apis/v1alpha1/membercluster_types.go b/apis/v1alpha1/membercluster_types.go
@@ -11,14 +11,13 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// MemberCluster is a resource created in the hub cluster to represent a member cluster within a fleet.
-
 // +kubebuilder:object:root=true
-// +kubebuilder:resource:scope=Cluster,categories={fleet},shortName=membercluster
+// +kubebuilder:resource:scope=Cluster,categories={fleet},shortName=mc
 // +kubebuilder:subresource:status
-// +kubebuilder:printcolumn:JSONPath=`.status.conditions[?(@.type=="ConditionTypeMemberClusterJoin")].status`,name="Joined",type=string
+// +kubebuilder:printcolumn:JSONPath=`.status.conditions[?(@.type=="Joined")].status`,name="Joined",type=string
 // +kubebuilder:printcolumn:JSONPath=`.metadata.creationTimestamp`,name="Age",type=date
-// +kubebuilder:printcolumn:JSONPath=`.metadata.label[fleet.azure.com/clusterHealth]`,name="HealthStatus",type=string
+
+// MemberCluster is a resource created in the hub cluster to represent a member cluster within a fleet.
 type MemberCluster struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -29,52 +28,63 @@ type MemberCluster struct {
 
 // MemberClusterSpec defines the desired state of MemberCluster.
 type MemberClusterSpec struct {
-	// State indicates the desired state of the member cluster.
-
 	// +kubebuilder:validation:Required,Enum=Join;Leave
-	State ClusterState `json:"state"`
 
-	// Identity used by the member cluster to contact the hub cluster.
-	// The hub cluster will create the minimal required permission for this identity.
+	// The desired state of the member cluster. Possible values: Join, Leave.
+	// +required
+	State ClusterState `json:"state"`
 
+	// The identity used by the member cluster to access the hub cluster.
+	// The hub agents deployed on the hub cluster will automatically grant the minimal required permissions to this identity for the member agents deployed on the member cluster to access the hub cluster.
 	// +required
 	Identity rbacv1.Subject `json:"identity"`
 
-	// HeartbeatPeriodSeconds indicates how often (in seconds) for the member cluster to send a heartbeat. Default to 60 seconds. Minimum value is 1.
-
 	// +kubebuilder:default=60
+	// +kubebuilder:validation:Minimum:1
+	// +kubebuilder:validation:Maximum:600
+
+	// How often (in seconds) for the member cluster to send a heartbeat to the hub cluster. Default: 60 seconds. Min: 1 second. Max: 10 minutes.
 	// +optional
-	HeartbeatPeriodSeconds int32 `json:"leaseDurationSeconds,omitempty"`
+	HeartbeatPeriodSeconds int32 `json:"heartbeatPeriodSeconds,omitempty"`
 }
 
-// MemberClusterStatus defines the observed state of MemberCluster.
+// MemberClusterStatus defines the observed status of MemberCluster.
 type MemberClusterStatus struct {
-	// Conditions is an array of current observed conditions for this member cluster.
-	// +required
+	// Conditions is an array of current observed conditions for the member cluster.
+	// +optional
 	Conditions []metav1.Condition `json:"conditions"`
 
-	// Resource usage collected from member cluster.
+	// The current observed resource usage of the member cluster. It is copied from the corresponding InternalMemberCluster object.
 	// +optional
 	ResourceUsage ResourceUsage `json:"resourceUsage,omitempty"`
 
-	// AgentStatus field contains the status for each agent running in the member cluster.
+	// AgentStatus is an array of current observed status, each corresponding to one member agent running in the member cluster.
 	// +optional
 	AgentStatus []AgentStatus `json:"agentStatus,omitempty"`
 }
 
+// MemberClusterConditionType defines a specific condition of a member cluster.
+type MemberClusterConditionType string
+
 const (
-	// ConditionTypeMemberClusterReadyToJoin is used to track the readiness of the hub cluster
-	// controller to accept the new member cluster.
-	// its conditionStatus can only be "True" == ReadyToJoin
-	ConditionTypeMemberClusterReadyToJoin string = "ReadyToJoin"
-
-	// ConditionTypeMemberClusterJoin is used to track the join state of the memberCluster.
-	// its conditionStatus can be "True" == Joined, "Unknown" == Joining/Leaving, "False" == Left
-	ConditionTypeMemberClusterJoin string = "Joined"
-
-	// ConditionTypeMemberClusterHealth is used to track the Health state of the MemberCluster.
-	// its conditionStatus can be "True" == Healthy, "Unknown" == Health degraded, "False" == UnHealthy
-	ConditionTypeMemberClusterHealth string = "Healthy"
+	// ConditionTypeMemberClusterReadyToJoin indicates the readiness condition of the given member cluster for joining the hub cluster. Its condition status can be one of the following:
+	// "True" means the hub cluster is ready for the member cluster to join.
+	// "False" means the hub cluster is not ready for the member cluster to join.
+	// "Unknown" means it is unknown whether the hub cluster is ready for the member cluster to join.
+	ConditionTypeMemberClusterReadyToJoin MemberClusterConditionType = "ReadyToJoin"
+
+	// ConditionTypeMemberClusterJoined indicates the join condition of the given member cluster. Its condition status can be one of the following:
+	// "True" means all the agents on the member cluster have joined.
+	// "False" means all the agents on the member cluster have left.
+	// "Unknown" means not all the agents have joined or left.
+	ConditionTypeMemberClusterJoined MemberClusterConditionType = "Joined"
+
+	// ConditionTypeMemberClusterHealthy indicates the health condition of the given member cluster. Its condition status can be one of the following:
+	// "True" means the member cluster is healthy.
+	// "False" means the member cluster is unhealthy.
+	// "Unknown" means the member cluster has an unknown health status.
+	// NOTE: This condition type is currently unused.
+	ConditionTypeMemberClusterHealthy MemberClusterConditionType = "Healthy"
 )
 
 //+kubebuilder:object:root=true

diff --git a/config/crd/bases/fleet.azure.com_clusterresourceplacements.yaml b/config/crd/bases/fleet.azure.com_clusterresourceplacements.yaml
@@ -48,8 +48,8 @@ spec:
             properties:
               policy:
                 description: Policy represents the placement policy to select clusters
-                  to place all the selected resources. Default is place to the entire
-                  fleet if this field is omitted.
+                  to place all the selected resources. If unspecified, all the joined
+                  clusters are selected.
                 properties:
                   affinity:
                     description: Affinity represents the selected resources' scheduling
@@ -125,9 +125,9 @@ spec:
                         type: object
                     type: object
                   clusterNames:
-                    description: ClusterNames is a request to schedule the selected
-                      resource to a list of member clusters. If exists, we only place
-                      the resources within the clusters in this list. kubebuilder:validation:MaxItems=100
+                    description: ClusterNames contains a list of names of MemberCluster
+                      to place the selected resources to. If the list is not empty,
+                      Affinity is ignored. kubebuilder:validation:MaxItems=100
                     items:
                       type: string
                     type: array
@@ -384,8 +384,8 @@ spec:
                   type: object
                 type: array
               selectedResources:
-                description: SelectedResources is a list of the resources the resource
-                  selector selects.
+                description: SelectedResources contains a list of resources selected
+                  by the resource selector.
                 items:
                   description: ResourceIdentifier points to one resource we selected
                   properties:
@@ -411,8 +411,9 @@ spec:
                   type: object
                 type: array
               targetClusters:
-                description: TargetClusters is a list of cluster names that this resource
-                  should run on.
+                description: TargetClusters contains a list of member cluster names
+                  selected by PlacementPolicy. Note that the clusters must be both
+                  joined and meeting PlacementPolicy.
                 items:
                   type: string
                 type: array