Add missing comments with serialized names

Apply suggestions from code review

Co-authored-by: Joel Speed <[email protected]>

api/v1beta1/cluster_types.go

@@ -484,7 +484,7 @@ type ClusterSpec struct {
 	// +optional
 	InfrastructureRef *corev1.ObjectReference `json:"infrastructureRef,omitempty"`
 
-	// This encapsulates the topology for the cluster.
+	// topology encapsulates the topology for the cluster.
 	// NOTE: It is required to enable the ClusterTopology
 	// feature gate flag to activate managed topologies support;
 	// this feature is highly experimental, and parts of it might still be not implemented.
@@ -844,6 +844,7 @@ type ClusterNetwork struct {
 
 // NetworkRanges represents ranges of network addresses.
 type NetworkRanges struct {
+	// cidrBlocks is a list of CIDR blocks.
 	CIDRBlocks []string `json:"cidrBlocks"`
 }
 

api/v1beta1/clusterclass_types.go

@@ -296,13 +296,15 @@ type MachineHealthCheckClass struct {
 	// +optional
 	UnhealthyConditions []UnhealthyCondition `json:"unhealthyConditions,omitempty"`
 
-	// Any further remediation is only allowed if at most "MaxUnhealthy" machines selected by
+	// maxUnhealthy specifies the maximum number of unhealthy machines allowed.
+	// Any further remediation is only allowed if at most "maxUnhealthy" machines selected by
 	// "selector" are not healthy.
 	// +optional
 	MaxUnhealthy *intstr.IntOrString `json:"maxUnhealthy,omitempty"`
 
+	// unhealthyRange specifies the range of unhealthy machines allowed.
 	// Any further remediation is only allowed if the number of machines selected by "selector" as not healthy
-	// is within the range of "UnhealthyRange". Takes precedence over MaxUnhealthy.
+	// is within the range of "unhealthyRange". Takes precedence over maxUnhealthy.
 	// Eg. "[3-5]" - This means that remediation will be allowed only when:
 	// (a) there are at least 3 unhealthy machines (and)
 	// (b) there are at most 5 unhealthy machines

api/v1beta1/machinehealthcheck_types.go

@@ -65,16 +65,18 @@ type MachineHealthCheckSpec struct {
 	// +optional
 	UnhealthyConditions []UnhealthyCondition `json:"unhealthyConditions,omitempty"`
 
-	// Any further remediation is only allowed if at most "MaxUnhealthy" machines selected by
+	// maxUnhealthy specifies the maximum number of unhealthy machines allowed.
+	// Any further remediation is only allowed if at most "maxUnhealthy" machines selected by
 	// "selector" are not healthy.
 	//
 	// Deprecated: This field is deprecated and is going to be removed in the next apiVersion. Please see https://github.com/kubernetes-sigs/cluster-api/issues/10722 for more details.
 	//
 	// +optional
 	MaxUnhealthy *intstr.IntOrString `json:"maxUnhealthy,omitempty"`
 
+	// unhealthyRange specifies the range of unhealthy machines allowed.
 	// Any further remediation is only allowed if the number of machines selected by "selector" as not healthy
-	// is within the range of "UnhealthyRange". Takes precedence over MaxUnhealthy.
+	// is within the range of "unhealthyRange". Takes precedence over maxUnhealthy.
 	// Eg. "[3-5]" - This means that remediation will be allowed only when:
 	// (a) there are at least 3 unhealthy machines (and)
 	// (b) there are at most 5 unhealthy machines
@@ -118,14 +120,20 @@ type MachineHealthCheckSpec struct {
 // specified as a duration.  When the named condition has been in the given
 // status for at least the timeout value, a node is considered unhealthy.
 type UnhealthyCondition struct {
+	// type of Node condition
 	// +kubebuilder:validation:Type=string
 	// +kubebuilder:validation:MinLength=1
 	Type corev1.NodeConditionType `json:"type"`
 
+	// status of the condition, one of True, False, Unknown.
 	// +kubebuilder:validation:Type=string
 	// +kubebuilder:validation:MinLength=1
 	Status corev1.ConditionStatus `json:"status"`
 
+	// timeout is the duration that a node must be in a given status for, 
+	// after which the node is considered unhealthy.
+	// For example, with a value of "1h", the node must match the status
+	// for at least 1 hour before being considered unhealthy.
 	Timeout metav1.Duration `json:"timeout"`
 }
 

api/v1beta1/machineset_types.go

@@ -309,6 +309,10 @@ type MachineSetStatus struct {
 	// +optional
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
 
+	// failureReason will be set in the event that there is a terminal problem
+	// reconciling the Machine and will contain a succinct value suitable
+	// for machine interpretation.
+	//
 	// In the event that there is a terminal problem reconciling the
 	// replicas, both FailureReason and FailureMessage will be set. FailureReason
 	// will be populated with a succinct value suitable for machine
@@ -332,10 +336,16 @@ type MachineSetStatus struct {
 	//
 	// +optional
 	FailureReason *capierrors.MachineSetStatusError `json:"failureReason,omitempty"`
+
+	// failureMessage will be set in the event that there is a terminal problem
+	// reconciling the Machine and will contain a more verbose string suitable
+	// for logging and human consumption.
+	//
 	// Deprecated: This field is deprecated and is going to be removed in the next apiVersion. Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.
 	//
 	// +optional
 	FailureMessage *string `json:"failureMessage,omitempty"`
+
 	// conditions defines current service state of the MachineSet.
 	// +optional
 	Conditions Conditions `json:"conditions,omitempty"`

bootstrap/kubeadm/api/v1beta1/kubeadm_types.go

@@ -662,7 +662,9 @@ type KubeConfigAuthExec struct {
 // KubeConfigAuthExecEnv is used for setting environment variables when executing an exec-based
 // credential plugin.
 type KubeConfigAuthExecEnv struct {
-	Name  string `json:"name"`
+	// name of the environment variable
+	Name string `json:"name"`
+	// value of the environment variable
 	Value string `json:"value"`
 }
 

bootstrap/kubeadm/api/v1beta1/kubeadmconfigtemplate_types.go

@@ -24,6 +24,7 @@ import (
 
 // KubeadmConfigTemplateSpec defines the desired state of KubeadmConfigTemplate.
 type KubeadmConfigTemplateSpec struct {
+	// template defines the desired state of KubeadmConfigTemplate.
 	Template KubeadmConfigTemplateResource `json:"template"`
 }
 

controlplane/kubeadm/api/v1beta1/kubeadmcontrolplanetemplate_types.go

@@ -25,6 +25,7 @@ import (
 
 // KubeadmControlPlaneTemplateSpec defines the desired state of KubeadmControlPlaneTemplate.
 type KubeadmControlPlaneTemplateSpec struct {
+	// template defines the desired state of KubeadmControlPlaneTemplate.
 	Template KubeadmControlPlaneTemplateResource `json:"template"`
 }
 

internal/apis/bootstrap/kubeadm/v1alpha3/kubeadmconfigtemplate_types.go

@@ -22,6 +22,7 @@ import (
 
 // KubeadmConfigTemplateSpec defines the desired state of KubeadmConfigTemplate.
 type KubeadmConfigTemplateSpec struct {
+	// template defines the desired state of KubeadmConfigTemplate.
 	Template KubeadmConfigTemplateResource `json:"template"`
 }
 

internal/apis/bootstrap/kubeadm/v1alpha4/kubeadmconfigtemplate_types.go

@@ -22,6 +22,7 @@ import (
 
 // KubeadmConfigTemplateSpec defines the desired state of KubeadmConfigTemplate.
 type KubeadmConfigTemplateSpec struct {
+	// template defines the desired state of KubeadmConfigTemplate.
 	Template KubeadmConfigTemplateResource `json:"template"`
 }
 

internal/apis/controlplane/kubeadm/v1alpha4/kubeadmcontrolplanetemplate_types.go

@@ -22,6 +22,7 @@ import (
 
 // KubeadmControlPlaneTemplateSpec defines the desired state of KubeadmControlPlaneTemplate.
 type KubeadmControlPlaneTemplateSpec struct {
+	// template defines the desired state of KubeadmControlPlaneTemplate.
 	Template KubeadmControlPlaneTemplateResource `json:"template"`
 }
 

internal/apis/core/v1alpha3/cluster_types.go

@@ -92,6 +92,7 @@ type ClusterNetwork struct {
 
 // NetworkRanges represents ranges of network addresses.
 type NetworkRanges struct {
+	// cidrBlocks is a list of CIDR blocks.
 	CIDRBlocks []string `json:"cidrBlocks"`
 }
 

internal/apis/core/v1alpha3/machinehealthcheck_types.go

@@ -40,13 +40,14 @@ type MachineHealthCheckSpec struct {
 	// +kubebuilder:validation:MinItems=1
 	UnhealthyConditions []UnhealthyCondition `json:"unhealthyConditions"`
 
-	// Any further remediation is only allowed if at most "MaxUnhealthy" machines selected by
+	// maxUnhealthy specifies the maximum number of unhealthy machines allowed.
+	// Any further remediation is only allowed if at most "maxUnhealthy" machines selected by
 	// "selector" are not healthy.
 	// +optional
 	MaxUnhealthy *intstr.IntOrString `json:"maxUnhealthy,omitempty"`
 
-	// Machines older than this duration without a node will be considered to have
-	// failed and will be remediated.
+	// nodeStartupTimeout is the duration after which machines without a node will be considered to
+	// have failed and will be remediated.
 	// +optional
 	NodeStartupTimeout *metav1.Duration `json:"nodeStartupTimeout,omitempty"`
 
@@ -68,14 +69,20 @@ type MachineHealthCheckSpec struct {
 // specified as a duration.  When the named condition has been in the given
 // status for at least the timeout value, a node is considered unhealthy.
 type UnhealthyCondition struct {
+	// type of Node condition
 	// +kubebuilder:validation:Type=string
 	// +kubebuilder:validation:MinLength=1
 	Type corev1.NodeConditionType `json:"type"`
 
+	// status of the condition, one of True, False, Unknown.
 	// +kubebuilder:validation:Type=string
 	// +kubebuilder:validation:MinLength=1
 	Status corev1.ConditionStatus `json:"status"`
 
+	// timeout is the duration that a node must be in a given status for,
+	// after which the node is considered unhealthy.
+	// For example, with a value of "1h", the node must match the status
+	// for at least 1 hour before being considered unhealthy.
 	Timeout metav1.Duration `json:"timeout"`
 }
 

internal/apis/core/v1alpha3/machineset_types.go

@@ -135,6 +135,10 @@ type MachineSetStatus struct {
 	// +optional
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
 
+	// failureReason will be set in the event that there is a terminal problem
+	// reconciling the Machine and will contain a succinct value suitable
+	// for machine interpretation.
+	//
 	// In the event that there is a terminal problem reconciling the
 	// replicas, both FailureReason and FailureMessage will be set. FailureReason
 	// will be populated with a succinct value suitable for machine
@@ -155,6 +159,10 @@ type MachineSetStatus struct {
 	// controller's output.
 	// +optional
 	FailureReason *capierrors.MachineSetStatusError `json:"failureReason,omitempty"`
+
+	// failureMessage will be set in the event that there is a terminal problem
+	// reconciling the Machine and will contain a more verbose string suitable
+	// for logging and human consumption.
 	// +optional
 	FailureMessage *string `json:"failureMessage,omitempty"`
 }

internal/apis/core/v1alpha4/cluster_types.go

@@ -61,7 +61,7 @@ type ClusterSpec struct {
 	// +optional
 	InfrastructureRef *corev1.ObjectReference `json:"infrastructureRef,omitempty"`
 
-	// This encapsulates the topology for the cluster.
+	// topology encapsulates the topology for the cluster.
 	// NOTE: It is required to enable the ClusterTopology
 	// feature gate flag to activate managed topologies support;
 	// this feature is highly experimental, and parts of it might still be not implemented.
@@ -172,6 +172,7 @@ type ClusterNetwork struct {
 
 // NetworkRanges represents ranges of network addresses.
 type NetworkRanges struct {
+	// cidrBlocks is a list of CIDR blocks.
 	CIDRBlocks []string `json:"cidrBlocks"`
 }
 

internal/apis/core/v1alpha4/machinehealthcheck_types.go

@@ -40,22 +40,24 @@ type MachineHealthCheckSpec struct {
 	// +kubebuilder:validation:MinItems=1
 	UnhealthyConditions []UnhealthyCondition `json:"unhealthyConditions"`
 
-	// Any further remediation is only allowed if at most "MaxUnhealthy" machines selected by
+	// maxUnhealthy specifies the maximum number of unhealthy machines allowed.
+	// Any further remediation is only allowed if at most "maxUnhealthy" machines selected by
 	// "selector" are not healthy.
 	// +optional
 	MaxUnhealthy *intstr.IntOrString `json:"maxUnhealthy,omitempty"`
 
+	// unhealthyRange specifies the range of unhealthy machines allowed.
 	// Any further remediation is only allowed if the number of machines selected by "selector" as not healthy
-	// is within the range of "UnhealthyRange". Takes precedence over MaxUnhealthy.
+	// is within the range of "unhealthyRange". Takes precedence over maxUnhealthy.
 	// Eg. "[3-5]" - This means that remediation will be allowed only when:
 	// (a) there are at least 3 unhealthy machines (and)
 	// (b) there are at most 5 unhealthy machines
 	// +optional
 	// +kubebuilder:validation:Pattern=^\[[0-9]+-[0-9]+\]$
 	UnhealthyRange *string `json:"unhealthyRange,omitempty"`
 
-	// Machines older than this duration without a node will be considered to have
-	// failed and will be remediated.
+	// nodeStartupTimeout is the duration after which machines without a node will be considered to
+	// have failed and will be remediated.
 	// If not set, this value is defaulted to 10 minutes.
 	// If you wish to disable this feature, set the value explicitly to 0.
 	// +optional
@@ -79,14 +81,20 @@ type MachineHealthCheckSpec struct {
 // specified as a duration.  When the named condition has been in the given
 // status for at least the timeout value, a node is considered unhealthy.
 type UnhealthyCondition struct {
+	// type of Node condition
 	// +kubebuilder:validation:Type=string
 	// +kubebuilder:validation:MinLength=1
 	Type corev1.NodeConditionType `json:"type"`
 
+	// status of the condition, one of True, False, Unknown.
 	// +kubebuilder:validation:Type=string
 	// +kubebuilder:validation:MinLength=1
 	Status corev1.ConditionStatus `json:"status"`
 
+	// timeout is the duration that a node must be in a given status for,
+	// after which the node is considered unhealthy.
+	// For example, with a value of "1h", the node must match the status
+	// for at least 1 hour before being considered unhealthy.
 	Timeout metav1.Duration `json:"timeout"`
 }
 

internal/apis/core/v1alpha4/machineset_types.go

@@ -142,6 +142,10 @@ type MachineSetStatus struct {
 	// +optional
 	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
 
+	// failureReason will be set in the event that there is a terminal problem
+	// reconciling the Machine and will contain a succinct value suitable
+	// for machine interpretation.
+	//
 	// In the event that there is a terminal problem reconciling the
 	// replicas, both FailureReason and FailureMessage will be set. FailureReason
 	// will be populated with a succinct value suitable for machine
@@ -162,8 +166,13 @@ type MachineSetStatus struct {
 	// controller's output.
 	// +optional
 	FailureReason *capierrors.MachineSetStatusError `json:"failureReason,omitempty"`
+
+	// failureMessage will be set in the event that there is a terminal problem
+	// reconciling the Machine and will contain a more verbose string suitable
+	// for logging and human consumption.
 	// +optional
 	FailureMessage *string `json:"failureMessage,omitempty"`
+
 	// conditions defines current service state of the MachineSet.
 	// +optional
 	Conditions Conditions `json:"conditions,omitempty"`