升级指南

概述

以下说明将指导您升级使用 Helm 安装在 Kubernetes 集群上的 Rancher 服务器。这些步骤也适用于使用 Helm 进行的离线安装。

有关使用 RancherD 升级安装在 Kubernetes 上的 Rancher 的说明,请参考本页

关于安装了 Docker 的 Rancher 的升级说明,请参考本页

要升级 Kubernetes 集群中的组件,或者定义Kubernetes 服务附加组件。参考 Rancher Kubernetes 引擎的RKE 的升级文档

如果你使用 RKE 附加组件 yaml 安装了 Rancher,请按照迁移或升级的指示进行。

前提条件

访问 kubeconfig 的权限

Helm 应该从与你的 kubeconfig 文件相同的位置运行,或者从你运行 kubectl 命令的相同位置运行。

如果你在安装 Kubernetes 时使用了 RKE,那么配置将在你运行rke up的目录下创建。

kubeconfig 也可以通过--kubeconfig标签来手动针对预定的集群,详情请参考Heml 官方文档

已知问题

查看 Rancher 文档中的已知升级问题,了解升级 Rancher 时需要注意的问题。

GitHubRancher 论坛上的发布说明中,可以找到每个 Rancher 版本的更完整的已知问题列表。

请注意,不支持升级到rancher-alpha 仓库中的任何 chart。

Helm 版本

本文基于 Helm 3 写作。如果您使用的是 Helm2,在按照本文进行升级之前,请先将 Helm 2 升级为 Helm 3。Helm 升级的具体操作步骤请参考Helm 官方文档-从 Helm 2 迁移到 Helm 3

如果您希望保留 Helm2,我们也提供了基于 Helm2 升级的操作指导,详情请参考Helm 2 升级指南

同步镜像到私有镜像仓库

这个前提条件只适用于离线高可用安装。同步镜像到私有镜像仓库之后,在安装 Rancher 时,Rancher 可以从此私有镜像仓库中拉取所需的镜像。详情请参考同步镜像到私有镜像仓库

升级 Rancher Server 并使用隐藏的本地集群

如果您从使用 Helm chart 选项--add-local=false启动的 Rancher 服务器升级到 Rancher v2.5,您需要在升级时取消该标志。否则,Rancher 服务器将无法启动。restricted-admin角色可以用来继续限制对本地集群的访问。有关更多信息,请参见本节

使用外部的 TLS 终端代理从 v2.0-v2.2 升级到 v2.3+

如果您将 Rancher 从 v2.x 升级到 v2.3+,并且您正在使用外部 TLS 终端,您需要编辑cluster.yml启用使用转发主机头

使用 cert-manager v0.8.0 之前的版本升级

从 2019 年 11 月 1 日开始,Let's Encrypt 将屏蔽大于 0.8.0 的 cert-manager 实例,请按照这些说明将 cert-manager 升级到最新版本。

升级大纲

请参考以下四个步骤升级 Rancher Server。

步骤 1:备份正在运行 Rancher Server 的 Kubernetes 集群

对于 Rancher v2.5+,使用备份应用程序来备份 Rancher。

对于 Rancher v2.0-v2.4,使用一次性快照进行备份。 运行 Rancher 服务器的 Kubernetes 集群的备份。

如果在升级过程中出现问题,您将使用备份作为恢复点。

步骤 2:升级 Helm Chart repository

  1. 更新你的本地 heml 缓存。

    helm repo update
  2. 获取你用来安装 Rancher 的仓库名称。

    关于资源库及其区别,请参见Helm Chart Repositories

    helm repo list
    NAME URL
    stable https://charts.helm.sh/stable
    rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>

    注意:如果你想切换到不同的 Helm chart 仓库,请按照如何切换仓库的步骤。如果你切换了资源库,请确保在继续步骤 3 之前再次列出资源库,以确保你添加的资源库是正确的。

  3. 从 Helm chart 库中获取最新的 chart 来安装 Rancher。

    该命令将提取最新的 chart,并将其作为.tgz文件保存在当前目录中。

    helm fetch rancher-<CHART_REPO>/rancher

    你可以通过添加---version=标签来获取你要升级到的特定版本的 chart。例如,你可以通过添加---version=标签来获取你升级到的特定版本的 chart。

    helm fetch rancher-<CHART_REPO>/rancher --version=v2.4.11

升级 Rancher

本节介绍了如何使用 Helm 升级 Rancher 的普通(互联网连接)或离线安装。

升级 Kubernetes

从当前安装的 Rancher Helm chart 中获取用--set传递的值。

helm get values rancher -n cattle-system
hostname: rancher.my.org

注意:这个命令会列出更多的值。这只是其中一个值的例子。 如果您也要将 cert-manager 从 0.11.0 以前的版本升级到最新版本,请按照选项 B:重装 Rancher 和 cert-manager进行操作。

否则,按照【选项 A:升级 Rancher。】(#选项-a-升级 Rancher)

选项 1:升级 Rancher

将 Rancher 升级到最新版本,并进行所有设置。

将上一步中的所有值用--set key=value追加到命令中。

helm upgrade rancher rancher-<CHART_REPO>/rancher \
--namespace cattle-system \
--set hostname=rancher.my.org

注意:以上是一个例子,可能有更多上一步的值需要追加。 另外,也可以将当前的值导出到一个文件中,并在升级时引用该文件。例如,只改变 Rancher 的版本。

helm get values rancher -n cattle-system -o yaml > values.yaml
helm upgrade rancher rancher-<CHART_REPO>/rancher \
--namespace cattle-system \
-f values.yaml \
--version=2.4.5
选项 2:卸载并重新安装 Rancher 和 cert-manager

如果你目前正在运行版本比 v0.11 更老的 cert-manager,并且想把 Rancher 和 cert-manager 都升级到较新的版本,那么你需要重新安装 Rancher 和 cert-manager,因为 cert-manager v0.11 的 API 变化。

  1. 卸载 Rancher

    helm delete rancher -n cattle-system
  2. 按照升级 Cert-Manager页面的说明,卸载并重新安装 cert-manager。

  3. 重新安装 Rancher 到最新版本,并进行所有设置。将步骤 1 中的所有值用--set key=value追加到命令中。注意:步骤 1 中还有很多选项需要追加。

    helm install rancher rancher-<CHART_REPO>/rancher \
    --namespace cattle-system \
    --set hostname=rancher.my.org

离线升级

使用安装 Rancher 时选择的相同选项来渲染 Rancher 模板。使用下面的参考表来替换每个占位符。Rancher 需要配置为使用私有注册表,以便为任何 Rancher 启动的 Kubernetes 集群或 Rancher 工具提供服务。

根据您在安装过程中做出的选择,完成以下程序之一。

占位符说明
<VERSION>输出压缩包的版本号。
<RANCHER.YOURDOMAIN.COM>指向负载均衡器的 DNS 名称。
<REGISTRY.YOURDOMAIN.COM:PORT>您的私有镜像仓库的 DNS 名称。
<CERTMANAGER_VERSION>在 k8s 集群上运行的 Cert-manager 版本。
选项 1:使用默认的自签名证书
helm template ./rancher-<VERSION>.tgz --output-dir . \
--name rancher \
--namespace cattle-system \
--set hostname=<RANCHER.YOURDOMAIN.COM> \
--set certmanager.version=<CERTMANAGER_VERSION> \
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
选项 2:使用 Kubernetes Secrets 从文件中获取证书
helm template ./rancher-<VERSION>.tgz --output-dir . \
--name rancher \
--namespace cattle-system \
--set hostname=<RANCHER.YOURDOMAIN.COM> \
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
--set ingress.tls.source=secret \
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts

如果你使用的是私人 CA 签名的证书,请在--set ingress.tls.source=secret后面添加--set privateCA=true

helm template ./rancher-<VERSION>.tgz --output-dir . \
--name rancher \
--namespace cattle-system \
--set hostname=<RANCHER.YOURDOMAIN.COM> \
--set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
--set ingress.tls.source=secret \
--set privateCA=true \
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts

步骤 3:应用渲染的模板

将渲染的清单目录复制到可以访问 Rancher 服务器集群的系统中,并应用渲染的模板。

使用 "kubectl "应用渲染的清单。

kubectl -n cattle-system apply -R -f ./rancher

步骤 4:验证升级是否成功

登录 Rancher,确认升级成功。

如果升级之后出现了网络问题,请参考恢复集群网络

已知问题

下表列出了升级 Rancher 时需要考虑的一些最值得注意的问题。每个 Rancher 版本的已知问题的更完整列表可以在GitHub上的发布说明和Rancher 论坛上找到。

升级场景问题描述
升级到 v2.4.6 或 v2.4.7这些 Rancher 版本存在一个问题,即创建、编辑或克隆 Amazon EC2 节点模板需要kms:ListKeys权限。这一要求在 v2.4.8 中被删除。建议跳过 v2.4.6 或 v2.4.7,直接升级到 v2.4.8+。
升级到 v2.3.0+任何用户供应的集群将在任何编辑后自动更新,因为容忍被添加到用于 Kubernetes 供应的图像中。
升级到 v2.2.0-v2.2.xRancher 引入了system charts存储库,其中包含监控、日志、警报和全局 DNS 等功能所需的所有目录项。为了能够在 air gap 安装中使用这些功能,您需要在本地镜像system-charts资源库,并配置 Rancher 使用该资源库。请按照说明配置 Rancher 系统 chart
从 v2.0.13 或更早的版本进行升级如果你的集群的证书已经过期,你需要执行这些步骤来轮换证书。
从 v2.0.7 或更早的版本进行升级Rancher 引入了system项目,这是一个自动创建的项目,用于存储 Kubernetes 运行所需的重要命名空间。在升级到 v2.0.7+的过程中,Rancher 希望这些命名空间能够从所有项目中取消分配。在开始升级之前,请检查您的系统命名空间,确保它们未被分配,以防止集群网络问题。

使用 RKE Add-on 安装 Rancher

重要:RKE 插件安装只支持到 Rancher v2.0.8

请使用 Rancher Helm Chart 在 Kubernetes 集群上安装 Rancher。详情请参见Kubernetes 安装

如果您当前使用的是 RKE 加载方式,请参见 从 RKE add-on 迁移,了解如何迁移到使用 Helm Chart 的详细信息。

最后由 yzeng25更新 于