--- title: "使用 KubeKey 离线升级" keywords: "离线环境, kubernetes, 升级, kubesphere, 3.3" description: "使用离线包升级 Kubernetes 和 KubeSphere。" linkTitle: "使用 KubeKey 离线升级" weight: 7400 --- 对于 KubeSphere 和 Kubernetes 都是通过 [KubeKey](../../installing-on-linux/introduction/kubekey/) 部署的用户，推荐使用 KubeKey 离线升级。如果您的 Kubernetes 集群由云厂商托管或自行配置，请参考[使用 ks-installer 离线升级](../air-gapped-upgrade-with-ks-installer/)。 ## 准备工作 - 您需要有一个运行 KubeSphere v3.2.x 的集群。如果您的 KubeSphere 是 v3.1.0 或更早的版本，请先升级至 v3.2.x。 - 您的 Kubernetes 版本必须为 v1.19.x及以上版本。 - 请仔细阅读 [3.3.1 版本说明](../../../v3.3/release/release-v331/)。 - 提前备份所有重要的组件。 - Docker 仓库。您需要有一个 Harbor 或其他 Docker 仓库。 - 请确保每个节点都可以从该 Docker 仓库拉取镜像或向其推送镜像。 ## 重要提示 KubeSphere 3.3.1 对内置角色和自定义角色的授权项做了一些调整。在您升级到 KubeSphere 3.3.1时，请注意以下几点： - 内置角色调整：移除了平台级内置角色 `users-manager`(用户管理员)和 `workspace-manager`（企业空间管理员），如果已有用户绑定了 `users-manager` 或 `workspace-manager`，他们的角色将会在升级之后变更为 `platform-regular`。增加了平台级内置角色 `platform-self-provisioner`。关于平台角色的具体描述，请参见[创建用户](../../quick-start/create-workspace-and-project/#创建用户)。 - 自定义角色授权项调整： - 移除平台层级自定义角色授权项：用户管理，角色管理，企业空间管理。 - 移除企业空间层级自定义角色授权项：成员管理，角色管理，用户组管理。 - 移除命名空间层级自定义角色授权项：成员管理，角色管理。 - 升级到 KubeSphere 3.3.1 后，自定义角色会被保留，但是其包含的已被移除的授权项会被删除。 ## 升级 KubeSphere 和 Kubernetes 单节点集群 (All-in-One) 和多节点集群的升级步骤不同。 {{< notice info >}} 当升级 Kubernetes 时，KubeKey 将从一个小版本升级到下一个小版本，直到目标版本。例如，您会发现升级过程是从 1.16 先升级到 1.17 然后再升级到 1.18，而不是直接从 1.16 升级到 1.18。 {{}} ### 系统要求 | 系统 | 最低要求（每个节点） | | ------------------------------------------------------------ | -------------------------------- | | **Ubuntu** *16.04, 18.04，20.04* | CPU：2 核，内存：4 G，硬盘：40 G | | **Debian** *Buster, Stretch* | CPU：2 核，内存：4 G，硬盘：40 G | | **CentOS** *7.x* | CPU：2 核，内存：4 G，硬盘：40 G | | **Red Hat Enterprise Linux** *7* | CPU：2 核，内存：4 G，硬盘：40 G | | **SUSE Linux Enterprise Server** *15* **/openSUSE Leap** *15.2* | CPU：2 核，内存：4 G，硬盘：40 G | {{< notice note >}} [KubeKey](https://github.com/kubesphere/kubekey) 使用 `/var/lib/docker` 作为默认路径来存储所有 Docker 相关文件（包括镜像）。建议您添加附加存储卷，分别给 `/var/lib/docker` 和 `/mnt/registry` 挂载至少 **100G**。请参见 [fdisk](https://www.computerhope.com/unix/fdisk.htm) 的参考命令。 {{}} ### 步骤 1：下载 KubeKey 1. 执行以下命令下载 KubeKey v2.3.0 并解压： {{< tabs >}} {{< tab "如果您能正常访问 GitHub/Googleapis" >}} 从 [GitHub Release Page](https://github.com/kubesphere/kubekey/releases) 下载 KubeKey 或者直接运行以下命令。 ```bash curl -sfL https://get-kk.kubesphere.io | VERSION=v2.3.0 sh - ``` {{}} {{< tab "如果您访问 GitHub/Googleapis 受限" >}} 首先运行以下命令，以确保您从正确的区域下载 KubeKey。 ```bash export KKZONE=cn ``` 运行以下命令来下载 KubeKey： ```bash curl -sfL https://get-kk.kubesphere.io | VERSION=v2.3.0 sh - ``` {{}} {{}} 2. 解压文件后，执行以下命令，使 `kk` 可执行： ```bash chmod +x kk ``` ### 步骤 2：准备安装镜像 当您在 Linux 上安装 KubeSphere 和 Kubernetes 时，需要准备一个包含所有必需镜像的镜像包，并事先下载 Kubernetes 二进制文件。 1. 使用以下命令从能够访问互联网的机器上下载镜像清单文件 `images-list.txt`： ```bash curl -L -O https://github.com/kubesphere/ks-installer/releases/download/v3.3.1/images-list.txt ``` {{< notice note >}} 该文件根据不同的模块列出了 `##+modulename` 下的镜像。您可以按照相同的规则把自己的镜像添加到这个文件中。 {{}} 2. 下载 `offline-installation-tool.sh`。 ```bash curl -L -O https://github.com/kubesphere/ks-installer/releases/download/v3.3.1/offline-installation-tool.sh ``` 3. 使 `.sh` 文件可执行。 ```bash chmod +x offline-installation-tool.sh ``` 4. 您可以执行命令 `./offline-installation-tool.sh -h` 来查看如何使用脚本： ```bash root@master:/home/ubuntu# ./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: /home/ubuntu/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.17.9 -h : usage message ``` 5. 下载 Kubernetes 二进制文件。 ```bash ./offline-installation-tool.sh -b -v v1.22.10 ``` 如果您无法访问 Google 的对象存储服务，请运行以下命令添加环境变量以变更来源。 ```bash export KKZONE=cn;./offline-installation-tool.sh -b -v v1.22.10 ``` {{< notice note >}} - 您可以根据自己的需求变更下载的 Kubernetes 版本。安装 KubeSphere 3.3 的建议 Kubernetes 版本：v1.19.x、v1.20.x、v1.21.x、v1.22.x（实验性支持）和v1.23.x（实验性支持）。如果不指定 Kubernetes 版本，KubeKey 将默认安装 Kubernetes v1.23.7。有关受支持的 Kubernetes 版本的更多信息，请参见[支持矩阵](../../installing-on-linux/introduction/kubekey/#支持矩阵)。 - 您可以通过下载 Kubernetes v1.17.9 二进制文件将 Kubernetes 从 v1.16.13 升级到 v1.17.9。但对于跨多个版本升级，需要事先下载所有中间版本，例如您想将 Kubernetes 从 v1.15.12 升级到 v1.18.6，则需要下载 Kubernetes v1.16.13、v1.17.9 和 v1.18.6 二进制文件。 - 运行脚本后，会自动创建一个文件夹 `kubekey`。请注意，您稍后创建集群时，该文件和 `kk` 必须放在同一个目录下。 {{}} 6. 在 `offline-installation-tool.sh` 中拉取镜像。 ```bash ./offline-installation-tool.sh -s -l images-list.txt -d ./kubesphere-images ``` {{< notice note >}} 您可以根据需要选择拉取的镜像。例如，如果已有一个 Kubernetes 集群，您可以在 `images-list.text` 中删除 `##k8s-images` 和在它下面的相关镜像。 {{}} ### 步骤 3：推送镜像至私有仓库 将打包的镜像文件传输至您的本地机器，并运行以下命令把它推送至仓库。 ```bash ./offline-installation-tool.sh -l images-list.txt -d ./kubesphere-images -r dockerhub.kubekey.local ``` {{< notice note >}} 命令中的域名是 `dockerhub.kubekey.local`。请确保使用您**自己仓库的地址**。 {{}} ### 离线升级 All-in-One 集群 #### 示例机器 | 主机名称 | IP | 角色 | 端口 | URL | | -------- | ----------- | -------------------- | ---- | ----------------------- | | master | 192.168.1.1 | Docker 仓库 | 5000 | http://192.168.1.1:5000 | | master | 192.168.1.1 | master、etcd、worker | | | #### 版本 | | Kubernetes | KubeSphere | | ------ | ---------- | ---------- | | 升级前 | v1.18.6 | v3.2.x | | 升级后 | v1.22.10 | 3.3 | #### 升级集群 本示例中，KubeSphere 安装在单个节点上，您需要指定一个配置文件以添加主机信息。此外，离线安装时，请务必将 `.spec.registry.privateRegistry` 设置为**您自己的仓库地址**。有关更多信息，请参见下面的内容。 #### 创建示例配置文件 执行以下命令生成示例配置文件用于安装： ```bash ./kk create config [--with-kubernetes version] [--with-kubesphere version] [(-f | --file) path] ``` 例如： ```bash ./kk create config --with-kubernetes v1.22.10 --with-kubesphere v3.3.1 -f config-sample.yaml ``` {{< notice note >}} 请确保 Kubernetes 版本和您下载的版本一致。 {{}} #### 编辑配置文件 编辑该配置文件 `config-sample.yaml`。请查看[供您参考的示例](https://github.com/kubesphere/kubekey/blob/release-2.2/docs/config-example.md)。 {{< notice warning >}} 离线安装时，您必须指定 `privateRegistry`，在本示例中是 `dockerhub.kubekey.local`。 {{}} 设置 `config-sample.yaml` 文件中的 `hosts`： ```yaml hosts: - {name: ks.master, address: 192.168.1.1, internalAddress: 192.168.1.1, user: root, password: Qcloud@123} roleGroups: etcd: - ks.master control-plane: - ks.master worker: - ks.master ``` 设置 `config-sample.yaml` 文件中的 `privateRegistry`： ```yaml registry: registryMirrors: [] insecureRegistries: [] privateRegistry: dockerhub.kubekey.local ``` #### 将单节点集群升级至 KubeSphere 3.3 和 Kubernetes v1.22.10 ```bash ./kk upgrade -f config-sample.yaml ``` 要将 Kubernetes 升级至特定版本，可以在 `--with-kubernetes` 标志后明确指定版本号。以下是可用版本：v1.19.x、v1.20.x、v1.21.x、v1.22.x（实验性支持）和 v1.23.x（实验性支持）。 ### 离线升级多节点集群 #### 示例机器 | 主机名称 | IP | 角色 | 端口 | URL | | -------- | ----------- | ------------ | ---- | ----------------------- | | master | 192.168.1.1 | Docker 仓库 | 5000 | http://192.168.1.1:5000 | | master | 192.168.1.1 | master、etcd | | | | slave1 | 192.168.1.2 | worker | | | | slave1 | 192.168.1.3 | worker | | | #### 版本 | | Kubernetes | KubeSphere | | ------ | ---------- | ---------- | | 升级前 | v1.18.6 | v3.2.x | | 升级后 | v1.22.10 | 3.3 | #### 升级集群 本示例中，KubeSphere 安装在多个节点上，因此您需要指定一个配置文件以添加主机信息。此外，离线安装时，请务必将 `.spec.registry.privateRegistry` 设置为**您自己的仓库地址**。有关更多信息，请参见下面的内容。 #### 创建示例配置文件 执行以下命令生成示例配置文件用于安装： ```bash ./kk create config [--with-kubernetes version] [--with-kubesphere version] [(-f | --file) path] ``` 例如： ```bash ./kk create config --with-kubernetes v1.22.10 --with-kubesphere v3.3.1 -f config-sample.yaml ``` {{< notice note >}} 请确保 Kubernetes 版本和您下载的版本一致。 {{}} #### 编辑配置文件 编辑该配置文件 `config-sample.yaml`。请查看[供您参考的示例](https://github.com/kubesphere/kubekey/blob/release-2.2/docs/config-example.md)。 {{< notice warning >}} 离线安装时，您必须指定 `privateRegistry`，在本示例中是 `dockerhub.kubekey.local`。 {{}} 设置 `config-sample.yaml` 文件中的 `hosts`： ```yaml hosts: - {name: ks.master, address: 192.168.1.1, internalAddress: 192.168.1.1, user: root, password: Qcloud@123} - {name: ks.slave1, address: 192.168.1.2, internalAddress: 192.168.1.2, user: root, privateKeyPath: "/root/.ssh/kp-qingcloud"} - {name: ks.slave2, address: 192.168.1.3, internalAddress: 192.168.1.3, user: root, privateKeyPath: "/root/.ssh/kp-qingcloud"} roleGroups: etcd: - ks.master control-plane: - ks.master worker: - ks.slave1 - ks.slave2 ``` 设置 `config-sample.yaml` 文件中的 `privateRegistry`： ```yaml registry: registryMirrors: [] insecureRegistries: [] privateRegistry: dockerhub.kubekey.local ``` #### 将多节点集群升级至 KubeSphere 3.3 和 Kubernetes v1.22.10 ```bash ./kk upgrade -f config-sample.yaml ``` 要将 Kubernetes 升级至特定版本，可以在 `--with-kubernetes` 标志后明确指定版本号。以下是可用版本：v1.19.x、v1.20.x、v1.21.x、v1.22.x（实验性支持）和 v1.23.x（实验性支持）。