#Upgrading the global Cluster

This document describes how to upgrade a global cluster that runs on Immutable Infrastructure. Upgrades replace nodes with new MicroOS images managed by the Cluster API provider; in-place node upgrades are not used.

#When to Use This Path

Choose this upgrade path when:

• The global cluster was originally installed on Immutable Infrastructure. See Installing the global Cluster.
• Your infrastructure is one of the documented providers: Huawei DCS or Huawei Cloud Stack. VMware vSphere and bare-metal support for the global cluster are planned.

For traditional-OS global clusters, use the standard upgrade path instead.

#Two-Phase Upgrade Overview

Like workload clusters, the global cluster on Immutable Infrastructure follows a two-phase upgrade.

1. Phase 1 — Distribution Version: aligned and agnostic extensions are upgraded to the target Distribution Version. The procedure is shared with workload clusters; see Upgrading Clusters for the Phase 1 mechanics.
2. Phase 2 — Kubernetes and OS Image: nodes are replaced with new MicroOS images that contain the target Kubernetes version. This document focuses on Phase 2 for the global cluster.

#Common Prerequisites

• The global cluster has completed Phase 1 (Distribution Version upgrade).
• An etcd backup of the global cluster has been taken and verified.
• The new MicroOS image and the matching KubeadmControlPlane and MachineDeployment versions are available on the platform's registry.
• A maintenance window plan that accounts for rolling control plane replacement.

#Procedure

After installation, the Cluster API controllers that manage the global cluster run on the global cluster itself. Use the global kubeconfig for the kubectl commands in this procedure.

#Step 1 — Update the global Cluster Manifest

Update the Cluster API manifests of the global cluster to reference the new MicroOS image and Kubernetes version. The manifest fields to update are provider-specific.

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: DCSIpHostnamePool
metadata:
  name: <global-pool-name>
  namespace: cpaas-system
spec:
  pool:
    - ip: <node-ip>
      hostname: <node-hostname>
      persistentDisk:
        - slot: 0
          quantityGB: 40
          datastoreName: <datastore-name>
          path: /var/cpaas
          format: xfs
          mountOptions:
            - defaults

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: HCSMachineConfigPool
metadata:
  name: <global-pool-name>
  namespace: cpaas-system
  labels:
    cluster.x-k8s.io/cluster-name: global
spec:
  configs:
    - hostname: <node-hostname>
      networks:
        - subnetName: <subnet-name>
          ipAddress: <node-ip>
      persistentDisks:
        - slot: 0
          size: 100
          type: SSD
          mountPath: /var/cpaas
          format: xfs
          mountOptions:
            - defaults
            - noatime

#Step 2 — Apply the Updated Manifest

Apply the updated manifest against the global cluster.

kubectl --kubeconfig <global-kubeconfig> apply -f <updated-manifest>

The Cluster API provider begins replacing control plane and worker nodes by using the new image. When maxSurge: 0 is set, each old node is drained and deleted before its replacement can reuse the same fixed identity, IP address, or preserved disk.

#Step 3 — Monitor the Rolling Replacement

Watch the rolling replacement until all control plane and worker nodes have been replaced.

kubectl --kubeconfig <global-kubeconfig> get machines -A -o wide
kubectl --kubeconfig <global-kubeconfig> get kubeadmcontrolplane -A

The upgrade is complete when every Machine reports the new Kubernetes version and Phase: Running, and the KubeadmControlPlane reports Ready: True against the new version.

#Verification

After the rolling replacement finishes, verify that the upgraded global cluster is healthy.

kubectl --kubeconfig <global-kubeconfig> get nodes -o wide
kubectl --kubeconfig <global-kubeconfig> get clusterversionshadow -o yaml
kubectl --kubeconfig <global-kubeconfig> get pods -n cpaas-system

All nodes must report the new Kubernetes version, the ClusterVersionShadow must reflect the target Distribution Version, and core platform pods must be Running.

#Rollback Considerations

Rollback after a partial Phase 2 upgrade is provider-specific. In general:

If the upgrade has not yet replaced any control plane node, revert the manifest to the previous image and reapply. If control plane nodes have been replaced, restore from the etcd backup taken before starting the upgrade, then revert the manifest.

#Next Steps

• Upgrade workload clusters to the same Distribution Version: see Upgrading Clusters.
• Review machine configuration changes that ship with the new image: see Machine Configuration.