更新 Rancher 证书
更新私有 CA 证书
按照以下步骤轮换安装在 Kubernetes 集群上、由 Rancher 使用的 SSL 证书和私有 CA,或转用由私有 CA 签发的 SSL 证书。
步骤概述:
- 使用新证书和私钥创建或更新
tls-rancher-ingress
Kubernetes Secret 对象。 - 使用根 CA 证书创建或更新
tls-ca
Kubernetes Secret 对象(仅在使用私有 CA 时需要)。 - 使用 Helm CLI 更新 Rancher 安装。
- 重新配置 Rancher Agent 以信任新的 CA 证书。
- 选择 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 证书。
- 调整初始安装期间使用的值,将当前值存储为:
helm get values rancher -n cattle-system -o yaml > values.yaml
- 检索当前部署的 Rancher Chart 的版本字符串:
helm ls -n cattle-system
- 更新
values.yaml
文件中的当前 Helm 值以包含下方内容:
ingress:
tls:
source: secret
privateCA: true
由于证书由私有 CA 签发,因此确保在 values.yaml
文件中设置了 privateCA: true
是非常重要的。
- 使用
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。
对每个下游集群重复以下步骤:
检索 agent 注册 kubectl 命令:
- 找到下游集群的集群 ID (c-xxxxx)。你可以在 Rancher UI 的集群管理中查看集群时在浏览器 URL 中找到 ID。
- 将 Rancher Server URL 和集群 ID 添加到以下 URL:
https://<RANCHER_SERVER_URL>/v3/clusterregistrationtokens?clusterId=<CLUSTER_ID>
。 - 复制
insecureCommand
字段中的命令,使用此命令是因为未使用私有 CA。
使用以下其中一种方法,使用 kubeconfig 为下游集群运行上一步中的 kubectl 命令:
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 中创建的新证书。
- 调整初始安装期间使用的值,将当前值存储为:
helm get values rancher -n cattle-system -o yaml > values.yaml
- 获取当前部署的 Rancher Chart 的版本字符串:
helm ls -n cattle-system
- 更新
values.yaml
文件中的当前 Helm 值:- 由于不再使用私有 CA,删除
privateCA: true
字段,或将其设置为false
。 - 根据需要调整
ingress.tls.source
字段。有关更多信息,请参阅 Chart 选项。以下是一些示例:- 如果使用公共 CA,继续使用
secret
- 如果使用 Let's Encrypt,将值更新为
letsEncrypt
- 如果使用公共 CA,继续使用
- 由于不再使用私有 CA,删除
- 使用
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 使用的证书。