高可用安装指南

先决条件

Kubernetes 集群

设置 Rancher 服务器的本地 Kubernetes 集群。

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

对于设置 Kubernetes 集群的帮助,我们提供这些教程:

  • RKE:有关安装 RKE Kubernetes 集群的教程,请参考本页,有关为高可用性 RKE 集群设置基础设施的帮助,请参考本页
  • K3s:安装 K3s Kubernetes 集群的教程,请参考本页。如需帮助设置高可用性 K3s 集群的基础架构,请参考本页
  • Amazon EKS: 在 EKS 上安装 Kubernetes 集群的教程,请参考本页
  • RKE2:在 RKE2 安装 Kubernetes 集群的教程,请参考本页。如需帮助设置高可用性 K3s 集群的基础架构,请参考本页

CLI

以下 CLI 工具是创建 Kubernetes 集群所必需的。请确保这些工具已安装并在您的$PATH中可用。

请查看 Helm 项目提供的安装指南,来在您的平台上进行安装。

  • kubectl - Kubernetes 命令行工具。
  • helm - Kubernetes 的软件包管理工具。请参阅 Helm 版本要求以选择要安装 Rancher 的 Helm 版本。
提示

国内用户,可以导航到 http://mirror.cnrancher.com 下载所需资源。

Ingress Controller

适用于托管在云厂商上的集群

要在托管的 Kubernetes 集群(如 EKS、GKE 或 AKS)上部署 Rancher v2.5+,应先部署一个兼容的 Ingress 控制器,在 Rancher 上配置 SSL 终止。

请参考本页,获取关于在 AWS EKS 上部署 Rancher 的详细操作步骤。

安装 Rancher Helm Chart

Rancher 使用 Kubernetes 的 Helm 软件包管理器安装。Helm Charts 为 Kubernetes YAML 清单文档提供了模板语法。

有了 Helm,我们可以创建可配置的 Deployment,而不只是使用静态文件。有关创建您自己的 Deployment 的应用商店应用的更多信息,请查看 https://helm.sh/ 中的文档。

对于无法直接访问 Internet 的系统,请参阅Rancher 离线安装

选择要安装的 Rancher 版本,请参阅选择 Rancher 版本

要选择用于安装 Rancher 的 Helm 版本,请参阅Helm 版本要求

注意

本安装指南假定您使用的是 Helm3。有关从 Helm 2 迁移到 Helm 3 的方法,请参阅官方的Helm 2 到 3 迁移文档。这个指南提供了使用 Helm 2 在 RKE Kubernetes 集群上安装 Rancher 的较旧的安装指南,适用于无法升级到 Helm 3 的情况。

1. 添加 Helm Chart 仓库

使用helm repo add命令添加含有 Rancher Chart 的 Helm Chart 仓库。

请将命令中的<CHART_REPO>,替换为lateststablealpha。更多信息,请查看选择 Rancher 版本来选择最适合您的仓库。

  • latest: 建议在尝试新功能时使用。
  • stable: 建议在生产环境中使用。(推荐)
  • alpha: 未来版本的实验性预览。
  1. helm repo add rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>
提示

国内用户,可以使用放在国内的 Rancher Chart 加速安装:

  1. helm repo add rancher-<CHART_REPO> http://rancher-mirror.oss-cn-beijing.aliyuncs.com/server-charts/<CHART_REPO>

2. 为 Rancher 创建 Namespace

我们需要定义一个 Kubernetes Namespace,在 Namespace 中安装由 Chart 创建的资源。这个命名空间的名称为cattle-system

  1. kubectl create namespace cattle-system

3. 选择您的 SSL 选项

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

提示

如果您想要将 SSL/TLS 访问在外部终止,请参考:使用外部 TLS 负载均衡器

您可以从以下三种证书来源中选择一种,证书将用来在 Rancher Server 中终止 TLS:

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

Rancher 中国技术支持团队建议您使用“您已有的证书” ingress.tls.source=secret 这种方式,从而减少对 cert-manager 的运维成本。

4. 安装 cert-manager

提示

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

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

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

  1. # 安装 CustomResourceDefinition 资源
  2. kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.4/cert-manager.crds.yaml
  3. # **重要:**
  4. # 如果您正在运行 Kubernetes v1.15 或更低版本,
  5. # 则需要在上方的 kubectl apply 命令中添加`--validate=false`标志,
  6. # 否则您将在 cert-manager 的 CustomResourceDefinition 资源中收到与
  7. # x-kubernetes-preserve-unknown-fields 字段有关的验证错误。
  8. # 这是一个良性错误,是由于 kubectl 执行资源验证的方式造成的。
  9. # 为 cert-manager 创建命名空间
  10. kubectl create namespace cert-manager
  11. # 添加 Jetstack Helm 仓库
  12. helm repo add jetstack https://charts.jetstack.io
  13. # 更新本地 Helm chart 仓库缓存
  14. helm repo update
  15. # 安装 cert-manager Helm chart
  16. helm install \
  17. cert-manager jetstack/cert-manager \
  18. --namespace cert-manager \
  19. --version v1.0.4

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

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

5. 根据您选择的 SSL 选项,通过 Helm 安装 Rancher

方式 A:使用 Rancher 生成的自签名证书

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

因为rancheringress.tls.source的默认选项,所以在运行helm install命令时我们没有指定ingress.tls.source

  • hostname设置为您指向负载均衡器的 DNS 名称。
  • 如果您在安装 alpha 版本,需要把--devel 选项添加到下面到 Helm 命令中。
  • 要安装指定版本的 Rancher,请使用--version选项,例如:--version 2.3.6
  1. helm install rancher rancher-<CHART_REPO>/rancher \
  2. --namespace cattle-system \
  3. --set hostname=rancher.my.org

等待 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

Rancher Chart 有许多自定义安装选项以适应特定的环境。以下是一些常见的高级方案。

有关选项的完整列表,请参见Chart 选项

方式 B:使用 Let’s Encrypt 证书

该选项使用cert-manager来自动请求和续订 Let’s Encrypt证书。这是一项免费服务,可为您提供有效的证书,因为 Let’s Encrypt 是受信任的 CA。

在下面的命令中,

  • hostname 设置为公共 DNS 记录。
  • ingress.tls.source 选项设置为 letsEncrypt
  • letsEncrypt.email 设置为可通讯的电子邮件地址,方便发送通知(例如证书到期的通知)。
  • 如果您在安装 alpha 版本,需要把--devel 选项添加到下面到 Helm 命令中。
  1. helm install rancher rancher-<CHART_REPO>/rancher \
  2. --namespace cattle-system \
  3. --set hostname=rancher.my.org \
  4. --set ingress.tls.source=letsEncrypt \
  5. --set letsEncrypt.email=me@example.org

等待 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

Rancher Chart 有许多自定义安装选项以适应特定的环境。以下是一些常见的高级方案。

有关选项的完整列表,请参见Chart 选项

方式 C:使用您已有的证书

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

当您运行此命令时,hostname选项必须与服务器证书中的Common NameSubject Alternative Names条目匹配,否则 Ingress 控制器将无法正确配置。

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

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

  • 设置 hostname
  • ingress.tls.source 选项设置为 secret
  • 如果您在安装 alpha 版本,需要把--devel 选项添加到下面到 Helm 命令中。
  1. helm install rancher rancher-<CHART_REPO>/rancher \
  2. --namespace cattle-system \
  3. --set hostname=rancher.my.org \
  4. --set ingress.tls.source=secret

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

  1. helm install rancher rancher-latest/rancher \
  2. --namespace cattle-system \
  3. --set hostname=rancher.my.org \
  4. --set ingress.tls.source=secret \
  5. --set privateCA=true

现在已经部署了 Rancher,请参阅添加 TLS 密文发布证书文件,以便 Rancher 和 ingress 控制器可以使用它们。

Rancher Chart 有许多自定义安装选项以适应特定的环境。以下是一些常见的高级方案。

有关选项的完整列表,请参见Chart 选项

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

检查 Rancher Server 是否运行成功:

  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

DESIREDAVAILABLE应该显示相同的个数。

7. 保存您的选项

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

安装完成

现在您应该具有一个功能正常的 Rancher Server 了。

打开浏览器,访问您的 DNS,这个 DNS 会将流量转发到您的负载均衡器,您应该会看到一个色彩丰富的登录页面。

如果在安装过程中碰到了问题,请查看故障排查页面。