#Pre-Upgrade Preparation

Supported upgrade paths:

At the minor-release policy level, ACP 4.1, 4.2, and 4.3 are within the n-3 direct-upgrade window for the ACP 4.4 release line. This policy does not make every source patch eligible for every target patch.

Upgrade only to a target 4.4.x version that the platform offers for the current source patch. After the target ProductManifest is registered, confirm that the target appears in availableUpdates in the Web Console or ac adm upgrade, and confirm that the VersionUpgradePath preflight check passes. If no 4.4.x target is offered, use a later 4.4.x target that includes the current source patch or first follow an intermediate target offered by the platform. Do not use an explicit upgrade request or disable VersionUpgradePath to bypass an unsupported source-to-target combination.

ACP 4.0.x is outside the direct-upgrade window for ACP 4.4. Follow the intermediate upgrade chain offered by the platform, and verify availableUpdates and VersionUpgradePath at every hop.

#Important Notes

• Ensure the directory /cpaas/minio on the control plane nodes of global cluster has at least 120 GB of free disk space.
• Before upgrading the global tier, verify that all workload clusters remain within the target Distribution Version's Compatible Versions documented in Kubernetes Support Matrix.
• If any workload cluster is outside the target compatible range, upgrade that workload cluster first until it enters the range before upgrading the global tier.
• A workload cluster can be upgraded only to a Distribution Version that the global tier has already reached.

#Verify Module Stability Before You Upgrade

The cluster upgrade preflight requires every installed Core and Aligned plugin module on the target cluster to be in a stable state. If any such module is mid-install, mid-upgrade, or failed, the ModuleInfoStable and ClusterModuleStable preflight checks block the upgrade until it is resolved. A common cause is a standalone plugin upgrade that is still running when the cluster upgrade is requested.

Before you request the upgrade, list the installed modules on the target cluster and confirm every one is in the Running phase:

kubectl get moduleinfo -l cpaas.io/cluster-name=<cluster> \
  -o custom-columns='MODULE:.metadata.labels.cpaas\.io/module-name,CURRENT:.status.version,TARGET:.spec.version,PHASE:.status.phase'

Also confirm the cluster module itself is not in a deploy or upgrade failure state:

kubectl get clustermodule <cluster> -o jsonpath='{.status.base.deployStatus}{"\n"}'

Every module PHASE must be Running, and deployStatus must not be Upgrading, DeployFailed, or UpgradeFailed. If a module is still upgrading, wait for it to reach Running; if a module is Failed or Blocked, resolve it before you request the cluster upgrade.

#Kubernetes 1.35 or Later Node Readiness

If the target release is ACP 4.4 or later, upgrades the cluster to Kubernetes 1.35 or later, and reports an administrator acknowledgement gate for node readiness, verify every production node that will run the target cluster before acknowledging the gate.

Log in to each node through SSH or another administrative node access method available in your environment, and run the following checks directly on the node operating system. The account and credentials depend on how the cluster nodes were provisioned.

Verify the Linux kernel version:

uname -r

The kernel must be 5.8 or later and must also be within the ACP supported operating system and kernel matrix for the target release.

Verify that the node uses cgroup v2:

stat -fc %T /sys/fs/cgroup/

The expected output is:

cgroup2fs

#Download the Packages for Offline Environments

A production maintenance window typically upgrades Core, the Aligned plugins (cluster plugins and operators released together with the same ACP version), and the in-use Agnostic plugins (independently released cluster plugins and operators) in the same window. Core and Extension packages are separate downloads. Prepare all three package sets before the maintenance window so that artifact synchronization can finish early.

#Step 1: Download the Core Package

From the Customer Portal, download the 4.4 Core Package that matches your target architecture. The Core Package contains Core artifacts only; it does not contain any Aligned or Agnostic Extension package.

#Step 2: Download ACP Upgrade to v4.4

Use Violet v4.2.13 or later to download the scenario packages directly. Run violet version to verify the version, and use violet ac login to log in to the Customer Portal. For installation and login instructions, see Download Packages.

Set <target-platform-version> to the exact ACP Distribution Version of the Core Package, such as v4.4.0. Set <arch> to amd64, arm64, or hybrid to match the Core Package. List the scenarios first, and then download ACP Upgrade to v4.4:

violet ac scenarios --arch=<arch> --platformVersion=<target-platform-version>
violet ac download-app --arch=<arch> --platformVersion=<target-platform-version> --scenario="ACP Upgrade to v4.4"

Confirm that ACP Upgrade to v4.4 appears in the scenario list before downloading it.

As an alternative to Violet, in the Customer Portal, go to Marketplace > Batch Download > Install. On the page, select the target Core Package version from Your ACP Version, select the matching Architecture, select ACP Upgrade to v4.4 from Scenarios, and download the packages.

This package set provides the target-version packages for the following Aligned applications. These packages remain separate from the Core Package:

• Alauda Container Platform Web Console
• Alauda Container Platform Web Console Central
• Alauda Container Platform Marketplace Web Console
• Alauda Container Platform Helm Application Catalog
• Alauda Container Platform Observability Essentials
• Alauda Container Platform Essentials
• Alauda Container Platform Cluster Essentials
• Alauda Container Platform GatewayAPI Plugin
• Alauda Container Platform Monitoring for Prometheus
• Alauda Language Pack for Chinese
• Alauda Container Platform Networking for Calico

Before publishing upgrade artifacts, manually copy all eleven packages into the plugins/ directory of the extracted Core Package. Sync upgrade artifacts describes the built-in and external Registry publication branches.

#Step 3: Inventory other Extensions on every cluster in scope

Cluster plugins and operators are managed by different mechanisms. Both are needed in this step:

• Cluster plugins are global resources. A cluster plugin pushed to the global tier becomes installable and upgradable on every cluster in the platform; you only push each cluster plugin once.
• Operators are scoped to each cluster. Pushing an operator to the global tier is the recommended starting point, but the same operator package must be available on each workload cluster before that cluster's upgrade.

Use the same violet installation from Step 2 to inventory installed Extensions and publish packages that are not part of ACP Upgrade to v4.4. For more information, see Download Packages and Upload Packages.

On any machine with network access to the platform endpoint, run violet list to list the plugins (both Aligned and Agnostic) installed in the current environment and export the result to ./apps.yaml:

violet list \
  --platform-address "https://<your-platform-domain>" \
  --platform-token "<platform_token>" \
  --output-file "./apps.yaml"

Prefer --platform-token over --platform-password to avoid exposing passwords in shell history and process listings (ps aux).

Violet v4.2.13 or later is required for this token-based inventory workflow. Earlier versions can fail with failed to get user info from platform server; upgrade Violet before continuing.

#Step 4: Download the other Extension packages

Import the exported apps.yaml file into the Customer Portal to align the package list with what your clusters currently run. Download the matching target-version packages for the other Aligned and Agnostic Extensions that your clusters use.

If the result includes one of the eleven applications from ACP Upgrade to v4.4, do not publish that duplicate with violet. Use the package from ACP Upgrade to v4.4 through the Core Package's plugins/ directory instead. Use violet push only for the remaining Extension packages.

Download every package you will need so they are all available locally before the upgrade window starts. The next page, Upgrade the global cluster, describes how the selected Registry path publishes Core and the eleven manually staged packages, and how violet publishes the other Extensions. Artifact publication does not upgrade any already-running plugin, so complete it before the maintenance window.