跳到主要内容
版本:v2.7

在 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 EKSAKSGKE 教程中包含了示例。

CLI 工具

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

安装 Rancher Helm Chart

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

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

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

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

备注

本安装指南假定你使用的是 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:建议用于试用最新功能
    helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
  • Stable:建议用于生产环境
    helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
  • Alpha:即将发布的实验性预览。
    helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha
    注意:不支持升级到 Alpha 版、从 Alpha 版升级或在 Alpha 版之间升级。

2. 为 Rancher 创建命名空间

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

kubectl create namespace cattle-system

3. 选择 SSL 配置

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

备注

如果你想在外部终止 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.crttls.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。

单击展开
重要提示:

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

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

备注

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

# 如果你手动安装了CRD,而不是在 Helm 安装命令中添加了 `--set installCRDs=true` 选项,你应该在升级 Helm Chart 之前升级 CRD 资源。
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/<VERSION>/cert-manager.crds.yaml

# 添加 Jetstack Helm 仓库
helm repo add jetstack https://charts.jetstack.io

# 更新本地 Helm Chart 仓库缓存
helm repo update

# 安装 cert-manager Helm Chart
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace

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

kubectl get pods --namespace cert-manager

NAME READY STATUS RESTARTS AGE
cert-manager-5c6866597-zw7kh 1/1 Running 0 2m
cert-manager-cainjector-577f6d9fd7-tr77l 1/1 Running 0 2m
cert-manager-webhook-787858fcdb-nlzsq 1/1 Running 0 2m

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

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

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

测试和开发:

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

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

由于 rancheringress.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 及更高版本来说,这不是必需的,但你仍然可以手动设置该选项。
helm install rancher rancher-<CHART_REPO>/rancher \
--namespace cattle-system \
--set hostname=rancher.my.org \
--set bootstrapPassword=admin

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

helm install rancher rancher-alpha/rancher --devel

等待 Rancher 运行:

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

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

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

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

添加密文后,检查 Rancher 是否已成功运行:

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

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

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

DESIREDAVAILABLE的个数应该相同。

7. 保存选项

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

安装完成

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

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

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