在 Kubernetes 集群上安装/升级 Rancher

在本节中，你将学习如何使用 Helm CLI 在 Kubernetes 集群上部署 Rancher。

先决条件

Kubernetes 集群

设置 Rancher Server 的本地 Kubernetes 集群。

Rancher 可以安装在任何 Kubernetes 集群上。这个集群可以使用上游 Kubernetes，也可以使用 Rancher 的 Kubernetes 发行版之一，也可以是来自 Amazon EKS 等提供商的托管 Kubernetes 集群。

你可参考以下教程，以获得设置 Kubernetes 集群的帮助：

Ingress Controller

Rancher UI 和 API 通过 Ingress 公开。换言之，安装 Rancher 的 Kubernetes 集群必须包含一个 Ingress Controller。

对于 RKE、RKE2 和 K3s，你不需要手动安装 Ingress Controller，因为它是默认安装的。

对于默认不包含 Ingress Controller 的发行版（例如 EKS、GKE 或 AKS 等托管 Kubernetes 集群），你必须先部署 Ingress Controller。请注意，Rancher Helm Chart 默认情况下不会在 Ingress 上设置 ingressClassName。因此，你必须将 Ingress Controller 配置为在没有 ingressClassName 的情况下也可以监视 Ingress。

上面的 Amazon EKS、AKS 和 GKE 教程中包含了示例。

CLI 工具

设置 Kubernetes 集群需要以下 CLI 工具。请确保这些工具已安装并在你的 $PATH 中可用。

安装 Rancher Helm Chart

Rancher 是使用 Kubernetes 的 Helm 包管理器安装的。Helm Chart 为 Kubernetes YAML 清单文件提供了模板语法。通过 Helm，用户可以创建可配置的 deployment，而不仅仅只能使用静态文件。

如果系统无法直接访问互联网，请参见离线环境：Kubernetes 安装。

如果要指定安装的 Rancher 版本，请参见选择 Rancher 版本。

如果要指定用于安装 Rancher 的 Helm 版本，请参见Helm 版本要求。

Install/Upgrade on a Kubernetes Cluster - 图1备注

本安装指南假定你使用的是 Helm 3。

要设置 Rancher：

  1. 添加 Helm Chart 仓库
  2. 为 Rancher 创建命名空间
  3. 选择 SSL 配置
  4. 安装 cert-manager（除非你自带证书，否则 TLS 将在负载均衡器上终止）
  5. 使用 Helm 和你选择的证书选项安装 Rancher
  6. 验证 Rancher Server 是否部署成功
  7. 保存选项

1. 添加 Helm Chart 仓库

执行 helm repo add 命令，以添加包含安装 Rancher 的 Chart 的 Helm Chart 仓库。有关如何选择仓库，以及哪个仓库最适合你的用例，请参见选择 Rancher 版本。

  • Latest：建议用于试用最新功能

    1. helm repo add rancher-latest https://releases.rancher.com/server-charts/latest

  • Stable：建议用于生产环境

    1. helm repo add rancher-stable https://releases.rancher.com/server-charts/stable

  • Alpha：即将发布的实验性预览。

    1. helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha

    注意：不支持升级到 Alpha 版、从 Alpha 版升级或在 Alpha 版之间升级。

2. 为 Rancher 创建命名空间

你需要定义一个 Kubernetes 命名空间，用于安装由 Chart 创建的资源。这个命名空间的名称为 cattle-system：

  1. kubectl create namespace cattle-system

3. 选择 SSL 配置

Rancher Management Server 默认需要 SSL/TLS 配置来保证访问的安全性。

Install/Upgrade on a Kubernetes Cluster - 图2备注

如果你想在外部终止 SSL/TLS，请参见外部负载均衡器的 TLS 终止。

你可以从以下三种证书来源中选择一种，用于在 Rancher Server 中终止 TLS：

  • Rancher 生成的 TLS 证书：要求你在集群中安装 cert-manager。Rancher 使用 cert-manager 签发并维护证书。Rancher 会生成自己的 CA 证书，并使用该 CA 签署证书。然后 cert-manager负责管理该证书。
  • Let’s Encrypt：Let’s Encrypt 选项也需要使用 cert-manager。但是，在这种情况下，cert-manager 与 Let’s Encrypt 的特殊颁发者相结合，该颁发者执行获取 Let’s Encrypt 颁发的证书所需的所有操作（包括请求和验证）。此配置使用 HTTP 验证（HTTP-01），因此负载均衡器必须具有可以从互联网访问的公共 DNS 记录。
  • 你已有的证书：使用已有的 CA 颁发的公有或私有证书。Rancher 将使用该证书来保护 WebSocket 和 HTTPS 流量。在这种情况下，你必须上传名称分别为 tls.crt 和 tls.key的 PEM 格式的证书以及相关的密钥。如果你使用私有 CA，则还必须上传该 CA 证书。这是由于你的节点可能不信任此私有 CA。Rancher 将获取该 CA 证书，并从中生成一个校验和，各种 Rancher 组件将使用该校验和来验证其与 Rancher 的连接。
配置Helm Chart 选项是否需要 cert-manager
Rancher 生成的证书（默认）ingress.tls.source=rancher是
Let’s Encryptingress.tls.source=letsEncrypt是
你已有的证书ingress.tls.source=secret否

4. 安装 cert-manager

如果你使用自己的证书文件（ingress.tls.source=secret）或使用外部负载均衡器的 TLS 终止，你可以跳过此步骤。

仅在使用 Rancher 生成的证书（ingress.tls.source=rancher）或 Let’s Encrypt 颁发的证书（ingress.tls.source=letsEncrypt）时，才需要安装 cert-manager。

单击展开

Install/Upgrade on a Kubernetes Cluster - 图3重要提示：

由于 cert-manager 的最新改动，你需要升级 cert-manager 版本。如果你需要升级 Rancher 并使用低于 0.11.0 的 cert-manager 版本，请参见升级文档。

这些说明来自 cert-manager 官方文档。

Install/Upgrade on a Kubernetes Cluster - 图4备注

要查看自定义 cert-manager 安装的选项（包括集群使用 PodSecurityPolicies 的情况），请参阅 cert-manager 文档。

  1. # 如果你手动安装了CRD，而不是在 Helm 安装命令中添加了 `--set installCRDs=true` 选项，你应该在升级 Helm Chart 之前升级 CRD 资源。
  2. kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/<VERSION>/cert-manager.crds.yaml
  4. # 添加 Jetstack Helm 仓库
  5. helm repo add jetstack https://charts.jetstack.io
  7. # 更新本地 Helm Chart 仓库缓存
  8. helm repo update
  10. # 安装 cert-manager Helm Chart
  11. helm install cert-manager jetstack/cert-manager \
  12.   --namespace cert-manager \
  13.   --create-namespace

安装完 cert-manager 后，你可以通过检查 cert-manager 命名空间中正在运行的 Pod 来验证它是否已正确部署：

  1. kubectl get pods --namespace cert-manager
  3. NAME                                       READY   STATUS    RESTARTS   AGE
  4. cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
  5. cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
  6. cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

5. 根据你选择的证书选项，通过 Helm 安装 Rancher

不同的证书配置需要使用不同的 Rancher 安装命令。

但是，无论证书如何配置，Rancher 在 cattle-system 命名空间中的安装名称应该总是 rancher。

Install/Upgrade on a Kubernetes Cluster - 图5测试和开发：

这个安装 Rancher 的最终命令需要一个将流量转发到 Rancher 的域名。如果你使用 Helm CLI 设置概念证明，则可以在传入 hostname 选项时使用伪域名。伪域名的一个例子是 <IP_OF_LINUX_NODE>.sslip.io，这会把 Rancher 暴露在它运行的 IP 上。生产安装中要求填写真实的域名。

  • Rancher 生成的证书
  • Let’s Encrypt
  • 证书文件

默认情况是使用 Rancher 生成 CA，并使用 cert-manager 颁发用于访问 Rancher Server 接口的证书。

由于 rancher 是 ingress.tls.source 的默认选项，因此在执行 helm install 命令时，我们不需要指定 ingress.tls.source。

  • 将 hostname 设置为解析到你的负载均衡器的 DNS 名称。
  • 将 bootstrapPassword 设置为 admin 用户独有的值。
  • 如果你需要安装指定的 Rancher 版本，使用 --version 标志，例如 --version 2.7.0。
  • 对于 Kubernetes v1.25 或更高版本，使用 Rancher v2.7.2-v2.7.4 时，将 global.cattle.psp.enabled 设置为 false。对于 Rancher v2.7.5 及更高版本来说，这不是必需的，但你仍然可以手动设置该选项。
  1. helm install rancher rancher-<CHART_REPO>/rancher \
  2.   --namespace cattle-system \
  3.   --set hostname=rancher.my.org \
  4.   --set bootstrapPassword=admin

如果你安装的是 alpha 版本，Helm 会要求你在安装命令中添加 --devel 选项：

  1. helm install rancher rancher-alpha/rancher --devel

等待 Rancher 运行：

  1. kubectl -n cattle-system rollout status deploy/rancher
  2. Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
  3. deployment "rancher" successfully rolled out

此选项使用 cert-manager 来自动请求和续订 Let’s Encrypt 证书。Let’s Encrypt 是免费的，而且是受信的 CA，因此可以为你提供有效的证书。

Install/Upgrade on a Kubernetes Cluster - 图6备注

由于 HTTP-01 质询只能在端口 80 上完成，因此你需要打开端口 80。

在以下命令中，

  • 将 hostname 设置为公有 DNS 记录。
  • 将 bootstrapPassword 设置为 admin 用户独有的值。
  • 将 ingress.tls.source 设置为 letsEncrypt。
  • 将 letsEncrypt.email 设置为可通讯的电子邮件地址，用于发送通知（例如证书到期的通知）。
  • 将 letsEncrypt.ingress.class 设为你的 Ingress Controller（例如 traefik，nginx，haproxy）
  • 对于 Kubernetes v1.25 或更高版本，使用 Rancher v2.7.2-v2.7.4 时，将 global.cattle.psp.enabled 设置为 false。对于 Rancher v2.7.5 及更高版本来说，这不是必需的，但你仍然可以手动设置该选项。
  1. helm install rancher rancher-<CHART_REPO>/rancher \
  2.   --namespace cattle-system \
  3.   --set hostname=rancher.my.org \
  4.   --set bootstrapPassword=admin \
  5.   --set ingress.tls.source=letsEncrypt \
  6.   --set letsEncrypt.email=me@example.org \
  7.   --set letsEncrypt.ingress.class=nginx

如果你安装的是 alpha 版本，Helm 会要求你在安装命令中添加 --devel 选项：

  1. helm install rancher rancher-alpha/rancher --devel

等待 Rancher 运行：

  1. kubectl -n cattle-system rollout status deploy/rancher
  2. Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
  3. deployment "rancher" successfully rolled out

在此选项中，你使用你自己的证书来创建 Kubernetes 密文，以供 Rancher 使用。

运行这个命令时，hostname 选项必须与服务器证书中的 Common Name 或 Subject Alternative Names 条目匹配，否则 Ingress controller 将无法正确配置。

虽然技术上仅需要 Subject Alternative Names 中有一个条目，但是拥有一个匹配的 Common Name 可以最大程度地提高与旧版浏览器/应用的兼容性。

Install/Upgrade on a Kubernetes Cluster - 图7备注

如果你想检查证书是否正确，请查看如何在服务器证书中检查 Common Name 和 Subject Alternative Names。

  • 设置 hostname。
  • 将 bootstrapPassword 设置为 admin 用户独有的值。
  • 将 ingress.tls.source 设置为 secret。
  • 对于 Kubernetes v1.25 或更高版本，使用 Rancher v2.7.2-v2.7.4 时，将 global.cattle.psp.enabled 设置为 false。对于 Rancher v2.7.5 及更高版本来说，这不是必需的，但你仍然可以手动设置该选项。
  1. helm install rancher rancher-<CHART_REPO>/rancher \
  2.   --namespace cattle-system \
  3.   --set hostname=rancher.my.org \
  4.   --set bootstrapPassword=admin \
  5.   --set ingress.tls.source=secret

如果你安装的是 alpha 版本，Helm 会要求你在安装命令中添加 --devel 选项：

  1. helm install rancher rancher-alpha/rancher --devel

如果你使用的是私有 CA 证书，请在命令中增加 --set privateCA=true。

  1. helm install rancher rancher-<CHART_REPO>/rancher \
  2.   --namespace cattle-system \
  3.   --set hostname=rancher.my.org \
  4.   --set bootstrapPassword=admin \
  5.   --set ingress.tls.source=secret \
  6.   --set privateCA=true

添加 TLS 密文（千万不要遗漏此步骤）：现在 Rancher 已经完成部署，你还需要参考添加 TLS 密文发布证书文件，以便 Rancher 和 Ingress Controller 可以使用它们。

Rancher Chart 有许多选项，用于为你的具体环境自定义安装。以下是一些常见的高级方案：

如需获取完整的选项列表，请参见 Chart 选项。

6. 验证 Rancher Server 是否部署成功

添加密文后，检查 Rancher 是否已成功运行：

  1. kubectl -n cattle-system rollout status deploy/rancher
  2. Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
  3. deployment "rancher" successfully rolled out

如果你看到 error: deployment "rancher" exceeded its progress deadline 这个错误，可运行以下命令来检查 deployment 的状态：

  1. kubectl -n cattle-system get deploy rancher
  2. NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
  3. rancher   3         3         3            3           3m

DESIRED 和 AVAILABLE的个数应该相同。

7. 保存选项

请保存你使用的 --set 选项。使用 Helm 升级 Rancher 到新版本时，你将需要使用相同的选项。

安装完成

安装已完成。现在 Rancher Server 应该已经可以正常运行了。

使用浏览器打开把流量转发到你的负载均衡器的 DNS 域名。然后，你就会看到一个漂亮的登录页面了。

如果遇到任何问题，请参见故障排除。