#Upgrade the global cluster

#Upload images

Copy the core package to any control plane node of the global cluster. Extract the package and cd into the extracted directory.

• If the global cluster uses the built-in registry, run:

  bash upgrade.sh --only-sync-image=true

• If the global cluster uses an external registry, you also need to provide the registry address:

  bash upgrade.sh --only-sync-image=true --registry <registry-address> --username <username> --password <password>

If you plan to upgrade the Operator and Cluster Plugin together during the global cluster upgrade, you can pre-push their images to the global cluster's registry in advance. For bulk upload instructions, see Push only images from all packages in a directory.

For details of the violet push subcommand, please refer to Upload Packages.

#Trigger the upgrade

After the image upload is complete, run the following command to start the upgrade process:

bash upgrade.sh --skip-sync-image

Wait for the script to finish before proceeding.

If you have already pre-pushed the Operator and Cluster Plugin images to the global cluster's registry, you can then follow Create only CRs from all packages in a directory. After running this command, wait about 10–15 minutes until upgrade notifications appear for functional components. You will then be able to upgrade the Operator and Cluster Plugin together as part of the subsequent upgrade steps.

#(Conditional) Remove TopoLVM

If you are upgrading from 3.18 and the Build of TopoLVM is installed, you must back up and delete the related TopoLVM resources before proceeding with the upgrade.

Otherwise, the cluster upgrade will fail.

Run the following commands on any control plane node of the cluster to be upgraded:

kubectl get artifactversion -n cpaas-system  $(kubectl get artifactversion -n cpaas-system -l cpaas.io/artifact-version=operatorhub-topolvm-operator --no-headers | grep 4.1 | head -1 | awk '{print $1}') -o yaml > topolvm-artifact.yaml
kubectl delete -f topolvm-artifact.yaml

Then, run the following command on any control plane node of the global cluster:

# Replace cluster_name with the name of the cluster to be upgraded
kubectl delete minfo $(kubectl get minfo | grep topolvm-migrate-catalog-updater | grep $cluster_name | awk '{print $1}')

#Upgrade the global cluster

1. Log in to the Web Console of the global cluster and switch to Administrator view.
2. Navigate to Clusters > Clusters.
3. Click on the global cluster to open its detail view.
4. Go to the Functional Components tab.
5. Click the Upgrade button.

Review the available component updates in the dialog, and confirm to proceed.

#(Conditional) Upgrade TopoLVM

If you are upgrading from 3.18 and the Build of TopoLVM is installed, and you have already completed the Remove TopoLVM step.

On a control plane node of the cluster to be upgraded, continue by running the following command to upgrade TopoLVM:

kubectl create -f topolvm-artifact.yaml

After running the command, wait approximately 5–10 minutes. The TopoLVM component will be automatically upgraded and reflected in the web console.

#Install Product Docs Plugin

Starting from 4.0, the built-in product documentation has been separated into the Alauda Container Platform Product Docs plugin. If you are upgrading from 3.x, you need to install this plugin by following these steps:

1. Navigate to Administrator.

2. In the left sidebar, click Marketplace > Cluster Plugins and select the global cluster.

3. Locate the Alauda Container Platform Product Docs plugin and click Install.

#Install Alauda Container Platform Cluster Enhancer Plugin

1. Navigate to Administrator.

2. In the left sidebar, click Marketplace > Cluster Plugins and select the global cluster.

3. Locate the Alauda Container Platform Cluster Enhancer plugin and click Install.

#(Conditional) Install Service Mesh Essentials

If Service Mesh v1 is installed, refer to the Alauda Service Mesh Essentials Cluster Plugin documentation before upgrading the workload clusters.

#Verify data consistency

Follow your regular global DR inspection procedures to ensure that data in the standby global cluster is consistent with the primary global cluster.

If inconsistencies are detected, contact technical support before proceeding.

On both clusters, run the following command to ensure no Machine nodes are in a non-running state:

kubectl get machines.platform.tkestack.io

If any such nodes exist, contact technical support to resolve them before continuing.

#Uninstall the etcd sync plugin

#Upload images

Perform the Upload images step on both the standby cluster and the primary cluster.

See Upload images in Standard procedure for details.

#Upgrade the standby cluster

apiVersion: product.alauda.io/v1alpha2
kind: ProductBase
metadata:
  name: base
spec:
  alternativeURLs:
    - https://<standby-cluster-vip>

On the standby cluster, follow the steps in the Standard procedure to complete the upgrade.

#Upgrade the primary cluster

After the standby cluster has been upgraded, proceed with the Standard procedure on the primary cluster.

#Reinstall the etcd sync plugin

Before reinstalling, verify that port 2379 is properly forwarded from both global cluster VIPs to their control plane nodes.

To reinstall:

1. Access the Web Console of the standby global cluster via its IP or VIP.
2. Switch to Administrator view.
3. Go to Marketplace > Cluster Plugins.
4. Select the global cluster.
5. Locate Alauda Container Platform etcd Synchronizer, click Install, and provide the required parameters.

To verify installation:

kubectl get po -n cpaas-system -l app=etcd-sync  # Ensure pod is 1/1 Running

kubectl logs -n cpaas-system $(kubectl get po -n cpaas-system -l app=etcd-sync --no-headers | awk '{print $1}' | head -1) | grep -i "Start Sync update"
# Wait until the logs contain "Start Sync update"

# Recreate the pod to trigger synchronization of resources with ownerReferences
kubectl delete po -n cpaas-system $(kubectl get po -n cpaas-system -l app=etcd-sync --no-headers | awk '{print $1}' | head -1)

#Check Synchronization Status

Run the following to verify the synchronization status:

curl "$(kubectl get svc -n cpaas-system etcd-sync-monitor -ojsonpath='{.spec.clusterIP}')/check"

Explanation of output:

• "LOCAL ETCD missed keys:" – Keys exist in the primary cluster but are missing in the standby. This often resolves after a pod restart.
• "LOCAL ETCD surplus keys:" – Keys exist in the standby cluster but not in the primary. Review these with your operations team before deletion.