add comments for internal Cluster API

Signed-off-by: changzhen <changzhen5@huawei.com>

pkg/apis/cluster/types.go

@@ -16,16 +16,30 @@ type Cluster struct {
 	metav1.TypeMeta
 	metav1.ObjectMeta
 
-	Spec   ClusterSpec
+	// Spec represents the specification of the desired behavior of member cluster.
+	Spec ClusterSpec
+
+	// Status represents the status of member cluster.
+	// +optional
 	Status ClusterStatus
 }
 
 // ClusterSpec defines the desired state of a member cluster.
 type ClusterSpec struct {
+	// SyncMode describes how a cluster sync resources from karmada control plane.
+	// +required
 	SyncMode ClusterSyncMode
 
+	// The API endpoint of the member cluster. This can be a hostname,
+	// hostname:port, IP or IP:port.
+	// +optional
 	APIEndpoint string
 
+	// SecretRef represents the secret contains mandatory credentials to access the member cluster.
+	// The secret should hold credentials as follows:
+	// - secret.data.token
+	// - secret.data.caBundle
+	// +optional
 	SecretRef *LocalSecretReference
 
 	// ImpersonatorSecretRef represents the secret contains the token of impersonator.
@@ -34,12 +48,36 @@ type ClusterSpec struct {
 	// +optional
 	ImpersonatorSecretRef *LocalSecretReference
 
+	// InsecureSkipTLSVerification indicates that the karmada control plane should not confirm the validity of the serving
+	// certificate of the cluster it is connecting to. This will make the HTTPS connection between the karmada control
+	// plane and the member cluster insecure.
+	// Defaults to false.
+	// +optional
 	InsecureSkipTLSVerification bool
-	ProxyURL                    string
-	Provider                    string
-	Region                      string
-	Zone                        string
-	Taints                      []corev1.Taint
+
+	// ProxyURL is the proxy URL for the cluster.
+	// If not empty, the karmada control plane will use this proxy to talk to the cluster.
+	// More details please refer to: https://github.com/kubernetes/client-go/issues/351
+	// +optional
+	ProxyURL string
+
+	// Provider represents the cloud provider name of the member cluster.
+	// +optional
+	Provider string
+
+	// Region represents the region of the member cluster locate in.
+	// +optional
+	Region string
+
+	// Zone represents the zone of the member cluster locate in.
+	// +optional
+	Zone string
+
+	// Taints attached to the member cluster.
+	// Taints on the cluster have the "effect" on
+	// any resource that does not tolerate the Taint.
+	// +optional
+	Taints []corev1.Taint
 }
 
 const (
@@ -66,8 +104,11 @@ const (
 // LocalSecretReference is a reference to a secret within the enclosing
 // namespace.
 type LocalSecretReference struct {
+	// Namespace is the namespace for the resource being referenced.
 	Namespace string
-	Name      string
+
+	// Name is the name of resource being referenced.
+	Name string
 }
 
 // Define valid conditions of a member cluster.
@@ -79,37 +120,76 @@ const (
 // ClusterStatus contains information about the current status of a
 // cluster updated periodically by cluster controller.
 type ClusterStatus struct {
+	// KubernetesVersion represents version of the member cluster.
+	// +optional
 	KubernetesVersion string
-	APIEnablements    []APIEnablement
-	Conditions        []metav1.Condition
-	NodeSummary       *NodeSummary
-	ResourceSummary   *ResourceSummary
+
+	// APIEnablements represents the list of APIs installed in the member cluster.
+	// +optional
+	APIEnablements []APIEnablement
+
+	// Conditions is an array of current cluster conditions.
+	// +optional
+	Conditions []metav1.Condition
+
+	// NodeSummary represents the summary of nodes status in the member cluster.
+	// +optional
+	NodeSummary *NodeSummary
+
+	// ResourceSummary represents the summary of resources in the member cluster.
+	// +optional
+	ResourceSummary *ResourceSummary
 }
 
 // APIEnablement is a list of API resource, it is used to expose the name of the
 // resources supported in a specific group and version.
 type APIEnablement struct {
+	// GroupVersion is the group and version this APIEnablement is for.
 	GroupVersion string
-	Resources    []APIResource
+
+	// Resources is a list of APIResource.
+	// +optional
+	Resources []APIResource
 }
 
 // APIResource specifies the name and kind names for the resource.
 type APIResource struct {
+	// Name is the plural name of the resource.
+	// +required
 	Name string
+
+	// Kind is the kind for the resource (e.g. 'Deployment' is the kind for resource 'deployments')
+	// +required
 	Kind string
 }
 
 // NodeSummary represents the summary of nodes status in a specific cluster.
 type NodeSummary struct {
+	// TotalNum is the total number of nodes in the cluster.
+	// +optional
 	TotalNum int32
+
+	// ReadyNum is the number of ready nodes in the cluster.
+	// +optional
 	ReadyNum int32
 }
 
 // ResourceSummary represents the summary of resources in the member cluster.
 type ResourceSummary struct {
+	// Allocatable represents the resources of a cluster that are available for scheduling.
+	// Total amount of allocatable resources on all nodes.
+	// +optional
 	Allocatable corev1.ResourceList
-	Allocating  corev1.ResourceList
-	Allocated   corev1.ResourceList
+
+	// Allocating represents the resources of a cluster that are pending for scheduling.
+	// Total amount of required resources of all Pods that are waiting for scheduling.
+	// +optional
+	Allocating corev1.ResourceList
+
+	// Allocated represents the resources of a cluster that have been scheduled.
+	// Total amount of required resources of all Pods that have been scheduled to nodes.
+	// +optional
+	Allocated corev1.ResourceList
 }
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
@@ -119,6 +199,7 @@ type ClusterList struct {
 	metav1.TypeMeta
 	metav1.ListMeta
 
+	// Items holds a list of Cluster.
 	Items []Cluster
 }