#Upgrading Clusters

This section provides instructions for upgrading Kubernetes clusters managed by Cluster API.

#Upgrade Overview

Cluster upgrades on Immutable Infrastructure follow a two-phase approach:

1. Phase 1: Upgrade Distribution Version (Aligned Extensions)
2. Phase 2: Upgrade Kubernetes Version

#Distribution Version vs Kubernetes Version

Each Distribution Version corresponds to a specific Kubernetes version. Upgrading the Distribution Version updates cluster extensions and may enable new Kubernetes versions.

#Prerequisites

• Control Plane is reachable and healthy
• All nodes are in Ready state
• Sufficient IP Pool capacity for rolling updates

#Phase 1: Upgrading Distribution Version (Aligned Extensions)

Upgrading the Distribution Version updates the cluster's Aligned Extensions (L3 and L4 plugins).

#Using the Web UI

Navigation: Clusters → Clusters → Select cluster → Aligned Extensions Tab → Click Upgrade

#Step 1: Review Modifications

Review any detected modifications that may affect the upgrade.

Operations:

• Acknowledge: Confirm review and proceed to Step 2
• Cancel: Abort the upgrade process

#Step 2: Upgrade Aligned Extensions

Version Information:

• Current Version: The cluster's current Distribution Version
• Target Version: The global cluster's Distribution Version

Plugin Impact Assessment:

For Medium and High impact plugins, check Acknowledge to confirm you understand the risks.

Operations:

• Back: Return to Step 1 to re-review modifications
• Start Upgrade: Begin the upgrade (only available after acknowledging Medium/High impacts)
• Cancel: Abort the upgrade process

#Post-Upgrade Verification

After the Distribution Version upgrade completes:

• Cluster's Distribution Version is updated
• Node Pools' Kubernetes versions are now lower than the new Distribution Version supports
• Proceed to Phase 2 to upgrade Kubernetes

#Phase 2: Upgrading Kubernetes Version

After upgrading Distribution Version, upgrade Kubernetes on each Node Pool. Provider-specific guides contain the Phase 2 procedures for each platform.

See platform-specific guides:

• Huawei DCS
• Huawei Cloud Stack
• VMware vSphere

#Preparing for Cross-Version Upgrades

When the target ACP Distribution Version is more than one Kubernetes minor above the cluster's current version, additional preparation is required before starting Phase 2. Single-minor upgrades skip this section.

On Immutable Infrastructure, each Kubernetes minor is baked into a matching OS image, and each Kubernetes minor maps to a specific ACP version row in OS Support Matrix. The Kubernetes version therefore moves forward one minor at a time, stepping through the OS image of each intermediate ACP row. The ACP Core (Distribution Version) itself is still upgraded directly to the target version through the Cluster Version Operator — only the Kubernetes version steps through the intermediate minors.

Identify every ACP minor between the current and target versions, use the latest patch in each row, and complete the following pre-staging for each intermediate version before starting Phase 2.

#Step 1 — Pre-sync intermediate Core images to the registry

For each intermediate ACP version, download its Core package and synchronize only its images into the registry. Do not request a Core upgrade to the intermediate version.

bash upgrade.sh --only-sync-image

See Sync upgrade artifacts for command options.

This places the intermediate-version CoreDNS, etcd, and Kube-OVN chart images in the registry so the staged Kubernetes rollout can pull them when KubeadmControlPlane is patched to the matching OS Support Matrix row. In an air-gapped environment, missing intermediate images prevent the new control plane components from starting.

Aligned plugins do not need an extra violet push for the intermediate versions; they move directly to the target version with the Core upgrade, and the Kube-OVN chart used by each intermediate Kubernetes hop is already covered by the Core image sync above.

#Step 2 — Stage intermediate OS images for the provisioning mechanism

For each intermediate ACP version, make the matching OS image (the Alauda OS Image Version value from the OS Support Matrix row) available to the node provisioning mechanism so the Kubernetes step can replace nodes from each image in turn:

• IaaS providers (Huawei DCS, VMware vSphere, Huawei Cloud Stack): upload the OS image and register it as a VM template (or VM image, depending on the platform) under the exact name listed in the OS Support Matrix row.
• Bare metal: make the OS image available to the node re-provisioning flow used by your cluster.

The control plane and worker rollouts then step through the intermediate OS images one at a time, matched to the staged Kubernetes minor, until the cluster reaches the target ACP version row.

#Step 3 — Apply the platform-specific procedure for each intermediate version

Repeat the platform-specific Phase 2 procedure for each intermediate ACP version in turn, using that version's row in OS Support Matrix for KubeadmControlPlane and MachineDeployment values. For each hop, complete the provider's standard procedure — control plane first, then workers, per the Kubernetes version skew policy — before starting the next. After all intermediate hops succeed, apply the same procedure once more for the target ACP version.

#Platform-Specific Instructions

Select your platform for detailed upgrade instructions:

#Related Topics

• Creating Clusters
• Managing Nodes
• Infrastructure Resources