更新 Rancher 证书

更新私有 CA 证书

本文介绍如何更新 Rancher 高可用 Kubernetes 安装 中 Ingress 的 SSL 证书，以及如何从默认的自签名证书切换到自定义证书。

步骤概述：

1. 使用新证书和私钥创建或更新 tls-rancher-ingress Kubernetes 密文资源。
2. 使用根 CA 证书创建或更新 tls-ca Kubernetes 密文资源（仅在使用私有 CA 时需要）。
3. 使用 Helm CLI 更新 Rancher 安装。
4. 重新配置 Rancher Agent 以信任新的 CA 证书。
5. 选择 Fleet 集群的强制更新，来将 fleet-agent 连接到 Rancher。

各个步骤的详细说明如下。

1. 创建/更新证书密文资源

首先，将服务器证书和所有中间证书合并到名为 tls.crt 的文件，并在名为 tls.key 的文件中提供相应的证书密钥。

如果你想切换 Rancher 自签名证书或 Let's Encrypt 证书，请运行以下命令，在 Rancher 高可用集群中创建 tls-rancher-ingress 密文资源：

$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=tls.crt \
  --key=tls.key

你也可以运行以下命令，更新现有的证书密文：

$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=tls.crt \
  --key=tls.key \
  --dry-run --save-config -o yaml | kubectl apply -f -

2. 创建/更新证书 CA 密文资源

如果新证书由私有 CA 签发的，你需要将相应的根 CA 证书复制到名为 cacerts.pem 的文件中，并创建或更新 cattle-system 命名空间中的 tls-ca 密文。如果证书由中间 CA 签名，则 cacerts.pem 必须按顺序同时包含中间 CA 证书和根 CA 证书。

创建初始密文：

$ kubectl -n cattle-system create secret generic tls-ca \
  --from-file=cacerts.pem

要更新现有的 tls-ca Secret：

$ kubectl -n cattle-system create secret generic tls-ca \
  --from-file=cacerts.pem \
  --dry-run --save-config -o yaml | kubectl apply -f -

3. 重新配置 Rancher 部署

备注

在继续之前，在 Rancher UI (用户 > API & 密钥 ) 中生成一个 API Token，并保存持有者 Token（你在步骤 4 中可能需要）。

只有在最初安装 Rancher 时使用了自签名证书 （ingress.tls.source=rancher）或 Let's Encrypt 证书（ingress.tls.source=letsEncrypt）时，你才需要执行此步骤。

这一步骤确保 Rancher Pod 和 Ingress 资源能够重新配置，来使用新的服务器和可选的 CA 证书。

要更新 Helm 部署，请使用初始安装时的选项（--set）。运行以下命令检查：

$ helm get values rancher -n cattle-system

获取当前部署的 Rancher Chart 的版本字符串：

$ helm ls -A

使用初始配置的值升级 Helm 应用实例，并指定 ingress.tls.source=secret 以及当前的 Chart 版本来防止应用升级。

如果证书是由私有 CA 签发的，你需要添加 set privateCA=true 参数。请确保你已经阅读了使用自定义证书进行初始安装的文档。

helm upgrade rancher rancher-stable/rancher \
  --namespace cattle-system \
  --version <DEPLOYED_CHART_VERSION> \
  --set hostname=rancher.my.org \
  --set ingress.tls.source=secret \
  --set ...

升级完成后，访问 https://<Rancher_SERVER>/v3/settings/cacerts，验证该值是否与先前写入 tls-ca 密文中的 CA 证书匹配。

4. 重新配置 Rancher Agent 以信任私有 CA

本节介绍了重新配置 Rancher Agent 以信任私有 CA 的三种方法。如果你的实际情况符合以下任意一个条件，请执行此步骤：

• Rancher 初始配置中使用了 Rancher 自签名证书 (ingress.tls.source=rancher) 或 Let's Encrypt 证书 (ingress.tls.source=letsEncrypt)。
• 新自定义证书的根 CA 证书已更改。

为什么要执行这一步骤？

如果 Rancher 配置了私有 CA 签名的证书时，CA 证书链会下载到 Rancher Agent 容器中。Agent 会对下载证书的校验和及 CATTLE_CA_CHECKSUM 环境变量进行比较。如果私有 CA 证书在 Rancher Server 端更改了，环境变量 CATTLE_CA_CHECKSUM 必须相应进行更新。

可使用的方法

• 方法 1（最简单的方法）： 在轮换证书后将所有集群连接到 Rancher。适用于更新 Rancher 部署（步骤 3）后立即执行的情况。

• 方法 2：适用于集群失去了与 Rancher 的连接，但是你已启动了授权集群端点（ACE）的情况。

• 方法 3：方法 1 和方法 2 不可用的情况下可使用。

方法 1：Kubectl 命令

对于集群管理中的每个集群（除去 local Rancher 管理集群），使用 Rancher 管理集群（RKE 或 K3S）的 Kubeconfig 文件运行以下命令：

kubectl patch clusters.management.cattle.io <REPLACE_WITH_CLUSTERID> -p '{"status":{"agentImage":"dummy"}}' --type merge

这个命令能使所有 Agent Kubernetes 资源使用新证书的校验和重新配置。

方法 2：手动更新校验和

通过将 CATTLE_CA_CHECKSUM 环境变量更新为匹配新 CA 证书校验和的值，来手动为 Agent Kubernetes 资源打上补丁。通过以下操作生成新的校验和：

$ curl -k -s -fL <RANCHER_SERVER>/v3/settings/cacerts | jq -r .value > cacert.tmp
$ sha256sum cacert.tmp | awk '{print $1}'

为每个下游集群使用 Kubeconfig 更新两个 Agent 部署的环境变量。

$ kubectl edit -n cattle-system ds/cattle-node-agent
$ kubectl edit -n cattle-system deployment/cattle-cluster-agent

方法 3：重新创建 Rancher Agent

你可以在每个下游集群的 controlplane 节点上运行一组命令，来重新创建 Rancher Agent。

首先，生成 Agent 定义（参见此处）。

然后，SSH 连接到下游集群的 controlplane 节点，创建 Kubeconfig 并应用定义（参见此处）。

5. 选择 Fleet 集群的强制更新，来将 fleet-agent 连接到 Rancher

在 Rancher UI 的持续交付中，为集群选择“强制更新”，来允许下游集群中的 fleet-agent 成功连接到 Rancher。

为什么要执行这一步骤？

Rancher 管理的集群中的 Fleet agent 存储 kubeconfig，该配置用于连接到 Fleet 系统命名空间的 fleet-agent 密文中的 Rancher 代理 kube-api。kubeconfig 包括一个包含 Rancher CA 的证书授权数据块。更改 Rancher CA 时，需要更新此块来使 fleet-agent 成功连接到 Rancher。

将私有 CA 证书更改为通用证书

备注

你可以执行与上文描述相反的操作，即将私有证书更改为通用或非私有证书。所涉及的步骤概述如下。

1. 创建/更新证书密文资源

首先，将服务器证书和所有中间证书合并到名为 tls.crt 的文件，并在名为 tls.key 的文件中提供相应的证书密钥。

如果你想切换 Rancher 自签名证书或 Let's Encrypt 证书，请运行以下命令，在 Rancher 高可用集群中创建 tls-rancher-ingress 密文资源：

$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=tls.crt \
  --key=tls.key

你也可以运行以下命令，更新现有的证书密文：

$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=tls.crt \
  --key=tls.key \
  --dry-run --save-config -o yaml | kubectl apply -f -

2. 删除 CA 证书密文资源

你需要删除 cattle-system 命名空间中的 tls-ca secret（不再需要它）。如果需要，你还可以选择保存 tls-ca secret 的副本。

要保存现有密文：

kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml

要删除现有的 tls-ca 密文：

kubectl -n cattle-system delete secret tls-ca

3. 重新配置 Rancher 部署

重要提示：

在继续之前，先在 Rancher UI 中生成 API 令牌（在 User > API & Keys 中）。

只有在最初安装 Rancher 时使用了自签名证书 （ingress.tls.source=rancher）或 Let's Encrypt 证书（ingress.tls.source=letsEncrypt）时，你才需要执行此步骤。

这一步骤确保 Rancher Pod 和 Ingress 资源能够重新配置，来使用新的服务器和可选的 CA 证书。

要更新 Helm 部署，请使用初始安装时的选项（--set）。运行以下命令检查：

$ helm get values rancher -n cattle-system

获取当前部署的 Rancher Chart 的版本字符串：

$ helm ls -A

使用初始配置的值升级 Helm 应用程序实例，并指定当前的 Chart 版本以防止应用程序升级。

请确保你已经阅读了使用自定义证书进行初始安装的文档。

helm upgrade rancher rancher-stable/rancher \
  --namespace cattle-system \
  --version <DEPLOYED_CHART_VERSION> \
  --set hostname=rancher.my.org \
  --set ...

升级时，你可以执行以下其中一个操作：

• 从 Helm 升级命令中删除 --set ingress.tls.source=secret \，如上所示。

• 删除 privateCA 参数或将其设置为 false （因为 CA 有效）：

set privateCA=false

4. 为非私有/通用证书重新配置 Rancher Agent

下游集群 Agent 上的 CATTLE_CA_CHECKSUM 环境变量应该被删除或设置为“”（一个空字符串）。

5. 选择 Fleet 集群的强制更新，来将 fleet-agent 连接到 Rancher

在 Rancher UI 的持续交付中，为集群选择“强制更新”，来允许下游集群中的 fleet-agent 成功连接到 Rancher。

为什么要执行这一步骤？

Rancher 管理的集群中的 Fleet agent 存储 kubeconfig，该配置用于连接到 Fleet 系统命名空间的 fleet-agent 密文中的 Rancher 代理 kube-api。kubeconfig 包括一个包含 Rancher CA 的证书授权数据块。更改 Rancher CA 时，需要更新此块来使 fleet-agent 成功连接到 Rancher。