Pre-Upgrade Preparation
Supported upgrade paths: 3.16 → 4.0, 3.18 → 4.0.
Before upgrading, ensure that your current platform version is within this supported range.
TOC
Important notes before upgrade
-
Starting from 4.0, periodic ETCD backup tasks besides the default one will all be deprecated. Before upgrading, backup and delete all ETCD backup tasks except the task
etcd-backup-default(deleting a periodic backup task will not remove any existing snapshot of ETCD, just the task itself). You may reconfigure theetcd-backup-defaulttask as you wish after the upgrading is accomplished. -
When upgrading the cluster's Kubernetes version to 1.31 or higher, all running Pods will be restarted. This behavior is due to changes in the PodSpec fields introduced in Kubernetes 1.31 and cannot be avoided. For more details, refer to the Kubernetes issue report: #129385.
-
Starting from 4.0, the upgrading procedure of the DR (Disaster Recovery Environment) has changed. Please refer to global DR procedure for the new procedure.
Prerequisites
| Condition | Requirement | If Not Met |
|---|---|---|
| Kubernetes | All clusters running 1.28 or later | Upgrade Kubernetes BEFORE proceeding |
| Service mesh (Istio) | All clusters running 1.20 or later | Upgrade Istio and its instances BEFORE proceeding |
| CostManager / Kubecost plugins | Must not be installed (deprecated from 4.0) | Uninstall those plugins |
| Elasticsearch logging | Must comply with the fix described in How to Correct the Issue of Node Role Settings in Big Cluster Elasticsearch (see Custom Portal > Knowledge) | Apply the fix before upgrade |
Disk space on /cpaas/minio (global cluster control plane) | At least 120 GB free | Expand storage |
| Disk space for upgrade package extraction | At least 250 GB free if package and extraction path are on the same disk | Free or expand storage |
| Condition | Requirement | If Not Met |
|---|---|---|
| ClickHouse log storage plugin | Uninstall it before the upgrade, then reinstall it after upgrading |
Preparation procedure
Run the checklist
Contact technical support to obtain the checklist script and run it against the target platform to verify readiness.
Download the upgrade package
For platforms upgrading from version 3.16 or 3.18 to 4.0, the upgrade package is the same as the installation package.
Refer to Download Installation Package for instructions.