Kubernetes v1.31: kubeadm v1beta4
As part of the Kubernetes v1.31 release, kubeadm
is
adopting a new (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.
You can read the reference for the v1beta4 configuration format: kubeadm Configuration (v1beta4).
A list of changes since v1beta3
This version improves on the v1beta3 format by fixing some minor issues and adding a few new fields.
To put it simply,
- Two new configuration elements: ResetConfiguration and UpgradeConfiguration
- For InitConfiguration and JoinConfiguration,
dryRun
mode andnodeRegistration.imagePullSerial
are supported - For ClusterConfiguration, there are new fields including
certificateValidityPeriod
,caCertificateValidityPeriod
,encryptionAlgorithm
,dns.disabled
andproxy.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:
- Support custom environment variables in control plane components under
ClusterConfiguration
. UseapiServer.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 tokubeadm 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 tonodeRegistrationOptions.kubeletExtraArgs
. - 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
andClusterConfiguration.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 totrue
. - Added the
nodeRegistration.imagePullSerial
field inInitConfiguration
andJoinConfiguration
, 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
tokubeadm 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 toInitConfiguration
,JoinConfiguration
,ResetConfiguration
andUpgradeConfiguration
that can be used to configure various timeouts. TheClusterConfiguration.timeoutForControlPlane
field is replaced bytimeouts.controlPlaneComponentHealthCheck
. TheJoinConfiguration.discovery.timeout
is replaced bytimeouts.discovery
. - Added a
certificateValidityPeriod
andcaCertificateValidityPeriod
fields toClusterConfiguration
. These fields can be used to control the validity period of certificates generated by kubeadm during sub-commands such asinit
,join
,upgrade
andcerts
. 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 bykubeadm certs renew
.
These changes simplify the configuration of tools that use kubeadm and improve the extensibility of kubeadm itself.
How to migrate v1beta3 configuration to v1beta4?
If your configuration is not using the latest version, it is recommended that you migrate using the kubeadm config migrate command.
This command reads an existing configuration file that uses the old format, and writes a new file that uses the current format.
Example
Using kubeadm v1.31, run kubeadm config migrate --old-config old-v1beta3.yaml --new-config new-v1beta4.yaml
How do I get involved?
Huge thanks to all the contributors who helped with the design, implementation, and review of this feature:
- Lubomir I. Ivanov (neolit123)
- Dave Chen(chendave)
- Paco Xu (pacoxu)
- Sata Qiu(sataqiu)
- Baofa Fan(carlory)
- Calvin Chen(calvin0327)
- Ruquan Zhao(ruquanzhao)
For those interested in getting involved in future discussions on kubeadm configuration, you can reach out kubeadm or SIG-cluster-lifecycle by several means:
- v1beta4 related items are tracked in kubeadm issue #2890.
- Slack: #kubeadm or #sig-cluster-lifecycle
- Mailing list