address Tim's comments: mainly use file format instead of API

content/en/blog/_posts/2024-09-20-kubeadm-v1beta4.md

@@ -7,20 +7,19 @@ author: >
    Paco Xu (DaoCloud)
 ---
 
-The [`kubeadm`](/docs/reference/setup-tools/kubeadm/) configuration
-([v1beta4](/docs/reference/config-api/kubeadm-config.v1beta4/))
-is released with Kubernetes v1.31. v1beta3 is still supported,
-but is marked as deprecated. It will be removed after a minimum
-of 3 Kubernetes releases.
-
-This guide will walk you through key changes and update about the kubeadm v1beta4 configuration,
+As part of the Kubernetes v1.31 release, [`kubeadm`](/docs/reference/setup-tools/kubeadm/) is
+adopting a new ([v1beta4](/docs/reference/config-api/kubeadm-config.v1beta4/)) version of
+its configuration file format. Configuration in the previous v1beta3 format is now formally
+deprecated, which means it's supported but you should migrate to v1beta4 and stop using
+the deprecated format.
+Support for v1beta3 configuration will be removed after a minimum of 3 Kubernetes minor releases.
+
+In this article, I'll walk you through key changes;
+I'll explain about the kubeadm v1beta4 configuration format,
 and how to migrate from v1beta3 to v1beta4.
 
-Details about v1beta4 can be found in the
-[API doc]((/docs/reference/config-api/kubeadm-config.v1beta4/)).
-The documentation is maintained in the
-[code](https://github.com/kubernetes/kubernetes/blob/master/cmd/kubeadm/app/apis/kubeadm/v1beta4/doc.go)
-and generated for the kubernetes.io website.
+You can read the reference for the v1beta4 configuration format:
+[kubeadm Configuration (v1beta4)]((/docs/reference/config-api/kubeadm-config.v1beta4/)).
 
 ### A list of changes since v1beta3
 
@@ -29,42 +28,45 @@ format by fixing some minor issues and adding a few new fields.
 
 To put it simply,
 
-- Two new API types: ResetConfiguration and UpgradeConfiguration
+- Two new configuration elements: ResetConfiguration and UpgradeConfiguration
 - For InitConfiguration and JoinConfiguration, `dryRun` mode and `nodeRegistration.imagePullSerial` are supported
-- For ClusterConfiguration, we add field including `certificateValidityPeriod`,
+- For ClusterConfiguration, there are new fields including `certificateValidityPeriod`,
 `caCertificateValidityPeriod`, `encryptionAlgorithm`, `dns.disabled` and `proxy.disabled`.
 - Support `extraEnvs` for all control plan components
 - `extraArgs` changed from a map to structured extra arguments for duplicates
 - Add a `timeouts` structure for init, join, upgrade and reset.
 
-For details, you can see the official document below:
+For details, you can see the [official document](/docs/reference/config-api/kubeadm-config.v1beta4/) below:
 
 - 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".
+a `--config` file to `kubeadm reset`.
 - `dryRun` mode 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`.
-- Add `ClusterConfiguration.encryptionAlgorithm` that can be used to set the asymmetric encryption algorithm
-used for this cluster's keys and certificates. Can be one of "RSA-2048" (default), "RSA-3072", "RSA-4096" or "ECDSA-P256".
-- Add `ClusterConfiguration.dns.disabled` and `ClusterConfiguration.proxy.disabled` that can be used to disable
-the CoreDNS and kube-proxy addons during cluster initialization. Skipping the related addons phases,
-during cluster creation will set the same fields to `true`.
-- Add the `nodeRegistration.imagePullSerial` field in `InitConfiguration` and `JoinConfiguration`, which
-can be used to control if kubeadm pulls images serially or in parallel.
-- The UpgradeConfiguration kubeadm API is now supported in v1beta4 when passing `--config` to "kubeadm upgrade" subcommands.
-For upgrade subcommands, the usage of component configuration for kubelet and kube-proxy, as well as InitConfiguration and
-ClusterConfiguration, is deprecated and will be ignored when passing `--config`.
-- Add a `timeouts` structure to `InitConfiguration`, `JoinConfiguration`, `ResetConfiguration` and `UpgradeConfiguration`
-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
-certificates. Only non-CA certificates continue to be renewable by `kubeadm certs renew`.
+- Added `ClusterConfiguration.encryptionAlgorithm` that can be used to set the asymmetric encryption
+ algorithm used for this cluster's keys and certificates. Can be one of "RSA-2048" (default), "RSA-3072",
+  "RSA-4096" or "ECDSA-P256".
+- Added `ClusterConfiguration.dns.disabled` and `ClusterConfiguration.proxy.disabled` that can be used
+  to disable the CoreDNS and kube-proxy addons during cluster initialization.
+  Skipping the related addons phases, during cluster creation will set the same fields to `true`.
+- Added the `nodeRegistration.imagePullSerial` field in `InitConfiguration` and `JoinConfiguration`,
+  which can be used to control if kubeadm pulls images serially or in parallel.
+- The UpgradeConfiguration kubeadm API is now supported in v1beta4 when passing `--config` to
+  `kubeadm upgrade` subcommands.
+  For upgrade subcommands, the usage of component configuration for kubelet and kube-proxy, as well as
+  InitConfiguration and ClusterConfiguration, is now deprecated and will be ignored when passing `--config`.
+- Added a `timeouts` structure to `InitConfiguration`, `JoinConfiguration`, `ResetConfiguration` and
+  `UpgradeConfiguration` 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`.
+- Added 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 certificates.
+  Also note that only non-CA certificates are renewable by `kubeadm certs renew`.
 
 These changes simplify the configuration of tools that use kubeadm
 and improve the extensibility of kubeadm itself.
@@ -74,8 +76,10 @@ and improve the extensibility of kubeadm itself.
 If your configuration is not using the latest version, it is recommended that you migrate using
 the [kubeadm config migrate](/docs/reference/setup-tools/kubeadm/kubeadm-config/#cmd-config-migrate) command.
 
-This command reads an older version of the kubeadm configuration API types from a file,
-and writes a newer version of the configuration objects into a new file.
+This command reads an existing configuration file that uses the old format, and writes a new
+file that uses the current format.
+
+#### Example {#example-kubeadm-config-migrate}
 
 Using kubeadm v1.31, run `kubeadm config migrate --old-config old-v1beta3.yaml --new-config new-v1beta4.yaml`
 
@@ -95,6 +99,6 @@ and review of this feature:
 For those interested in getting involved in future discussions on kubeadm configuration,
 you can reach out kubeadm or [SIG-cluster-lifecycle](https://github.com/kubernetes/community/blob/master/sig-cluster-lifecycle/README.md) by several means:
 
-- v1beta4 related items are tracked in https://github.com/kubernetes/kubeadm/issues/2890.
+- v1beta4 related items are tracked in [kubeadm issue #2890](https://github.com/kubernetes/kubeadm/issues/2890).
 - Slack: [#kubeadm](https://kubernetes.slack.com/messages/kubeadm) or [#sig-cluster-lifecycle](https://kubernetes.slack.com/messages/sig-cluster-lifecycle)
 - [Mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-cluster-lifecycle)