mirror of
https://github.com/kubesphere/website.git
synced 2025-12-26 00:12:48 +00:00
353 lines
13 KiB
Markdown
353 lines
13 KiB
Markdown
---
|
||
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 版本必须为 1.20.x、1.21.x、1.22.x，1.23.x 或 1.24.x。
|
||
- 请仔细阅读 [3.3.2 版本说明](../../../v3.3/release/release-v332/)。
|
||
- 提前备份所有重要的组件。
|
||
- 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。
|
||
|
||
{{</ notice >}}
|
||
|
||
|
||
### 系统要求
|
||
|
||
| 系统 | 最低要求（每个节点） |
|
||
| ------------------------------------------------------------ | -------------------------------- |
|
||
| **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) 的参考命令。
|
||
|
||
{{</ notice >}}
|
||
|
||
|
||
### 步骤 1：下载 KubeKey
|
||
|
||
1. 执行以下命令下载 KubeKey 并解压：
|
||
|
||
{{< tabs >}}
|
||
|
||
{{< tab "如果您能正常访问 GitHub/Googleapis" >}}
|
||
|
||
从 [GitHub Release Page](https://github.com/kubesphere/kubekey/releases) 下载 KubeKey 或者直接运行以下命令。
|
||
|
||
```bash
|
||
curl -sfL https://get-kk.kubesphere.io | VERSION=v3.0.7 sh -
|
||
```
|
||
|
||
{{</ tab >}}
|
||
|
||
{{< tab "如果您访问 GitHub/Googleapis 受限" >}}
|
||
|
||
首先运行以下命令，以确保您从正确的区域下载 KubeKey。
|
||
|
||
```bash
|
||
export KKZONE=cn
|
||
```
|
||
|
||
运行以下命令来下载 KubeKey：
|
||
|
||
```bash
|
||
curl -sfL https://get-kk.kubesphere.io | VERSION=v3.0.7 sh -
|
||
```
|
||
{{</ tab >}}
|
||
|
||
{{</ tabs >}}
|
||
|
||
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.2/images-list.txt
|
||
```
|
||
|
||
{{< notice note >}}
|
||
|
||
该文件根据不同的模块列出了 `##+modulename` 下的镜像。您可以按照相同的规则把自己的镜像添加到这个文件中。
|
||
|
||
{{</ notice >}}
|
||
|
||
2. 下载 `offline-installation-tool.sh`。
|
||
|
||
```bash
|
||
curl -L -O https://github.com/kubesphere/ks-installer/releases/download/v3.3.2/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.12
|
||
```
|
||
|
||
如果您无法访问 Google 的对象存储服务，请运行以下命令添加环境变量以变更来源。
|
||
|
||
```bash
|
||
export KKZONE=cn;./offline-installation-tool.sh -b -v v1.22.12
|
||
```
|
||
|
||
{{< notice note >}}
|
||
|
||
- 您可以根据自己的需求变更下载的 Kubernetes 版本。安装 KubeSphere 3.3 的建议 Kubernetes 版本：v1.20.x、v1.21.x、* v1.22.x、* v1.23.x 和 * v1.24.x。带星号的版本可能出现边缘节点部分功能不可用的情况。因此，如需使用边缘节点，推荐安装 v1.21.x。如果不指定 Kubernetes 版本，KubeKey 将默认安装 Kubernetes v1.23.10。有关受支持的 Kubernetes 版本的更多信息，请参见[支持矩阵](../../installing-on-linux/introduction/kubekey/#支持矩阵)。
|
||
|
||
- 运行脚本后，会自动创建一个文件夹 `kubekey`。请注意，您稍后创建集群时，该文件和 `kk` 必须放在同一个目录下。
|
||
|
||
{{</ notice >}}
|
||
|
||
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` 和在它下面的相关镜像。
|
||
|
||
{{</ notice >}}
|
||
|
||
### 步骤 3：推送镜像至私有仓库
|
||
|
||
将打包的镜像文件传输至您的本地机器，并运行以下命令把它推送至仓库。
|
||
|
||
```bash
|
||
./offline-installation-tool.sh -l images-list.txt -d ./kubesphere-images -r dockerhub.kubekey.local
|
||
```
|
||
|
||
{{< notice note >}}
|
||
|
||
命令中的域名是 `dockerhub.kubekey.local`。请确保使用您**自己仓库的地址**。
|
||
|
||
{{</ notice >}}
|
||
|
||
### 离线升级 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.12 | 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.12 --with-kubesphere v3.3.2 -f config-sample.yaml
|
||
```
|
||
|
||
{{< notice note >}}
|
||
|
||
请确保 Kubernetes 版本和您下载的版本一致。
|
||
|
||
{{</ notice >}}
|
||
|
||
#### 编辑配置文件
|
||
|
||
编辑该配置文件 `config-sample.yaml`。请查看[供您参考的示例](https://github.com/kubesphere/kubekey/blob/release-2.2/docs/config-example.md)。
|
||
|
||
{{< notice warning >}}
|
||
|
||
离线安装时，您必须指定 `privateRegistry`，在本示例中是 `dockerhub.kubekey.local`。
|
||
|
||
{{</ notice >}}
|
||
|
||
设置 `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.12
|
||
|
||
```bash
|
||
./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.21.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.12 | 3.3.x |
|
||
|
||
#### 升级集群
|
||
|
||
本示例中，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.12 --with-kubesphere v3.3.2 -f config-sample.yaml
|
||
```
|
||
|
||
{{< notice note >}}
|
||
|
||
请确保 Kubernetes 版本和您下载的版本一致。
|
||
|
||
{{</ notice >}}
|
||
|
||
#### 编辑配置文件
|
||
|
||
编辑该配置文件 `config-sample.yaml`。请查看[供您参考的示例](https://github.com/kubesphere/kubekey/blob/release-2.2/docs/config-example.md)。
|
||
|
||
{{< notice warning >}}
|
||
|
||
离线安装时，您必须指定 `privateRegistry`，在本示例中是 `dockerhub.kubekey.local`。
|
||
|
||
{{</ notice >}}
|
||
|
||
设置 `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.12
|
||
|
||
```bash
|
||
./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.21.x。
|
||
|