使用 ks-installer 离线升级

对于 Kubernetes 集群不是通过 KubeKey 部署而是由云厂商托管或自行部署的用户，推荐使用 ks-installer。本教程只用于升级 KubeSphere。集群运维员应负责提前升级 Kubernetes。

准备工作

  • 您需要有一个运行 KubeSphere v3.2.x 的集群。如果您的 KubeSphere 是 v3.1.0 或更早的版本，请先升级至 v3.2.x。
  • 请仔细阅读 3.4.0 版本说明。
  • 提前备份所有重要的组件。
  • Docker 仓库。您需要有一个 Harbor 或其他 Docker 仓库。有关更多信息，请参见准备一个私有镜像仓库。
  • 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。

重要提示

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

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

步骤 1：准备安装镜像

当您在离线环境中安装 KubeSphere 时，需要事先准备一个包含所有必需镜像的镜像包。

  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:
    4.   ./offline-installation-tool.sh [-l IMAGES-LIST] [-d IMAGES-DIR] [-r PRIVATE-REGISTRY] [-v KUBERNETES-VERSION ]
    6. Description:
    7.   -b                     : save kubernetes' binaries.
    8.   -d IMAGES-DIR          : the dir of files (tar.gz) which generated by `docker save`. default: ./kubesphere-images
    9.   -l IMAGES-LIST         : text file with list of images.
    10.   -r PRIVATE-REGISTRY    : target private registry:port.
    11.   -s                     : save model will be applied. Pull the images in the IMAGES-LIST and save images as a tar.gz file.
    12.   -v KUBERNETES-VERSION  : download kubernetes' binaries. default: v1.17.9
    13.   -h                     : usage message

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

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

    备注

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

步骤 2：推送镜像至您的私有仓库

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

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

备注

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

步骤 3：下载 ks-installer

与在现有 Kubernetes 集群上在线安装 KubeSphere 相似，您需要事先下载 kubesphere-installer.yaml。

  1. 执行以下命令下载 ks-installer，并将其传输至您充当任务机的机器，用于安装。

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

  2. 验证您已在 cluster-configuration.yaml 中的 spec.local_registry 字段指定了私有镜像仓库地址。请注意，如果您的已有集群通过离线安装方式搭建，您应该已配置了此地址。如果您的集群采用在线安装方式搭建而需要进行离线升级，执行以下命令编辑您已有 KubeSphere 3.4 集群的 cluster-configuration.yaml 文件，并添加私有镜像仓库地址：

    1. kubectl edit cc -n kubesphere-system

    例如，本教程中的仓库地址是 dockerhub.kubekey.local，将它用作 .spec.local_registry 的值，如下所示：

    1. spec:
    2.   persistence:
    3.     storageClass: ""
    4.   authentication:
    5.     jwtSecret: ""
    6.   local_registry: dockerhub.kubekey.local # Add this line manually; make sure you use your own registry address.

  3. 编辑完成后保存 cluster-configuration.yaml。使用以下命令将 ks-installer 替换为您自己仓库的地址。

    1. sed -i "s#^\s*image: kubesphere.*/ks-installer:.*#        image: dockerhub.kubekey.local/kubesphere/ks-installer:v3.4.0#" kubesphere-installer.yaml

    警告

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

步骤 4：升级 KubeSphere

确保上述所有步骤都已完成后，执行以下命令。

  1. kubectl apply -f kubesphere-installer.yaml

步骤 5：验证安装

安装完成后，您会看到以下内容：

  1. #####################################################
  2. ###              Welcome to KubeSphere!           ###
  3. #####################################################
  5. Console: http://192.168.0.2:30880
  6. Account: admin
  7. Password: P@88w0rd
  9. NOTES：
  10.   1. After you log into the console, please check the
  11.      monitoring status of service components in
  12.      the "Cluster Management". If any service is not
  13.      ready, please wait patiently until all components
  14.      are up and running.
  15.   2. Please change the default password after login.
  17. #####################################################
  18. https://kubesphere.io             20xx-xx-xx xx:xx:xx
  19. #####################################################

现在，您可以通过 http://{IP}:30880 使用默认帐户和密码 admin/P@88w0rd 访问 KubeSphere 的 Web 控制台。

备注

要访问控制台，请确保在您的安全组中打开端口 30880。