使用 KubeKey 离线升级

对于 Kube AI Hub 和 Kubernetes 都是通过 KubeKey 部署的用户，推荐使用 KubeKey 离线升级。如果您的 Kubernetes 集群由云厂商托管或自行配置，请参考使用 ks-installer 离线升级。

准备工作

您需要有一个运行 Kube AI Hub v3.3.x 的集群。如果您的 Kube AI Hub 是 v3.2.0 或更早的版本，请先升级至 v3.3.x。
您的 Kubernetes 版本必须为 v1.28.x、v1.29.x、v1.30.x、v1.31.x、v1.32.x、v1.33.x 或 v1.34.x。
请仔细阅读 3.4.1 版本说明。
提前备份所有重要的组件。
镜像仓库。您需要有一个 Harbor 或其他镜像仓库。
请确保每个节点都可以从该镜像仓库拉取镜像或向其推送镜像。

重要提示

Kube AI Hub 3.4 对内置角色和自定义角色的授权项做了一些调整。在您升级到 Kube AI Hub 3.4 时，请注意以下几点：

内置角色调整：移除了平台级内置角色 users-manager(用户管理员)和 workspace-manager（企业空间管理员），如果已有用户绑定了 users-manager 或 workspace-manager，他们的角色将会在升级之后变更为 platform-regular。增加了平台级内置角色 platform-self-provisioner。关于平台角色的具体描述，请参见创建用户。
自定义角色授权项调整：
- 移除平台层级自定义角色授权项：用户管理，角色管理，企业空间管理。
- 移除企业空间层级自定义角色授权项：成员管理，角色管理，用户组管理。
- 移除命名空间层级自定义角色授权项：成员管理，角色管理。
- 升级到 Kube AI Hub 3.4 后，自定义角色会被保留，但是其包含的已被移除的授权项会被删除。

升级 Kube AI Hub 和 Kubernetes

单节点集群 (All-in-One) 和多节点集群的升级步骤不同。

信息

当升级 Kubernetes 时，KubeKey 将从一个小版本升级到下一个小版本，直到目标版本。例如，您会发现升级过程是从 1.28 先升级到 1.29 然后再升级到 1.30，而不是直接从 1.28 升级到 1.30。

系统要求

系统	最低要求（每个节点）
Ubuntu 22.04，24.04（建议 24.04 及以上）	CPU：2 核，内存：4 G，硬盘：40 G
CentOS 9 及以上	CPU：2 核，内存：4 G，硬盘：40 G
麒麟 Kylin V10	CPU：2 核，内存：4 G，硬盘：40 G
openEuler 22.03 LTS 及以上	CPU：2 核，内存：4 G，硬盘：40 G

备注

KubeKey 使用 /var/lib/containerd 作为默认路径来存储所有容器相关文件（包括镜像）。建议您添加附加存储卷，分别给 /var/lib/containerd 和 /mnt/registry 挂载至少 100G。

步骤 1：获取 KubeKey

KubeKey 已包含在 Kube AI Hub 离线安装包中。解压离线包后，根据您的架构选择对应的二进制文件：

# x86_64 架构
mv kk-x86 kk

# ARM64 架构
mv kk-arm kk

chmod +x kk

备注

离线安装包请从交付渠道获取。包内已包含 Kubernetes v1.34.4、containerd 及所需镜像。

步骤 2：准备安装镜像

当您在 Linux 上安装 Kube AI Hub 和 Kubernetes 时，需要准备一个包含所有必需镜像的镜像包，并事先下载 Kubernetes 二进制文件。

从交付渠道获取镜像清单文件 images-list.txt。

备注

该文件根据不同的模块列出了 ##+modulename 下的镜像。您可以按照相同的规则把自己的镜像添加到这个文件中。
从交付渠道获取 offline-installation-tool.sh。
使 .sh 文件可执行。
```
chmod +x offline-installation-tool.sh
```

您可以执行命令 ./offline-installation-tool.sh -h 来查看如何使用脚本：

Usage:

  ./offline-installation-tool.sh [-l IMAGES-LIST] [-d IMAGES-DIR] [-r PRIVATE-REGISTRY] [-v KUBERNETES-VERSION ]

Description:
  -b                     : save kubernetes' binaries.
  -d IMAGES-DIR          : the dir of files (tar.gz) which generated by `docker save`. default: ./kubesphere-images
  -l IMAGES-LIST         : text file with list of images.
  -r PRIVATE-REGISTRY    : target private registry:port.
  -s                     : save model will be applied. Pull the images in the IMAGES-LIST and save images as a tar.gz file.
  -v KUBERNETES-VERSION  : download kubernetes' binaries. default: v1.34.4
  -h                     : usage message

下载 Kubernetes 二进制文件。
```
./offline-installation-tool.sh -b -v v1.34.4
```
备注
- 您可以根据自己的需求变更下载的 Kubernetes 版本。安装 Kube AI Hub 3.4 的建议 Kubernetes 版本：v1.28.x、v1.29.x、v1.30.x、v1.31.x、v1.32.x、v1.33.x 和 v1.34.x（建议 v1.34.x）。如果不指定 Kubernetes 版本，KubeKey 将默认安装 Kubernetes v1.34.4。有关受支持的 Kubernetes 版本的更多信息，请参见支持矩阵。
- 运行脚本后，会自动创建一个文件夹 kubekey。请注意，您稍后创建集群时，该文件和 kk 必须放在同一个目录下。
在 offline-installation-tool.sh 中拉取镜像。
```
./offline-installation-tool.sh -s -l images-list.txt -d ./kubesphere-images
```
备注

您可以根据需要选择拉取的镜像。例如，如果已有一个 Kubernetes 集群，您可以在 images-list.txt 中删除 ##k8s-images 和在它下面的相关镜像。

步骤 3：推送镜像至私有仓库

将打包的镜像文件传输至您的本地机器，并运行以下命令把它推送至仓库。

./offline-installation-tool.sh -l images-list.txt -d ./kubesphere-images -r <registry>

备注

命令中的 <registry> 是您的镜像仓库地址。请确保使用您自己仓库的地址。

离线升级 All-in-One 集群

示例机器

主机名称	IP	角色	端口	URL
master	192.168.1.1	镜像仓库	5000	http://192.168.1.1:5000
master	192.168.1.1	master、etcd、worker

版本

	Kubernetes	Kube AI Hub
升级前	v1.28.x	v3.3.x
升级后	v1.34.4	v3.4.x

升级集群

本示例中，Kube AI Hub 安装在单个节点上，您需要指定一个配置文件以添加主机信息。此外，离线安装时，请务必将 .spec.registry.privateRegistry 设置为您自己的仓库地址。有关更多信息，请参见下面的内容。

创建示例配置文件

执行以下命令生成示例配置文件用于安装：

./kk create config [--with-kubernetes version] [--with-kubesphere version] [(-f | --file) path]

例如：

./kk create config --with-kubernetes v1.34.4 --with-kubesphere v3.4.1 -f config-sample.yaml

备注

请确保 Kubernetes 版本和您下载的版本一致。

编辑配置文件

编辑该配置文件 config-sample.yaml。

警告

离线安装时，您必须指定 privateRegistry，在本示例中是 <registry>。

设置 config-sample.yaml 文件中的 hosts：

  hosts:
  - {name: ks.master, address: 192.168.1.1, internalAddress: 192.168.1.1, user: root, password: <password>}
  roleGroups:
    etcd:
    - ks.master
    control-plane:
    - ks.master
    worker:
    - ks.master

设置 config-sample.yaml 文件中的 privateRegistry：

  registry:
    registryMirrors: []
    insecureRegistries: []
    privateRegistry: <registry>

将单节点集群升级至 Kube AI Hub 3.4 和 Kubernetes v1.34.4

./kk upgrade -f config-sample.yaml

要将 Kubernetes 升级至特定版本，可以在 --with-kubernetes 标志后明确指定版本号。以下是可用版本：v1.28.x、v1.29.x、v1.30.x、v1.31.x、v1.32.x、v1.33.x 和 v1.34.x（建议 v1.34.x）。

离线升级多节点集群