升级 Docker 安装的 Rancher

本文介绍如何升级通过 Docker 安装的 Rancher Server。

警告

生产环境不支持 Docker 安装。这些说明仅适用于测试和开发。如果你已经在生产环境中部署了 Docker 安装并且需要升级到新的 Rancher 版本，我们建议你在升级前先迁移到 Helm Chart 安装。

先决条件

• 在 Rancher 文档中检查已知升级问题，了解升级 Rancher 时最需要注意的问题。你可以在 GitHub 发布说明以及 Rancher 论坛中找到每个 Rancher 版本的已知问题。不支持升级或升级到 rancher-alpha 仓库中的任何 Chart。
• 仅适用于离线安装：为新的 Rancher Server 版本收集和推送镜像。按照指南为你想要升级的目标 Rancher 版本推送镜像到私有镜像仓库。

占位符

在升级过程中，你将输入一系列命令。请按照你环境的实际情况替换占位符。占位符用尖括号和大写字母（如 <EXAMPLE>）表示。

以下是带有占位符的命令示例：

docker stop <RANCHER_CONTAINER_NAME>

在此命令中，<RANCHER_CONTAINER_NAME> 是你的 Rancher 容器的名称。

获取升级命令的数据

要获取替换占位符的数据，请运行：

docker ps

在开始升级之前记下或复制此信息。

^{终端 docker ps 命令，显示如何找到 <RANCHER_CONTAINER_TAG> 和 <RANCHER_CONTAINER_NAME>}

占位符	示例	描述
<RANCHER_CONTAINER_TAG>	v2.1.3	首次安装拉取的 rancher/rancher 镜像。
<RANCHER_CONTAINER_NAME>	festive_mestorf	你的 Rancher 容器的名称。
<RANCHER_VERSION>	v2.1.3	你为其创建备份的 Rancher 版本。
<DATE>	2018-12-19	数据容器或备份的创建日期。

可以通过远程连接登录到 Rancher Server 所在的主机并输入命令 docker ps 以查看正在运行的容器，从而获得 <RANCHER_CONTAINER_TAG> 和 <RANCHER_CONTAINER_NAME>。你还可以运行 docker ps -a 命令查看停止了的容器。在创建备份期间，你随时可以运行这些命令来获得帮助。

升级

在升级期间，你可以为当前 Rancher 容器创建数据的副本及备份，以确保可以在升级出现问题时可以进行回滚。然后，你可使用现有数据将新版本的 Rancher 部署到新容器中。

1. 创建 Rancher Server 容器的数据副本

1. 使用远程终端连接，登录到运行 Rancher Server 的节点。

2. 停止正在运行 Rancher Server 的容器。将 <RANCHER_CONTAINER_NAME> 替换为你的 Rancher 容器的名称：

   docker stop <RANCHER_CONTAINER_NAME>
3. 运行以下命令，从刚才停止的 Rancher 容器创建一个数据容器。请替换命令中的占位符：

   docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data rancher/rancher:<RANCHER_CONTAINER_TAG>

2. 创建备份压缩包

1. 从你刚刚创建的数据容器（rancher-data）中，创建一个备份 tar 包（rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz）。

   如果升级期间出现问题，此压缩包可以用作回滚点。替换占位符来运行以下命令。

   docker run --volumes-from rancher-data -v "$PWD:/backup" --rm busybox tar zcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher

   步骤结果：你输入此命令时，会运行一系列命令。

2. 输入 ls 命令，确认备份压缩包已创建成功。压缩包的名称格式类似 rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz。

   [rancher@ip-10-0-0-50 ~]$ ls
   rancher-data-backup-v2.1.3-20181219.tar.gz

3. 将备份压缩包移动到 Rancher Server 外的安全位置。

3. 拉取新的 Docker 镜像

拉取你需要升级到的 Rancher 版本镜像。

占位符	描述
<RANCHER_VERSION_TAG>	你想要升级到的 Rancher 版本的版本标签。

docker pull rancher/rancher:<RANCHER_VERSION_TAG>

4. 启动新的 Rancher Server 容器

使用 rancher-data 容器中的数据启动一个新的 Rancher Server 容器。记住要传入启动原始容器时使用的所有环境变量。

危险

启动升级后，即使升级耗时比预期长，也 不要 停止升级。如果你停止升级，可能会导致之后的升级中出现数据库迁移错误。

如果你使用代理，请参见 HTTP 代理配置。

如果你配置了自定义 CA 根证书来访问服务，请参见自定义 CA 根证书。

如果你要记录所有 Rancher API 的事务，请参见 API 审计。

如需查看启动新 Rancher Server 容器时使用的命令，从以下的选项中进行选择：

• Docker 升级
• 离线安装的 Docker 升级

Docker 升级

选择你安装 Rancher Server 时用的选项

选项 A：使用 Rancher 默认的自签名证书

单击展开

如果你使用 Rancher 生成的自签名证书，则将 --volumes-from rancher-data 添加到你启动原始 Rancher Server 容器的命令中。

占位符	描述
<RANCHER_VERSION_TAG>	你想要升级到的 Rancher 版本的版本标签。

docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG>

特权访问是必须的。

选项 B：使用你自己的证书 - 自签名

单击展开

如果你选择使用自己的自签名证书，则在启动原始 Rancher Server 容器的命令中添加 --volumes-from rancher-data。此外，你需要能够访问你原始安装时使用的证书。

证书要求提示：

证书文件的格式必须是 PEM。在你的证书文件中，包括链中的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。

占位符	描述
<CERT_DIRECTORY>	包含证书文件的目录的路径。
<FULL_CHAIN.pem>	完整证书链的路径。
<PRIVATE_KEY.pem>	证书私钥的路径。
<CA_CERTS.pem>	CA 证书的路径。
<RANCHER_VERSION_TAG>	你想要升级到的 Rancher 版本的版本标签。

docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
  -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
  -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG>

特权访问是必须的。

选项 C：使用你自己的证书 - 可信 CA 签名的证书

单击展开

如果你选择使用可信 CA 签名的证书，则在启动原始 Rancher Server 容器的命令中添加 --volumes-from rancher-data。此外，你需要能够访问你原始安装时使用的证书。注意要使用 --no-cacerts 作为容器的参数，以禁用 Rancher 生成的默认 CA 证书。

证书要求提示：

证书文件的格式必须是 PEM。在你的证书文件中，包括可信 CA 提供的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。如需查看示例，请参见证书故障排除。

占位符	描述
<CERT_DIRECTORY>	包含证书文件的目录的路径。
<FULL_CHAIN.pem>	完整证书链的路径。
<PRIVATE_KEY.pem>	证书私钥的路径。
<RANCHER_VERSION_TAG>	你想要升级到的 Rancher 版本的版本标签。

docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
  -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG> \
  --no-cacerts

特权访问是必须的。

选项 D：Let's Encrypt 证书

单击展开

警告

Let's Encrypt 对新证书请求有频率限制。因此，请限制创建或销毁容器的频率。详情请参见 Let's Encrypt 官方文档 - 频率限制。

如果你选择使用 Let's Encrypt 证书，则在启动原始 Rancher Server 容器的命令中添加 --volumes-from rancher-data，并且提供最初安装 Rancher 时使用的域名。

证书要求提示：

• 在 DNS 中创建一条记录，将 Linux 主机 IP 地址绑定到要用于访问 Rancher 的主机名（例如，rancher.mydomain.com）。
• 在 Linux 主机上打开 TCP/80 端口。Let's Encrypt 的 HTTP-01 质询可以来自任何源 IP 地址，因此端口 TCP/80 必须开放开所有 IP 地址。

占位符	描述
<RANCHER_VERSION_TAG>	你想要升级到的 Rancher 版本的版本标签。
<YOUR.DNS.NAME>	你最初使用的域名

docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG> \
  --acme-domain <YOUR.DNS.NAME>

特权访问是必须的。

Docker 离线升级

出于安全考虑，使用 Rancher 时请使用 SSL（Secure Sockets Layer）。SSL 保护所有 Rancher 网络通信（如登录和与集群交互）的安全。

启动新的 Rancher Server 容器时，从以下的选项中进行选择：

选项 A：使用 Rancher 默认的自签名证书

单击展开

如果你使用 Rancher 生成的自签名证书，则将 --volumes-from rancher-data 添加到你启动原始 Rancher Server 容器的命令中。

占位符	描述
<REGISTRY.YOURDOMAIN.COM:PORT>	私有镜像仓库的 URL 和端口。
<RANCHER_VERSION_TAG>	你想要升级到的 Rancher 版本的版本标签。

  docker run -d --volumes-from rancher-data \
      --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # 设置在 Rancher 中使用的默认私有镜像仓库
      -e CATTLE_SYSTEM_CATALOG=bundled \ # 使用打包的 Rancher System Chart
      --privileged \
      <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>

特权访问是必须的。

选项 B：使用你自己的证书 - 自签名

单击展开

如果你选择使用自己的自签名证书，则在启动原始 Rancher Server 容器的命令中添加 --volumes-from rancher-data。此外，你需要能够访问你原始安装时使用的证书。

证书要求提示：

证书文件的格式必须是 PEM。在你的证书文件中，包括链中的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。如需查看示例，请参见证书故障排除。

占位符	描述
<CERT_DIRECTORY>	包含证书文件的目录的路径。
<FULL_CHAIN.pem>	完整证书链的路径。
<PRIVATE_KEY.pem>	证书私钥的路径。
<CA_CERTS.pem>	CA 证书的路径。
<REGISTRY.YOURDOMAIN.COM:PORT>	私有镜像仓库的 URL 和端口。
<RANCHER_VERSION_TAG>	你想要升级到的 Rancher 版本的版本标签。

docker run -d --restart=unless-stopped \
    -p 80:80 -p 443:443 \
    -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
    -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
    -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
    -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # 设置在 Rancher 中使用的默认私有镜像仓库
    -e CATTLE_SYSTEM_CATALOG=bundled \ # 使用打包的 Rancher System Chart
    --privileged \
    <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>

特权访问是必须的。

选项 C：使用你自己的证书 - 可信 CA 签名的证书

单击展开

如果你选择使用可信 CA 签名的证书，则在启动原始 Rancher Server 容器的命令中添加 --volumes-from rancher-data。此外，你需要能够访问你原始安装时使用的证书。

证书要求提示：

证书文件的格式必须是 PEM。在你的证书文件中，包括可信 CA 提供的所有中间证书。你需要对你的证书进行排序，把你的证书放在最前面，后面跟着中间证书。如需查看示例，请参见证书故障排除。

占位符	描述
<CERT_DIRECTORY>	包含证书文件的目录的路径。
<FULL_CHAIN.pem>	完整证书链的路径。
<PRIVATE_KEY.pem>	证书私钥的路径。
<REGISTRY.YOURDOMAIN.COM:PORT>	私有镜像仓库的 URL 和端口。
<RANCHER_VERSION_TAG>	你想要升级到的 Rancher 版本的版本标签。

备注

使用 --no-cacerts 作为容器的参数，以禁用 Rancher 生成的默认 CA 证书。

docker run -d --volumes-from rancher-data \
    --restart=unless-stopped \
     -p 80:80 -p 443:443 \
     --no-cacerts \
     -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
     -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
     -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # 设置在 Rancher 中使用的默认私有镜像仓库
     -e CATTLE_SYSTEM_CATALOG=bundled \ # 使用打包的 Rancher System Chart
     --privileged
     <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>

特权访问是必须的。

结果：你已升级 Rancher。已升级 Server 中的数据将保存在 rancher-data 容器中，用于将来的升级。

5. 验证升级

登录到 Rancher。通过检查浏览器左下角的版本号，确认升级是否成功。

升级后下游集群出现网络问题？

请参见恢复集群网络。

6. 清理旧的 Rancher Server 容器

移除旧的 Rancher Server 容器。如果你仅停止了旧的 Rancher Server 容器，但没有移除它，该容器还可能在服务器下次重启后重新启动。

回滚

如果升级没有成功完成，你可以将 Rancher Server 及其数据回滚到上次的健康状态。详情请参见 Docker 回滚。