- 升级指南

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

• rancher
• rancher中文
• rancher中文文档
• rancher官网
• rancher文档
• Rancher
• rancher 中文
• rancher 中文文档
• rancher cn
• 安装指南
• 升级指南

概述

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

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

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

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

前提条件

访问 kubeconfig 的权限

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

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

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

已知问题

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

在GitHub和Rancher 论坛上的发布说明中，可以找到每个 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.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 工具提供服务。

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

选项 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 论坛上找到。

使用 RKE Add-on 安装 Rancher

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

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

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