Upgrade Guide ​

Must Read Before Upgrade ​

The following introduces the essential knowledge before upgrade operations.

Upgrade Solution ​

Version upgrade enables safe and seamless upgrades from lower versions to higher versions, helping users easily keep up with technological iterations and ensuring that the system remains in a secure, stable, and supported state for the long term.

Version Requirements Before Upgrade ​

The basic concepts related to community versions are introduced as follows:

Component version: A component is the smallest compilable unit in the component repository, and its corresponding Semantic Version is the component version, which evolves according to MAJOR.MINOR.PATCH.

Community version: Versions released by the community, including Release Candidate (RC), official versions, and patch versions, such as v25.12-rc.2, v25.12, v25.12.1, etc.

LTS version: The community version released on December 30 of each year is called the LTS version.

Installable version: Release candidate versions and official versions.

Upgradable version: Higher installable versions and patch versions.

Note:
The currently supported minimum version for upgrade is v25.12-rc.2.

Upgrade Impact ​

When upgrading K8s-related components in a non-high-availability cluster, there will be a brief apiserver service unavailability.

Upgrade Precautions ​

Only version upgrade functionality is provided, version downgrade functionality is not provided. It is recommended to back up etcd data before upgrading and perform manual rollback in case of upgrade failure.

Upgrade Process ​

The following is the upgrade process flowchart.

Pre-upgrade Preparation and Checks ​

The following introduces the preparation and check items before upgrade operations.

Pre-upgrade Preparation and Check List ​

Table 1 Pre-upgrade Preparation Checklist

Note:
The time required for version package files is greatly affected by the number of files to be prepared and network speed.

Cluster Status Check ​

Before upgrading, you need to confirm that the cluster is healthy. Select "Cluster Lifecycle Management" in the openFuyao management interface of the management cluster to view the corresponding business cluster.

Prepare Version Configuration File ​

• Obtain version configuration file

  Download the index file of the openFuyao version. This file records the correspondence between versions and file names.

  bash

  wget https://openfuyao.obs.cn-north-4.myhuaweicloud.com/openFuyao/version-config/index.yaml

  The following shows sample content of index.yaml:

  yaml

  - openFuyaoVersion: v25.12
    filePath: ./VersionConfig-v25.12.yaml
  - openFuyaoVersion: v25.12.1
    filePath: ./VersionConfig-v25.12.1.yaml
  - openFuyaoVersion: v25.12-rc.2
    filePath: ./VersionConfig-v25.12-rc.2.yaml

  Version files can be downloaded via wget:

  bash

  # For example, the following downloads the configuration file for version v25.12
  wget https://openfuyao.obs.cn-north-4.myhuaweicloud.com/openFuyao/version-config/VersionConfig-v25.12.yaml

• Use version configuration file

  The use of version configuration files differs between online installation scenarios and offline installation scenarios, which are introduced separately below.

  • Online scenario

    After downloading the configuration file, the following uses VersionConfig-v25.12.2.yaml as an example to introduce how to place it properly.

    1. Check the REMOTE_PATCH_PATH environment variable of installer-service to get a URL address.

       bash

       # 1. Find the Pod name, for example, the query shows the pod name is installer-service-xxxxx
       kubectl -n openfuyao-system get pods -l app.kubernetes.io/name=installer-service
       
       # 2. Check the environment variable REMOTE_PATCH_PATH
       kubectl -n openfuyao-system describe pod installer-service-xxxxx | grep REMOTE_PATCH_PATH

    2. Place the configuration file under the URL address queried in the first step, and edit the index.yaml file in the URL directory to add the following content.

       bash

       - openFuyaoVersion: v25.12
         filePath: ./VersionConfig-v25.12.yaml
       - openFuyaoVersion: v25.12.1
         filePath: ./VersionConfig-v25.12.1.yaml
       - openFuyaoVersion: v25.12-rc.2
         filePath: ./VersionConfig-v25.12-rc.2.yaml
       - openFuyaoVersion: v25.12.2 # New, fill in the openFuyaoVersion from the VersionConfig-v25.12.2.yaml file
         filePath: ./VersionConfig-v25.12.2.yaml # New

  • Offline scenario

    After downloading the version configuration file, select "Cluster Lifecycle Management > Patch Upload" in the openFuyao management interface of the management cluster and directly upload the file content.

Upload Version Package Files ​

Version package files are divided into offline image package files and binary files, which are introduced separately below.

• Prepare and use image package files

  Note:
  Image package files are required for offline scenario upgrades.

  Prepare the version configuration file (using patchV1.yaml as an example). Two strategies are provided to prepare patch package files: registry and oci strategies. The former requires an environment running a docker daemon.

  • registry strategy

    Follow the steps below to prepare the patch package.

    1. Install Docker (use version 20.10.13 or 18.09.0) and configure Docker. Add the following configuration to the Docker configuration file. Edit the /etc/docker/daemon.json file (create one if it doesn't exist).

       json

        {
        "insecure-registries": [     
          "0.0.0.0/0"
        ]    
        }

    2. Execute the following command to restart docker

       bash

       systemctl restart docker

    3. Prepare image package files

       Execute the following command to prepare the image package files.

       bash

       bke build patch -f patchV1.yaml -t patchV1.tar.gz

  • oci strategy

    Prepare the patch package with the following command.

    bash

    bke build patch -f patchV1.yaml -t patchV1.tar.gz --strategy=oci

  The following shows how to synchronize image package files to the image source service of the offline bootstrap node. Two methods are provided: openFuyao management interface operation and bootstrap node backend operation.

  • openFuyao management interface

    On the openFuyao interface of the bootstrap node, enter "Cluster Lifecycle Management", find the business cluster to be upgraded, enter "Upgrade Preparation", enter the patch package file information, click "OK" to complete the upload of the image package before upgrade.

    Note:
    1. Only image packages prepared with the oci strategy can be uploaded through the openFuyao management interface.
    2. Image package files need to be .tar.gz files and must be placed in the /etc/openFuyao directory of the bootstrap node.
    3. Through the "Upgrade Preparation" on the openFuyao management interface, you can also copy the containerd, kubelet, kubectl binary files to the /bke/mount/source_registry/files directory of the bootstrap node.

  • Bootstrap node backend

    Log in to the backend of the bootstrap node and execute the following command to synchronize images.

    bash

    # First copy patchV1.tar.gz to the bootstrap node
    tar -xzvf patchV1.tar.gz
    # Synchronize the image package to the local image source
    bke registry patch --source ./patchV1 --target 0.0.0.0:40443

• Download and upload binary files