使用 KubeKey 离线升级

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

准备工作

  • 您需要有一个运行 KubeSphere v3.2.x 的集群。如果您的 KubeSphere 是 v3.1.0 或更早的版本,请先升级至 v3.2.x。
  • 您的 Kubernetes 版本必须为 1.20.x、1.21.x、1.22.x,1.23.x 或 1.24.x。
  • 请仔细阅读 3.4.0 版本说明
  • 提前备份所有重要的组件。
  • Docker 仓库。您需要有一个 Harbor 或其他 Docker 仓库。
  • 请确保每个节点都可以从该 Docker 仓库拉取镜像或向其推送镜像。

重要提示

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

  • 内置角色调整:移除了平台级内置角色 users-manager(用户管理员)和 workspace-manager(企业空间管理员),如果已有用户绑定了 users-managerworkspace-manager,他们的角色将会在升级之后变更为 platform-regular。增加了平台级内置角色 platform-self-provisioner。关于平台角色的具体描述,请参见创建用户

  • 自定义角色授权项调整:

    • 移除平台层级自定义角色授权项:用户管理,角色管理,企业空间管理。
    • 移除企业空间层级自定义角色授权项:成员管理,角色管理,用户组管理。
    • 移除命名空间层级自定义角色授权项:成员管理,角色管理。
    • 升级到 KubeSphere 3.4 后,自定义角色会被保留,但是其包含的已被移除的授权项会被删除。

升级 KubeSphere 和 Kubernetes

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

信息

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

系统要求

系统最低要求(每个节点)
Ubuntu 16.04, 18.04,20.04CPU:2 核,内存:4 G,硬盘:40 G
Debian Buster, StretchCPU:2 核,内存:4 G,硬盘:40 G
CentOS 7.xCPU:2 核,内存:4 G,硬盘:40 G
Red Hat Enterprise Linux 7CPU:2 核,内存:4 G,硬盘:40 G
SUSE Linux Enterprise Server 15 /openSUSE Leap 15.2CPU:2 核,内存:4 G,硬盘:40 G

备注

KubeKey 使用 /var/lib/docker 作为默认路径来存储所有 Docker 相关文件(包括镜像)。建议您添加附加存储卷,分别给 /var/lib/docker/mnt/registry 挂载至少 100G。请参见 fdisk 的参考命令。

步骤 1:下载 KubeKey

  1. 执行以下命令下载 KubeKey 并解压:

    GitHub Release Page 下载 KubeKey 或者直接运行以下命令。

    1. curl -sfL https://get-kk.kubesphere.io | VERSION=v3.0.7 sh -

    首先运行以下命令,以确保您从正确的区域下载 KubeKey。

    1. export KKZONE=cn

    运行以下命令来下载 KubeKey:

    1. curl -sfL https://get-kk.kubesphere.io | VERSION=v3.0.7 sh -
  2. 解压文件后,执行以下命令,使 kk 可执行:

    1. chmod +x kk

步骤 2:准备安装镜像

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

  1. 使用以下命令从能够访问互联网的机器上下载镜像清单文件 images-list.txt

    1. curl -L -O https://github.com/kubesphere/ks-installer/releases/download/v3.4.0/images-list.txt

    备注

    该文件根据不同的模块列出了 ##+modulename 下的镜像。您可以按照相同的规则把自己的镜像添加到这个文件中。

  2. 下载 offline-installation-tool.sh

    1. curl -L -O https://github.com/kubesphere/ks-installer/releases/download/v3.4.0/offline-installation-tool.sh
  3. 使 .sh 文件可执行。

    1. chmod +x offline-installation-tool.sh
  4. 您可以执行命令 ./offline-installation-tool.sh -h 来查看如何使用脚本:

    1. root@master:/home/ubuntu# ./offline-installation-tool.sh -h
    2. Usage:
    3. ./offline-installation-tool.sh [-l IMAGES-LIST] [-d IMAGES-DIR] [-r PRIVATE-REGISTRY] [-v KUBERNETES-VERSION ]
    4. Description:
    5. -b : save kubernetes' binaries.
    6. -d IMAGES-DIR : the dir of files (tar.gz) which generated by `docker save`. default: /home/ubuntu/kubesphere-images
    7. -l IMAGES-LIST : text file with list of images.
    8. -r PRIVATE-REGISTRY : target private registry:port.
    9. -s : save model will be applied. Pull the images in the IMAGES-LIST and save images as a tar.gz file.
    10. -v KUBERNETES-VERSION : download kubernetes' binaries. default: v1.17.9
    11. -h : usage message
  5. 下载 Kubernetes 二进制文件。

    1. ./offline-installation-tool.sh -b -v v1.22.12

    如果您无法访问 Google 的对象存储服务,请运行以下命令添加环境变量以变更来源。

    1. export KKZONE=cn;./offline-installation-tool.sh -b -v v1.22.12

    备注

    • 您可以根据自己的需求变更下载的 Kubernetes 版本。安装 KubeSphere 3.4 的建议 Kubernetes 版本:v1.20.x、v1.21.x、* v1.22.x、* v1.23.x、* v1.24.x、* v1.25.x 和 * v1.26.x。带星号的版本可能出现边缘节点部分功能不可用的情况。因此,如需使用边缘节点,推荐安装 v1.21.x。如果不指定 Kubernetes 版本,KubeKey 将默认安装 Kubernetes v1.23.10。有关受支持的 Kubernetes 版本的更多信息,请参见支持矩阵

    • 运行脚本后,会自动创建一个文件夹 kubekey。请注意,您稍后创建集群时,该文件和 kk 必须放在同一个目录下。

  6. offline-installation-tool.sh 中拉取镜像。

    1. ./offline-installation-tool.sh -s -l images-list.txt -d ./kubesphere-images

    备注

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

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

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

  1. ./offline-installation-tool.sh -l images-list.txt -d ./kubesphere-images -r dockerhub.kubekey.local

备注

命令中的域名是 dockerhub.kubekey.local。请确保使用您自己仓库的地址

离线升级 All-in-One 集群

示例机器

主机名称IP角色端口URL
master192.168.1.1Docker 仓库5000http://192.168.1.1:5000
master192.168.1.1master、etcd、worker

版本

KubernetesKubeSphere
升级前v1.18.6v3.2.x
升级后v1.22.12v3.3

升级集群

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

创建示例配置文件

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

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

例如:

  1. ./kk create config --with-kubernetes v1.22.12 --with-kubesphere v3.4.0 -f config-sample.yaml

备注

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

编辑配置文件

编辑该配置文件 config-sample.yaml。请查看供您参考的示例

警告

离线安装时,您必须指定 privateRegistry,在本示例中是 dockerhub.kubekey.local

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

  1. hosts:
  2. - {name: ks.master, address: 192.168.1.1, internalAddress: 192.168.1.1, user: root, password: Qcloud@123}
  3. roleGroups:
  4. etcd:
  5. - ks.master
  6. control-plane:
  7. - ks.master
  8. worker:
  9. - ks.master

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

  1. registry:
  2. registryMirrors: []
  3. insecureRegistries: []
  4. privateRegistry: dockerhub.kubekey.local

将单节点集群升级至 KubeSphere 3.4 和 Kubernetes v1.22.12

  1. ./kk upgrade -f config-sample.yaml

要将 Kubernetes 升级至特定版本,可以在 --with-kubernetes 标志后明确指定版本号。以下是可用版本:v1.20.x、v1.21.x、* v1.22.x、* v1.23.x、* v1.24.x、* v1.25.x 和 * v1.26.x。带星号的版本可能出现边缘节点部分功能不可用的情况。因此,如需使用边缘节点,推荐安装 v1.21.x。

离线升级多节点集群

示例机器

主机名称IP角色端口URL
master192.168.1.1Docker 仓库5000http://192.168.1.1:5000
master192.168.1.1master、etcd
slave1192.168.1.2worker
slave1192.168.1.3worker

版本

KubernetesKubeSphere
升级前v1.18.6v3.2.x
升级后v1.22.12v3.3.x

升级集群

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

创建示例配置文件

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

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

例如:

  1. ./kk create config --with-kubernetes v1.22.12 --with-kubesphere v3.4.0 -f config-sample.yaml

备注

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

编辑配置文件

编辑该配置文件 config-sample.yaml。请查看供您参考的示例

警告

离线安装时,您必须指定 privateRegistry,在本示例中是 dockerhub.kubekey.local

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

  1. hosts:
  2. - {name: ks.master, address: 192.168.1.1, internalAddress: 192.168.1.1, user: root, password: Qcloud@123}
  3. - {name: ks.slave1, address: 192.168.1.2, internalAddress: 192.168.1.2, user: root, privateKeyPath: "/root/.ssh/kp-qingcloud"}
  4. - {name: ks.slave2, address: 192.168.1.3, internalAddress: 192.168.1.3, user: root, privateKeyPath: "/root/.ssh/kp-qingcloud"}
  5. roleGroups:
  6. etcd:
  7. - ks.master
  8. control-plane:
  9. - ks.master
  10. worker:
  11. - ks.slave1
  12. - ks.slave2

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

  1. registry:
  2. registryMirrors: []
  3. insecureRegistries: []
  4. privateRegistry: dockerhub.kubekey.local

将多节点集群升级至 KubeSphere 3.4 和 Kubernetes v1.22.12

  1. ./kk upgrade -f config-sample.yaml

要将 Kubernetes 升级至特定版本,可以在 --with-kubernetes 标志后明确指定版本号。以下是可用版本:v1.20.x、v1.21.x、* v1.22.x、* v1.23.x、* v1.24.x、* v1.25.x 和 * v1.26.x。带星号的版本可能出现边缘节点部分功能不可用的情况。因此,如需使用边缘节点,推荐安装 v1.21.x。