在 Kubernetes 集群上安装/升级 Rancher
在本节中,你将学习如何使用 Helm CLI 在 Kubernetes 集群上部署 Rancher。
先决条件
Kubernetes 集群
设置 Rancher Server 的本地 Kubernetes 集群。
Rancher 可以安装在任何 Kubernetes 集群上。这个集群可以使用上游 Kubernetes,也可以使用 Rancher 的 Kubernetes 发行版之一,也可以是来自 Amazon EKS 等提供商的托管 Kubernetes 集群。
你可参考以下教程,以获得设置 Kubernetes 集群的帮助:
- RKE:安装 RKE Kubernetes 集群的教程;为高可用 RKE 集群设置基础设施的教程。
- K3s:安装 K3s Kubernetes 集群的教程;设置高可用 K3s 集群的基础设施的教程。
- RKE2: :安装 RKE2 Kubernetes 集群的教程;设置高可用 RKE2 集群的基础设施的教程。
- Amazon EKS:在 Amazon EKS 上安装 Rancher 以及如何安装 Ingress Controller 以访问 Rancher Server。
- AKS:使用 Azure Kubernetes 服务安装 Rancher 以及如何安装 Ingress Controller 以访问 Rancher Server。
- GKE:有关如何使用 GKE 安装 Rancher,包括如何安装 Ingress Controller 以便可以访问 Rancher Server,请参阅此页面。GKE 创建 Kubernetes 集群时有两种运行模式,分别是 Autopilot 和 Standard 模式。Autopilot 模式的集群配置对编辑 kube-system 命名空间有限制。但是,Rancher 在安装时需要在 kube-system 命名空间中创建资源。因此,你将无法在以 Autopilot 模式创建的 GKE 集群上安装 Rancher。
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
中可用。
- kubectl - Kubernetes 命令行工具。
- Helm - Kubernetes 的包管理器。请参见 Helm 版本要求选择 Helm 版本来安装 Rancher。请为你的具体平台参见 Helm 项目提供的说明。
安装 Rancher Helm Chart
Rancher 是使用 Kubernetes 的 Helm 包管理器安装的。Helm Chart 为 Kubernetes YAML 清单文件提供了模板语法。通过 Helm,用户可以创建可配置的 deployment,而不仅仅只能使用静态文件。
如果系统无法直接访问互联网,请参见离线环境:Kubernetes 安装。
如果要指定安装的 Rancher 版本,请参见选择 Rancher 版本。
如果要指定用于安装 Rancher 的 Helm 版本,请参见Helm 版本要求。
本安装指南假定你使用的是 Helm 3。
要设置 Rancher:
- 添加 Helm Chart 仓库
- 为 Rancher 创建命名空间
- 选择 SSL 配置
- 安装 cert-manager(除非你自带证书,否则 TLS 将在负载均衡器上终止)
- 使用 Helm 和你选择的证书选项安装 Rancher
- 验证 Rancher Server 是否部署成功
- 保存选项
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:即将发布的实验性预览。注意:不支持升级到 Alpha 版、从 Alpha 版升级或在 Alpha 版之间升级。
helm repo add rancher-alpha https://releases.rancher.com/server-charts/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.crt
和tls.key
的 PEM 格式的证书以及相关的密钥。如果你使用私有 CA,则还必须上传该 CA 证书。这是由于你的节点可能不信任此私有 CA。Rancher 将获取该 CA 证书,并从中生成一个校验和,各种 Rancher 组件将使用该校验和来验证其与 Rancher 的连接。
配置 | Helm Chart 选项 | 是否需要 cert-manager |
---|---|---|
Rancher 生成的证书(默认) | ingress.tls.source=rancher | 是 |
Let’s Encrypt | ingress.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 生成的证书
- 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 及更高版本来说,这不是必需的,但你仍然可以手动设置该选项。
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
此选项使用 cert-manager
来自动请求和续订 Let's Encrypt 证书。Let's Encrypt 是免费的,而且是受信的 CA,因此可以为你提供有效的证书。
由于 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 及更高版本来说,这不是必需的,但你仍然可以手动设置该选项。
helm install rancher rancher-<CHART_REPO>/rancher \
--namespace cattle-system \
--set hostname=rancher.my.org \
--set bootstrapPassword=admin \
--set ingress.tls.source=letsEncrypt \
--set letsEncrypt.email=me@example.org \
--set letsEncrypt.ingress.class=nginx
如果你安装的是 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
运行这个命令时,hostname
选项必须与服务器证书中的 Common Name
或 Subject Alternative Names
条目匹配,否则 Ingress controller 将无法正确配置。
虽然技术上仅需要 Subject Alternative Names
中有一个条目,但是拥有一个匹配的 Common Name
可以最大程度地提高与旧版浏览器/应用的兼容性。
如果你想检查证书是否正确,请查看如何在服务器证书中检查 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 及更高版本来说,这不是必需的,但你仍然可以手动设置该选项。
helm install rancher rancher-<CHART_REPO>/rancher \
--namespace cattle-system \
--set hostname=rancher.my.org \
--set bootstrapPassword=admin \
--set ingress.tls.source=secret
如果你安装的是 alpha 版本,Helm 会要求你在安装命令中添加 --devel
选项:
helm install rancher rancher-alpha/rancher --devel
如果你使用的是私有 CA 证书,请在命令中增加 --set privateCA=true
。
helm install rancher rancher-<CHART_REPO>/rancher \
--namespace cattle-system \
--set hostname=rancher.my.org \
--set bootstrapPassword=admin \
--set ingress.tls.source=secret \
--set privateCA=true
添加 TLS 密文(千万不要遗漏此步骤):现在 Rancher 已经完成部署,你还需要参考添加 TLS 密文发布证书文件,以便 Rancher 和 Ingress Controller 可以使用它们。
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
DESIRED
和 AVAILABLE
的个数应该相同。
7. 保存选项
请保存你使用的 --set
选项。使用 Helm 升级 Rancher 到新版本时,你将需要使用相同的选项。
安装完成
安装已完成。现在 Rancher Server 应该已经可以正常运行了。
使用浏览器打开把流量转发到你的负载均衡器的 DNS 域名。然后,你就会看到一个漂亮的登录页面了。
如果遇到任何问题,请参见故障排除。