Usage Guide for Upgrading from v25.12 to v26.03 ​

This document aims to provide a solution for upgrading openFuyao from v25.12 to v26.03.

Background Information ​

Due to the following changes in v26.03 compared to v25.12, automated version upgrade cannot be achieved.

1. The cluster-api-provider-bke reconciler added the BKENode CRD, and also changed the definition of BKECluster.
2. The bkeagent-deployer node Pod switched the health probe from HTTP protocol to HTTPS protocol, and its startup depends on TLS certificates issued by the cluster CA certificate.
3. There is an issue with the installer-service service obtaining the upgrade version list, which prevents openFuyao clusters on v25.12 from obtaining upgradable versions such as v26.03.
4. As installer-website is the frontend service of installer-service, the versions of both need to match.

Prerequisites ​

A v25.12 cluster installed using openFuyao.

Usage Restrictions ​

None.

Usage Scenarios ​

• Online environment, business clusters deployed by bootstrap cluster.
• Offline environment, business clusters deployed by bootstrap cluster.
• Online environment, business clusters deployed by management cluster.
• Offline environment, business clusters deployed by management cluster.

Bootstrap Cluster Deploying Business Clusters ​

Bootstrap clusters can directly deploy and install business clusters. Bootstrap clusters do not have upgrade capabilities and require manual handling.

Online Installation ​

Follow the steps below to perform version upgrade operations for business clusters deployed by the bootstrap cluster.

1. Execute the following command on the bootstrap node to download the preprocessing script.

   bash

   curl -O https://openfuyao.obs.cn-north-4.myhuaweicloud.com/openFuyao/tmp/patch-test/v25.12_to_v26.03_upgrade_bypass_script.tar.gz

2. Extract the archive and enter the business cluster upgrade directory for the online scenario.

   bash

   tar -xzvf v25.12_to_v26.03_upgrade_bypass_script.tar.gz
   cd bootstrap_cluster_deploy_service_cluster/online/

3. Processing for the first installed business cluster.

   3.1 Pre-upgrade preparation.

   bash

   ## Choose one of "Step-by-step execution" or "One-time execution" below.
   
   ### Step-by-step execution on each node
   #### Step 1: Update installer-service and installer-website on the bootstrap node
   chmod +x update-installer.sh && sh ./update-installer.sh
   
   #### Step 2: Update CRD and add bn on the bootstrap node
   ##### 1. First prepare the nodes.txt file (only fill in node information for the first business cluster to be processed), then execute the following command
   chmod +x update-crd.sh && sh ./update-crd.sh
   ##### 2. Add bn data for the business cluster on the bootstrap node (required if there are multiple business clusters)
   #### First prepare the nodes-bn.txt file (fill in node information for all remaining business clusters according to the format), then execute the following command
   #### Note: After completing this operation, it is normal for the business cluster STATE to change to Deploying status
   chmod +x add-bn.sh && sh ./add-bn.sh
   
   #### Step 3: Update bkeagent on each node of the business cluster
   ##### 1. Generate certificates on each node (node_ip needs to be replaced with the actual node IP address)
   chmod +x cert-gen.sh && sh ./cert-gen.sh node_ip
   ##### 2. Select one node at random to update bkeagent-deployer
   chmod + update-bkeagent-deployer.sh && sh ./update-bkeagent-deployer.sh
   ##### 3. Update bkeagent on each node (make sure the bkeagent-deployer.yaml file is in the same directory)
   chmod +x update-bkeagent.sh && sh ./update-bkeagent.sh
   
   #### Step 4: Update cluster-api-provider-bke on the bootstrap node
   #### First prepare the nodes.txt file (node information for the first business cluster to be processed), then execute the following command
   chmod +x update-provider.sh && sh ./update-provider.sh
   
   ### One-time execution on the bootstrap node
   #### Step 1: Preprocessing: Fill in node information according to the format, prepare the nodes.txt file (only containing node information for the first business cluster to be processed) and the nodes-bn.txt file (containing node information for all remaining business clusters, leave empty if there are none, but the file needs to exist), then execute the following command
   #### Note: 1. sshpass needs to be installed on the execution node  2. DRY_RUN=1 sh ./upgrade-all.sh  can be executed this way to preview preprocessing operations
   chmod +x upgrade-all.sh && sh ./upgrade-all.sh

   3.2 Upgrade processing.

   On the openFuyao management interface of the bootstrap node, select the corresponding business cluster and issue the version upgrade task (from v25.12 to v26.03).

4. Processing for remaining installed business clusters.

   4.1 Pre-upgrade preparation.

   bash

   ## Choose one of "Step-by-step execution" or "One-time execution" below.
   
   ### Step-by-step execution on each node
   #### Step 1: Update bkeagent on each node of the business cluster
   ##### 1. Generate certificates on each node (node_ip needs to be replaced with the actual node IP address)
   chmod +x cert-gen.sh && sh ./cert-gen.sh node_ip
   ##### 2. Select one node at random to update bkeagent-deployer
   chmod + update-bkeagent-deployer.sh && sh ./update-bkeagent-deployer.sh
   ##### 3. Update bkeagent on each node (make sure the bkeagent-deployer.yaml file is in the same directory)
   chmod +x update-bkeagent.sh && sh ./update-bkeagent.sh
   
   ### One-time execution on the bootstrap node
   #### Step 1: Preprocessing: Fill in node information according to the format, prepare the nodes.txt file (containing node information for the business cluster to be processed), then execute the following command
   #### Note: 1. sshpass needs to be installed on the execution node  2. DRY_RUN=1 sh ./upgrade-other.sh  can be executed this way to preview preprocessing operations
   chmod +x upgrade-other.sh && sh ./upgrade-other.sh

   4.2 Upgrade processing.

   On the openFuyao management interface of the bootstrap node, select the corresponding business cluster and issue the version upgrade task (from v25.12 to v26.03).

Offline Installation ​

The operation process for offline installation is similar, with the following differences.

• Different processing directory.

  bash

  tar -xzvf v25.12_to_v26.03_upgrade_bypass_script.tar.gz
  cd bootstrap_cluster_deploy_service_cluster/offline/

• Upload the Core-VersionConfig-v26.03.yaml version file in the directory on the openFuyao management interface before upgrading.

Management Cluster Deploying Business Clusters ​

The bootstrap cluster first brings up the management cluster, then uses the management cluster to deploy business clusters. In this scenario, the management cluster needs to be upgraded first, and then the business clusters can be upgraded. Both upgrade scenarios are controlled by the management cluster.

Online Installation ​

Follow the steps below to perform version upgrade operations for business clusters deployed by the management cluster.

1. Self-upgrade processing for the management cluster.

   1.1 Execute the following command on any node of the management cluster to download the preprocessing script.

   bash

   curl -O https://openfuyao.obs.cn-north-4.myhuaweicloud.com/openFuyao/tmp/patch-test/v25.12_to_v26.03_upgrade_bypass_script.tar.gz

   1.2 Extract the archive and enter the management cluster upgrade directory for the online scenario.

   bash

   tar -xzvf v25.12_to_v26.03_upgrade_bypass_script.tar.gz
   cd manager_cluster_deploy_service_cluster/online/upgrade_manager_cluster/

   1.3 Pre-upgrade preparation.

   bash

   ## Choose one of "Step-by-step execution" or "One-time execution" below.
   
   ### Step-by-step execution on each node
   #### Step 1: Update installer-service and installer-website on any node of the management cluster
   chmod +x update-installer.sh && sh ./update-installer.sh
   
   #### Step 2: Update cluster-api-provider-bke on any node of the management cluster
   #### First prepare the nodes.txt file (fill in management cluster node information according to the format), then execute the following command
   chmod +x update-provider.sh && sh ./update-provider.sh
   
   #### Step 3: Update bkeagent on each node of the management cluster
   ##### 1. Generate certificates on each node (node_ip needs to be replaced with the actual node IP address)
   chmod +x cert-gen.sh && sh ./cert-gen.sh node_ip
   ##### 2. Select one node at random to update bkeagent-deployer
   chmod +x update-bkeagent-deployer.sh && sh ./update-bkeagent-deployer.sh
   ##### 3. Update bkeagent on each node (make sure the bkeagent-deployer.yaml file is in the same directory)
   chmod +x update-bkeagent.sh && sh ./update-bkeagent.sh
   
   #### Step 4: Add bn data for business clusters on any node of the management cluster (required if there are business clusters brought up by the management cluster, otherwise this step can be skipped)
   #### First prepare the nodes-bn.txt file (fill in node information for all business clusters according to the format), then execute the following command
   #### Note: After completing this operation, it is normal for the business cluster STATE to change to Deploying status.
   chmod +x add-bn.sh && sh ./add-bn.sh
   
   
   ### One-time execution on any node of the management cluster
   #### Step 1: Preprocessing
   #### Fill in node information according to the format, prepare the nodes.txt file (containing management cluster node information) and the nodes-bn.txt file (containing node information for all business clusters, leave empty if there are none, but the file needs to exist), then execute the following command
   #### Note: 1. sshpass needs to be installed on the execution node  2. DRY_RUN=1 sh ./upgrade-all.sh  can be executed this way to preview preprocessing operations
   chmod +x upgrade-all.sh && sh ./upgrade-all.sh

   Notice:
   The nodes.txt and nodes-bn.txt files should not contain empty lines.

   1.4 Upgrade processing.

   On the openFuyao management interface of the management cluster, select the management cluster itself and issue the version upgrade task (from v25.12 to v26.03).

2. Upgrade processing for business clusters.

   After the management cluster upgrade is complete, you can proceed with the upgrade operations for the business clusters.

   2.1 Based on the management cluster upgrade, since the preprocessing script has already been downloaded, directly enter the business cluster upgrade directory here.

   bash

   cd manager_cluster_deploy_service_cluster/online/upgrade_service_cluster/

   2.2 Pre-upgrade preparation.

   bash

   ## Choose one of "Step-by-step execution" or "One-time execution" below.
   
   ### Step-by-step execution on each node
   #### Step 1: Update bkeagent on each node of the business cluster
   ##### 1. Generate certificates on each node (node_ip needs to be replaced with the actual node IP address)
   chmod +x cert-gen.sh && sh ./cert-gen.sh node_ip
   ##### 2. Select one node at random to update bkeagent-deployer
   chmod +x update-bkeagent-deployer.sh && sh ./update-bkeagent-deployer.sh
   ##### 3. Update bkeagent on each node (make sure the bkeagent-deployer.yaml file is in the same directory)
   chmod +x update-bkeagent.sh && sh ./update-bkeagent.sh
   
   
   
   ### One-time execution on any node of the management cluster
   #### Step 1: Preprocessing
   #### First prepare the nodes.txt file (containing all node information for the current business cluster), then execute the following command
   #### Note: 1. sshpass needs to be installed on the execution node  2. DRY_RUN=1 sh ./upgrade-all.sh  can be executed this way to preview preprocessing operations
   chmod +x upgrade-all.sh && sh ./upgrade-all.sh

   Notice:
   The nodes.txt and nodes-bn.txt files should not contain empty lines.

   2.3 Upgrade processing.

   On the openFuyao management interface of the management cluster, select the corresponding business cluster and issue the version upgrade task (from v25.12 to v26.03).

Offline Installation ​

The operation process for offline installation is similar, with the following differences.

• Self-upgrade for management cluster.

  • Different processing directory.

    bash

    tar -xzvf v25.12_to_v26.03_upgrade_bypass_script.tar.gz
    cd bootstrap_cluster_deploy_service_cluster/offline/

  • Upload the Core-VersionConfig-v26.03.yaml version file in the directory on the openFuyao management interface before upgrading.

• Enter the following directory for business cluster upgrade.

  bash

  tar -xzvf v25.12_to_v26.03_upgrade_bypass_script.tar.gz
  cd manager_cluster_deploy_service_cluster/offline/upgrade_service_cluster/