Upgrade the global Cluster

Use this page to upgrade a global cluster that has no disaster recovery standby, for every upgrade, patch upgrades included. If the platform has a primary and a standby global cluster, use Upgrade global Clusters in a DR Environment instead.

One upgrade request moves the global cluster to the target ACP version (Distribution Version): ACP Core and the installed Extensions (Operators and Cluster Plugins) with the Aligned lifecycle. On Alauda OS, the same request also upgrades Kubernetes and Alauda OS, one node at a time. On non-Alauda OS clusters, the request upgrades Kubernetes in place.

Before You Begin

  • Prepare for the Upgrade is complete for the global cluster, including the global cluster checks on Alauda OS.
  • The preflight check has passed, including any administrator acknowledgement that it reported. On a cluster that has never run the Cluster Version Operator (CVO), the final preflight check on this page is the first one.
  • The global cluster has a recent successful etcd backup. See etcd Backup and Restore.
  • You are on the execution host, logged in with ac login as a platform administrator, in the installer/ directory of the extracted target Core Package. upgrade.sh uses kubectl with the kubeconfig that ac login saved.

Select the global cluster, then confirm that no workload cluster upgrade is running; the platform does not block a global upgrade while one runs:

ac config use-cluster global
ac whoami --show-server
ac -n cpaas-system get cvsh \
  -o custom-columns='CLUSTER:.metadata.name,REQUESTED:.spec.desiredUpdate.version,CURRENT:.status.current.version'

Continue when the address ends with /kubernetes/global/ and, on every row, REQUESTED is empty or equal to CURRENT; otherwise, wait until that upgrade completes. If the last command reports the server doesn't have a resource type, the cluster has never been upgraded with CVO; continue.

Upgrade the global Cluster

Deploy the Cluster Version Operator

Deploy CVO and the target release information. The artifacts were published during preparation, so skip the image sync. <target-version> is the target ACP version, for example 4.5.0:

ac config use-cluster global
ac whoami --show-server   # ends with /kubernetes/global/
bash upgrade.sh --skip-sync-image
ac get productmanifest v<target-version>

Continue when the script completes without an error and READY is True. Otherwise, see Recover a Missing Aligned Extension Package.

Run the Final Preflight Check

ac config use-cluster global
ac whoami --show-server   # ends with /kubernetes/global/
bash upgrade.sh --preflight

Continue when Summary shows Passed or PassedWithWarnings. Otherwise, resolve the reported checks as described in Handle Preflight Blocks, then run the check again. AdminAckRequired can appear for the first time here, after the target CVO is deployed; handle it as described in Handle Administrator Acknowledgement Gates.

Request the Upgrade

WARNING

An upgrade cannot be rolled back. On Huawei DCS, Huawei Cloud Stack, and VMware vSphere, the request also replaces every node with a new VM, one at a time; on Bare Metal, it reinstalls every host, one at a time. This happens on every minor upgrade, and on a patch upgrade when the target changes the Kubernetes build or the Alauda OS image.

List the available updates, then request the target version exactly as it is listed:

ac adm upgrade
ac adm upgrade --cluster=global --to=<target-version>

Monitor the Upgrade

ac adm upgrade status --cluster=global

Run the command again until Current shows the target version and the Ready condition is True. Add --verbose to see every check and stage.

On Alauda OS, also follow the Kubernetes upgrade:

ac -n cpaas-system get infraclusterversion global

CURRENT advances through each intermediate Kubernetes version. Continue when CURRENT equals DESIRED and PHASE is Succeeded. While the control plane nodes are replaced, a command can fail to connect; run it again. The upgrade continues on its own.

If Upgrade shows Blocked or Retrying, see Inspect Upgrade State. On Alauda OS, if the upgrade stays InProgress in the Kubernetes stage, read the Stalled condition of the InfraClusterVersion as described there. Fix the reported cause and the upgrade continues; if it cannot be fixed, contact technical support.

Upgrade the Agnostic Extensions

The upgrade request does not upgrade Extensions (Operators and Cluster Plugins) with the Agnostic lifecycle. Upgrade each Agnostic Extension separately by following its own documentation, for example:

Validate the Upgrade

Complete Upgrade Validation for the global cluster to finish its upgrade.

Next Step

Upgrade the workload clusters. See Upgrade Workload Clusters.