kubeadm: update godoc and comments for v1beta4

- Include some more examples related to v1beta4 in the doc.go.
- Fix some typos in v1beta4 field comments.
- Add missing JSON tag for UpgradeConfiguration.Apply.SkipPhases.

cmd/kubeadm/app/apis/kubeadm/types.go

@@ -752,6 +752,6 @@ type Timeouts struct {
 	// for a joining node.
 	Discovery *metav1.Duration
 
-	// UpgradeManifests is the timeout for upgradring static Pod manifests
+	// UpgradeManifests is the timeout for upgrading static Pod manifests.
 	UpgradeManifests *metav1.Duration
 }

cmd/kubeadm/app/apis/kubeadm/v1beta3/conversion.go

@@ -125,7 +125,7 @@ func Convert_kubeadm_DNS_To_v1beta3_DNS(in *kubeadm.DNS, out *DNS, s conversion.
 }
 
 // convertToArgs takes a argument map and converts it to a slice of arguments.
-// Te resulting argument slice is sorted alpha-numerically.
+// The resulting argument slice is sorted alpha-numerically.
 func convertToArgs(in map[string]string) []kubeadm.Arg {
 	if in == nil {
 		return nil

cmd/kubeadm/app/apis/kubeadm/v1beta4/doc.go

@@ -24,11 +24,11 @@ limitations under the License.
 //
 // A list of changes since v1beta3:
 //
-//   - TODO https://github.com/kubernetes/kubeadm/issues/2890
 //   - Support custom environment variables in control plane components under `ClusterConfiguration`.
 //     Use `APIServer.ExtraEnvs`, `ControllerManager.ExtraEnvs`, `Scheduler.ExtraEnvs`, `Etcd.Local.ExtraEnvs`.
-//   - The ResetConfiguration API type is now supported in v1beta4. Users are able to reset a node by passing a --config file to "kubeadm reset".
+//   - The ResetConfiguration API type is now supported in v1beta4. Users are able to reset a node by passing
-//   - `dry-run` mode in is now configurable in InitConfiguration and JoinConfiguration config files.
+//     a --config file to "kubeadm reset".
+//   - `dry-run` mode in is now configurable in InitConfiguration and JoinConfiguration.
 //   - Replace the existing string/string extra argument maps with structured extra arguments that support duplicates.
 //     The change applies to `ClusterConfiguration` - `APIServer.ExtraArgs, `ControllerManager.ExtraArgs`,
 //     `Scheduler.ExtraArgs`, `Etcd.Local.ExtraArgs`. Also to `NodeRegistrationOptions.KubeletExtraArgs`.
@@ -43,7 +43,9 @@ limitations under the License.
 //     Usage of component configuration for kubelet and kube-proxy, InitConfiguration and ClusterConfiguration is deprecated
 //     and will be ignored when passing --config to upgrade subcommands.
 //   - Add a `Timeouts` structure to `InitConfiguration`, `JoinConfiguration`, `ResetConfiguration` and `UpgradeConfiguration`
-//     that can be used to configure various timeouts.
+//     that can be used to configure various timeouts. The `ClusterConfiguration.TimeoutForControlPlane` field is replaced
+//     by `Timeouts.ControlPlaneComponentHealthCheck`. The `JoinConfiguration.Discovery.Timeout` is replaced by
+//     `Timeouts.Discovery`.
 //   - Add a `CertificateValidityPeriod` and `CACertificateValidityPeriod` fields to `ClusterConfiguration`. These fields
 //     can be used to control the validity period of certificates generated by kubeadm during sub-commands such as `init`,
 //     `join`, `upgrade` and `certs`. Default values continue to be 1 year for non-CA certificates and 10 years for CA
@@ -54,8 +56,7 @@ limitations under the License.
 //   - kubeadm v1.15.x and newer can be used to migrate from v1beta1 to v1beta2.
 //   - kubeadm v1.22.x and newer no longer support v1beta1 and older APIs, but can be used to migrate v1beta2 to v1beta3.
 //   - kubeadm v1.27.x and newer no longer support v1beta2 and older APIs.
-//   - TODO: https://github.com/kubernetes/kubeadm/issues/2890
+//   - kubeadm v1.31.x and newer can be used to migrate from v1beta3 to v1beta4.
-//     add version that can be used to convert to v1beta4
 //
 // # Basics
 //
@@ -82,10 +83,18 @@ limitations under the License.
 //	apiVersion: kubeadm.k8s.io/v1beta4
 //	kind: JoinConfiguration
 //
+//	apiVersion: kubeadm.k8s.io/v1beta4
+//	kind: ResetConfiguration
+//
+//	apiVersion: kubeadm.k8s.io/v1beta4
+//	kind: UpgradeConfiguration
+//
 // To print the defaults for "init" and "join" actions use the following commands:
 //
 //	kubeadm config print init-defaults
 //	kubeadm config print join-defaults
+//	kubeadm config print reset-defaults
+//	kubeadm config print upgrade-defaults
 //
 // The list of configuration types that must be included in a configuration file depends by the action you are
 // performing (init or join) and by the configuration options you are going to use (defaults or advanced customization).
@@ -193,16 +202,21 @@ limitations under the License.
 //	    value: "someValue"
 //	    effect: "NoSchedule"
 //	  kubeletExtraArgs:
-//	    v: 4
+//	  - name: "v"
+//	    value: "5"
 //	  ignorePreflightErrors:
 //	  - IsPrivilegedUser
 //	  imagePullPolicy: "IfNotPresent"
+//	  imagePullSerial: true
 //	localAPIEndpoint:
 //	  advertiseAddress: "10.100.0.1"
 //	  bindPort: 6443
 //	certificateKey: "e6a2eb8581237ab72a4f494f30285ec12a9694d750b9785706a83bfcbbbd2204"
 //	skipPhases:
-//	- addon/kube-proxy
+//	- preflight
+//	timeouts:
+//	  controlPlaneComponentHealthCheck: "60s"
+//	  kubernetesAPICall: "40s"
 //	---
 //	apiVersion: kubeadm.k8s.io/v1beta4
 //	kind: ClusterConfiguration
@@ -213,9 +227,13 @@ limitations under the License.
 //	    imageTag: "3.2.24"
 //	    dataDir: "/var/lib/etcd"
 //	    extraArgs:
-//	      listen-client-urls: "http://10.100.0.1:2379"
+//	    - name: "listen-client-urls"
+//	      value: "http://10.100.0.1:2379"
+//	    extraEnvs:
+//	    - name: "SOME_VAR"
+//	      value: "SOME_VALUE"
 //	    serverCertSANs:
-//	    -  "ec2-10-100-0-1.compute-1.amazonaws.com"
+//	    - "ec2-10-100-0-1.compute-1.amazonaws.com"
 //	    peerCertSANs:
 //	    - "10.100.0.1"
 //	  # external:
@@ -233,7 +251,11 @@ limitations under the License.
 //	controlPlaneEndpoint: "10.100.0.1:6443"
 //	apiServer:
 //	  extraArgs:
-//	    authorization-mode: "Node,RBAC"
+//	  - name: "authorization-mode"
+//	    value: "Node,RBAC"
+//	  extraEnvs:
+//	  - name: "SOME_VAR"
+//	    value: "SOME_VALUE"
 //	  extraVolumes:
 //	  - name: "some-volume"
 //	    hostPath: "/etc/some-path"
@@ -243,10 +265,10 @@ limitations under the License.
 //	  certSANs:
 //	  - "10.100.1.1"
 //	  - "ec2-10-100-0-1.compute-1.amazonaws.com"
-//	  timeoutForControlPlane: 4m0s
 //	controllerManager:
 //	  extraArgs:
-//	    "node-cidr-mask-size": "20"
+//	  - name: "node-cidr-mask-size"
+//	    value: "20"
 //	  extraVolumes:
 //	  - name: "some-volume"
 //	    hostPath: "/etc/some-path"
@@ -255,7 +277,8 @@ limitations under the License.
 //	    pathType: File
 //	scheduler:
 //	  extraArgs:
-//	    address: "10.100.0.1"
+//	  - name: "address"
+//	    value: "10.100.0.1"
 //	  extraVolumes:
 //	  - name: "some-volume"
 //	    hostPath: "/etc/some-path"
@@ -265,6 +288,11 @@ limitations under the License.
 //	certificatesDir: "/etc/kubernetes/pki"
 //	imageRepository: "registry.k8s.io"
 //	clusterName: "example-cluster"
+//	encryptionAlgorithm: "ECDSA-P256"
+//	dns:
+//	  disabled: true # disable CoreDNS
+//	proxy:
+//	  disabled: true # disable kube-proxy
 //	---
 //	apiVersion: kubelet.config.k8s.io/v1beta1
 //	kind: KubeletConfiguration
@@ -280,7 +308,12 @@ limitations under the License.
 //
 //	apiVersion: kubeadm.k8s.io/v1beta4
 //	kind: JoinConfiguration
-//	   ...
+//	discovery:
+//	  bootstrapToken:
+//	    apiServerEndpoint: some-address:6443
+//	    token: abcdef.0123456789abcdef
+//	    unsafeSkipCAVerification: true
+//	  tlsBootstrapToken: abcdef.0123456789abcdef
 //
 // The JoinConfiguration type should be used to configure runtime settings, that in case of kubeadm join
 // are the discovery method used for accessing the cluster info and all the setting which are specific
@@ -291,7 +324,31 @@ limitations under the License.
 // node only (e.g. the node ip).
 //
 // - APIEndpoint, that represents the endpoint of the instance of the API server to be eventually deployed on this node.
+//
+// # Kubeadm reset configuration types
+//
+// When executing kubeadm reset with the --config option, the ResetConfiguration type should be provided.
+//
+//	apiVersion: kubeadm.k8s.io/v1beta4
+//	kind: ResetConfiguration
+//	   ...
+//
+// # Kubeadm upgrade configuration types
+//
+// When executing kubeadm upgrade with the --config option, the UpgradeConfiguration type should be provided.
+//
+//	apiVersion: kubeadm.k8s.io/v1beta4
+//	kind: UpgradeConfiguration
+//	apply:
+//	  ...
+//	diff:
+//	  ...
+//	node:
+//	  ...
+//	plan:
+//	  ...
+//
+// The UpgradeConfiguration structure includes a few substructures that only apply to different subcommands of "kubeadm upgrade".
+// For example, the "apply" substructure will be used with the "kubeadm upgrade apply" subcommand and all other substructures
+// will be ignored in such a case.
 package v1beta4 // import "k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta4"
-
-//TODO: The BootstrapTokenString object should move out to either k8s.io/client-go or k8s.io/api in the future
-//(probably as part of Bootstrap Tokens going GA). It should not be staged under the kubeadm API as it is now.

cmd/kubeadm/app/apis/kubeadm/v1beta4/types.go

@@ -607,7 +607,7 @@ type Timeouts struct {
 	// +optional
 	Discovery *metav1.Duration `json:"discovery,omitempty"`
 
-	// UpgradeManifests is the timeout for upgradring static Pod manifests
+	// UpgradeManifests is the timeout for upgrading static Pod manifests.
 	// Default: 5m
 	UpgradeManifests *metav1.Duration `json:"upgradeManifests,omitempty"`
 }
@@ -662,7 +662,7 @@ type UpgradeApplyConfiguration struct {
 
 	// SkipPhases is a list of phases to skip during command execution.
 	// NOTE: This field is currently ignored for "kubeadm upgrade apply", but in the future it will be supported.
-	SkipPhases []string
+	SkipPhases []string `json:"skipPhases,omitempty"`
 
 	// ImagePullPolicy specifies the policy for image pulling during kubeadm "upgrade apply" operations.
 	// The value of this field must be one of "Always", "IfNotPresent" or "Never".