升级指导 ​

升级前必读 ​

下面介绍升级操作前的必备知识。

升级方案 ​

版本升级实现从低版本到高版本的安全、无缝升级，帮助用户轻松跟上技术迭代，保障系统长期处于安全、稳定、支持的状态。

升级前的版本要求 ​

社区版本相关基本概念介绍如下：

组件版本：组件仓库可编译的最小单位即组件，其对应的Semantic Version就是组件版本，按照MAJOR.MINOR.PATCH演进。

社区版本：社区发布的版本，包含候选版本（Release Candidate，简称RC）、正式版本和补丁版本，比如v25.12-rc.2、v25.12、v25.12.1等。

LTS版本：每年1230发布的社区版本称为LTS版本。

可安装版本：候选版本和正式版本。

可升级版本：更高的可安装版本和补丁版本。

说明：
目前支持可升级的最低版本是v25.12-rc.2。

升级影响 ​

非高可用集群升级K8s相关组件时，会出现短暂的apiserver服务不可用。

升级注意事项 ​

只提供了版本升级功能，未提供版本降级功能，升级前建议备份etcd数据，升级失败时进行手动回滚。

升级流程 ​

下面是升级流程图。

升级前准备与检查 ​

下面介绍升级操作前的准备与检查项。

升级前准备与检查表 ​

表1 升级前准备清单

说明：
版本包文件耗时受版本文件需要准备的文件数量、网络速度影响较大。

集群状态检查 ​

升级前需要确认集群是健康的，在管理集群的openFuyao管理面中选择“集群生命周期管理”查看相应的业务集群即可。

准备版本配置文件 ​

• 获取版本配置文件

  版本配置文件记录着组件的版本信息，获取地址：https://openfuyao.obs.cn-north-4.myhuaweicloud.com/openFuyao/version-config。

  这个路径下包含一个名为index.yaml的索引文件和许多的版本配置yaml文件，可以通过wget下载：

  bash

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

  下面展示的是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

  版本文件可以通过wget下载：

  bash

  # 比如下面是下载v25.12版本的配置文件
  wget https://openfuyao.obs.cn-north-4.myhuaweicloud.com/openFuyao/version-config/VersionConfig-v25.12.yaml

• 使用版本配置文件

  版本配置文件的使用区分在线安装场景和离线安装场景，下面分开介绍。

  • 在线场景

    下载好配置文件，下面以VersionConfig-v25.12.2.yaml为例子进行介绍，通过下面步骤放置好。

    1. 查看installer-service的REMOTE_PATCH_PATH环境变量，会得到一个url地址。

       bash

       # 1. 找到Pod名称，比如查询pod名称是installer-service-xxxxx
       kubectl -n openfuyao-system get pods -l app.kubernetes.io/name=installer-service
       
       # 2. 查看环境变量REMOTE_PATCH_PATH
       kubectl -n openfuyao-system describe pod installer-service-xxxxx | grep REMOTE_PATCH_PATH

    2. 将配置文件放置在第一步查询到的url地址下，并编辑url目录下的index.yaml文件，添加下面内容。

       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 # 新增，填写VersionConfig-v25.12.2.yaml文件中openFuyaoVersion
         filePath: ./VersionConfig-v25.12.2.yaml # 新增

  • 离线场景

    下载好版本配置文件，在管理集群的openFuyao管理面中选择“集群生命周期管理 > 补丁上传”直接上传文件内容。

上传版本包文件 ​

版本包文件分为离线镜像包文件和二进制文件，下面分开介绍。

• 制备和使用镜像包文件

  说明：
  镜像包文件是离线场景下升级所需要的。

  预备版本配置文件（以patchV1.yaml为例），提供两种策略制备补丁包文件，分别是registry和oci策略，其中前者需要运行docker守护进程的环境。

  • registry策略

    按照下面步骤制备补丁包。

    1. 安装docker并配置docker，在Docker配置文件中增加以下配置。编辑/etc/docker/daemon.json文件（如果没有就创建一个）。

       json

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

    2. 执行下面命令，重启docker

       bash

       systemctl restart docker

    3. 制备镜像包文件

       执行下面命令制备镜像包文件。

       bash

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

  • oci策略

    通过下面命令制备补丁包。

    bash

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

  下面展示镜像包文件如何同步到离线引导节点的镜像源服务，提供两种方式，分别是openFuyao管理面操作和引导节点后端操作。

  • openFuyao管理面

    引导节点的openFuyao界面，进入“集群生命周期管理”，找到要升级的业务集群，进入“升级准备”，输入补丁包文件信息，单击“确定”，完成升级前镜像包的上传。

    说明：
    1.通过openFuyao管理面上传的只能是oci策略制备的镜像包。
    2.镜像包文件需要是.tar.gz文件，且要放置在引导节点的/etc/openFuyao目录下。
    3.通过openFuyao管理面的“升级准备”还可以将containerd、kubelet、kubectl二进制文件复制到引导节点的/bke/mount/source_registry/files目录下。

  • 引导节点后端

    登录到引导节点后端，执行下面命令同步镜像。

    bash

    # 需要先复制patchV1.tar.gz到引导节点
    tar -xzvf patchV1.tar.gz
    # 同步镜像包到本地镜像源
    bke registry patch --source ./patchV1 --target 0.0.0.0:40443

• 下载和上传二进制文件

  下载升级所需的二进制文件，所需的文件会在版本配置文件中体现，如下样例：

  yaml

  files:
    - address: https://openfuyao.obs.cn-north-4.myhuaweicloud.com/containerd/containerd/releases/download/patch_test/
      files:
        - fileName: containerd-v2.1.2-linux-amd64.tar.gz
        - fileName: containerd-v2.1.2-linux-arm64.tar.gz

  执行下面的命令下载文件：

  bash

  wget https://openfuyao.obs.cn-north-4.myhuaweicloud.com/containerd/containerd/releases/download/patch_test/containerd-v2.1.2-linux-amd64.tar.gz
  
  wget https://openfuyao.obs.cn-north-4.myhuaweicloud.com/containerd/containerd/releases/download/patch_test/containerd-v2.1.2-linux-arm64.tar.gz

  下载好的二进制文件需要放到引导节点的/bke/mount/source_registry/files目录下。

升级操作 ​

按照下面步骤进行业务集群的升级：

1. 管理集群的openFuyao界面，进入“集群生命周期管理”，找到业务集群，进入“升级”子界面，选择对应的升级版本，单击“确定”，下发升级操作。
2. 等待升级结果，升级成功就结束流程，失败就需要手动回退（依赖于用户升级前备份的etcd数据）。