跳到主要内容
版本:v2.10 (Preview)

更新 Rancher 证书

更新私有 CA 证书

按照以下步骤轮换安装在 Kubernetes 集群上、由 Rancher 使用的 SSL 证书和私有 CA,或转用由私有 CA 签发的 SSL 证书。

步骤概述:

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

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

1. 创建/更新证书 Secret 对象

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

使用以下命令在 Rancher(本地)管理集群中创建 tls-rancher-ingress Secret 对象:

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

或者,更新现有的 tls-rancher-ingress Secret:

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 Secret 对象

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

创建初始 tls-ca Secret:

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 部署

如果证书源保持不变(例如,secret),请按照步骤 3a 中的步骤操作。

但是,如果证书源发生变化(例如,letsEncrypt 更改为 secret),请按照 3b 中的步骤操作。

3a. 重新部署 Rancher pod

当证书源保持不变,但需要更新 CA 证书时,需要执行此步骤。

在这种情况下,由于 tls-ca secret 在启动时由 Rancher pod 读取,因此你需要重新部署 Rancher pod。

你可以运行以下命令重新部署 Rancher pod:

kubectl rollout restart deploy/rancher -n cattle-system

修改完成后,访问 https://<RANCHER_SERVER_URL>/v3/settings/cacerts,验证该值是否与先前写入 tls-ca Secret 中的 CA 证书匹配。在所有重新部署的 Rancher pod 启动之前,CA cacerts 值可能不会更新。

3b. 更新 Rancher 的 Helm 值

如果证书源有更改,则需要执行此步骤。如果你的 Rancher 之前使用默认的自签名证书 (ingress.tls.source=rancher) 或 Let's Encrypt (ingress.tls.source=letsEncrypt) 证书,并且现在正在使用由私有 CA (ingress.tls.source=secret) 签名的证书。

以下步骤更新了 Rancher Chart 的 Helm 值,因此 Rancher pod 和 ingress 会使用在步骤 1 和 2 中创建的新私有 CA 证书。

  1. 调整初始安装期间使用的值,将当前值存储为:
helm get values rancher -n cattle-system -o yaml > values.yaml
  1. 检索当前部署的 Rancher Chart 的版本字符串:
helm ls -n cattle-system
  1. 更新 values.yaml 文件中的当前 Helm 值以包含下方内容:
ingress:
tls:
source: secret
privateCA: true
重要:

由于证书由私有 CA 签发,因此确保在 values.yaml 文件中设置了 privateCA: true 是非常重要的。

  1. 使用 values.yaml 文件和当前 Chart 版本升级 Helm 应用程序实例。版本必须匹配以防止 Rancher 升级。
 helm upgrade rancher rancher-stable/rancher \
--namespace cattle-system \
-f values.yaml \
--version <DEPLOYED_RANCHER_VERSION>

修改完成后,访问 https://<RANCHER_SERVER_URL>/v3/settings/cacerts,验证该值是否与先前写入 tls-ca Secret 中的 CA 证书匹配。在所有 Rancher pod 启动之前,CA cacerts 值可能不会更新。

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 环境变量进行比较。换言之,如果 Rancher 使用的私有 CA 证书发生变化,环境变量 CATTLE_CA_CHECKSUM 必须相应更新。

可使用的方法

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

  • 方法 2:适用于集群与 Rancher 失去连接,但所有集群都启用了 Authorized Cluster Endpoint (ACE) 的情况。

  • 方法 3:如果方法 1 和 2 不可行,则可使用方法 3 进行回退。

方法 1:强制重新部署 Rancher Agent

对于每个下游集群,使用 Rancher(本地)管理集群的 Kubeconfig 文件运行以下命令。

kubectl annotate clusters.management.cattle.io <CLUSTER_ID> io.cattle.agent.force.deploy=true
备注

找到下游集群的集群 ID (c-xxxxx)。你可以在 Rancher UI 的集群管理中查看集群时在浏览器 URL 中找到 ID。

此命令将使 Agent 清单重新应用新证书的校验和。

方法二:手动更新校验和环境变量

CATTLE_CA_CHECKSUM 环境变量更新为匹配新 CA 证书校验和的值,从而手动为 Agent Kubernetes 对象打上补丁。通过以下操作生成新的校验和:

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

为每个下游集群使用 Kubeconfig 更新两个 Agent 部署的环境变量。如果集群启用了 ACE,你可以调整 kubectl 上下文,从而直接连接到下游集群。

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

方法三:手动重新部署 Rancher agent

该方法通过在每个下游集群的 control plane 节点上运行一组命令,从而重新应用 Rancher agent。

对每个下游集群重复以下步骤:

  1. 检索 agent 注册 kubectl 命令:

    1. 找到下游集群的集群 ID (c-xxxxx)。你可以在 Rancher UI 的集群管理中查看集群时在浏览器 URL 中找到 ID。
    2. 将 Rancher Server URL 和集群 ID 添加到以下 URL:https://<RANCHER_SERVER_URL>/v3/clusterregistrationtokens?clusterId=<CLUSTER_ID>
    3. 复制 insecureCommand 字段中的命令,使用此命令是因为未使用私有 CA。
  2. 使用以下其中一种方法,使用 kubeconfig 为下游集群运行上一步中的 kubectl 命令:

    1. 如果集群启用了 ACE,你可以调整上下文,从而直接连接到下游集群。
    2. 或者,SSH 到 control plane 节点:

5. 强制更新 Fleet 集群,从而将 fleet-agent 重新连接到 Rancher

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

为什么要执行这一步骤?

Rancher 管理的集群中的 Fleet agent 存储了用于连接到 Rancher 的 kubeconfig。kubeconfig 包含一个 certificate-authority-data 字段,该字段包含 Rancher 使用的证书的 CA。更改 CA 时,你需要更新此块来允许 fleet-agent 信任 Rancher 使用的证书。

将私有 CA 证书更改为公共证书

按照以下步骤执行与上面相反的操作,将私有 CA 颁发的证书更改为公共或自签名 CA。

1. 创建/更新证书 Secret 对象

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

使用以下命令在 Rancher(本地)管理集群中创建 tls-rancher-ingress Secret 对象:

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

或者,更新现有的 tls-rancher-ingress Secret:

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 证书 Secret 对象

你需要删除 cattle-system 命名空间中的 tls-ca secret(不再需要它)。如果需要,你还可以选择保存 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 之前配置为使用默认的自签名证书 (ingress.tls.source=rancher)。

以下步骤更新了 Rancher Chart 的 Helm 值,因此 Rancher pod 和 Ingress 会使用在步骤 1 中创建的新证书。

  1. 调整初始安装期间使用的值,将当前值存储为:
helm get values rancher -n cattle-system -o yaml > values.yaml
  1. 获取当前部署的 Rancher Chart 的版本字符串:
helm ls -n cattle-system
  1. 更新 values.yaml 文件中的当前 Helm 值:
    1. 由于不再使用私有 CA,删除 privateCA: true 字段,或将其设置为 false
    2. 根据需要调整 ingress.tls.source 字段。有关更多信息,请参阅 Chart 选项。以下是一些示例:
      1. 如果使用公共 CA,继续使用 secret
      2. 如果使用 Let's Encrypt,将值更新为 letsEncrypt
  2. 使用 values.yaml 文件更新 Rancher Chart 的 Helm 值,并使用当前 Chart 版本防止升级:
  helm upgrade rancher rancher-stable/rancher \
--namespace cattle-system \
-f values.yaml \
--version <DEPLOYED_RANCHER_VERSION>

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

由于不再使用私有 CA,因此你需要删除下游集群 agent 上的 CATTLE_CA_CHECKSUM 环境变量,或将其设置为 ""(空字符串)。

5. 强制更新 Fleet 集群,从而将 fleet-agent 重新连接到 Rancher

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

为什么要执行这一步骤?

Rancher 管理的集群中的 Fleet agent 存储了用于连接到 Rancher 的 kubeconfig。kubeconfig 包含一个 certificate-authority-data 字段,该字段包含 Rancher 使用的证书的 CA。更改 CA 时,你需要更新此块来允许 fleet-agent 信任 Rancher 使用的证书。