If you are upgrading the version of Kubernetes for a cluster managed by Cluster API, check that the running version of Cluster API on the Management Cluster supports the target Kubernetes version.
You may need to upgrade the version of Cluster API in order to support the target Kubernetes version.
In addition, you must always upgrade between Kubernetes minor versions in sequence, e.g. if you need to upgrade from Kubernetes v1.17 to v1.19, you must first upgrade to v1.18.
For kubeadm based clusters, infrastructure providers require a “machine image” containing pre-installed, matching
kubelet, ensure that relevant infrastructure machine templates reference the appropriate
image for the Kubernetes version.
The high level steps to fully upgrading a cluster are to first upgrade the control plane and then upgrade the worker machines.
To upgrade the control plane machines underlying machine images, the
MachineTemplate resource referenced by the
KubeadmControlPlane must be changed. Since
MachineTemplate resources are immutable, the recommended approach is to
- Copy the existing
- Modify the values that need changing, such as instance type or image ID.
- Create the new
MachineTemplateon the management cluster.
- Modify the existing
KubeadmControlPlaneresource to reference the new
MachineTemplateresource in the
The next step will trigger a rolling update of the control plane using the new values found in the new
To upgrade the Kubernetes control plane version make a modification to the
Spec.Version field. This will trigger a rolling upgrade of the control plane and, depending on the provider, also upgrade the underlying machine image.
Some infrastructure providers, such as AWS, require
that if a specific machine image is specified, it has to match the Kubernetes version specified in the
KubeadmControlPlane spec. In order to only trigger a single upgrade, the new
MachineTemplate should be created first
and then both the
InfrastructureTemplate should be modified in a single transaction.
Upgrades are not limited to just the control plane. This section is not related to Kubeadm control plane specifically, but is the final step in fully upgrading a Cluster API managed cluster.
It is recommended to manage machines with one or more
Machines to allow for a seamless scaling experience. A modification to the
MachineDeployments spec will begin a rolling update of the machines. Follow
these instructions for changing the
template for an existing