更新 Rancher 憑證

更新私有 CA 憑證

請依照以下步驟輪替 SSL 憑證和安裝在 Kubernetes 叢集上的 Rancher 所使用的私有 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 憑證正在更新時，需要執行此步驟。

在此情境中，需要重新部署 Rancher Pod，這是因為 tls-ca secret 在啟動時由 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 簽署的憑證時，Rancher Agent 容器會信任 CA 憑證鏈。Agent 會將下載的憑證的校驗和與 CATTLE_CA_CHECKSUM 環境變數進行比較。這意味著，當 Rancher 使用的私有 CA 憑證發生變更時，必須相應地更新環境變數 CATTLE_CA_CHECKSUM。

我應該選擇哪種方法？

方法 1 是最簡單的，但需要在憑證輪替後所有叢集都連線到 Rancher。如果在更新或重新部署 Rancher 部署（步驟 3）後立即執行此程序，通常會是這種情況。

如果叢集已失去與 Rancher 的連線，但所有叢集都啟用了授權叢集端點（ACE），則選擇方法 2。

如果方法 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 列中看到。

此指令將使用新憑證的校驗和重新套用 Agent 清單。

方法 2：手動更新校驗和環境變數

透過將 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

方法 3：手動重新部署 Rancher Agent

使用此方法，透過在每個下游叢集的控制平面節點上執行一組指令來重新套用 Rancher Agent。

對每個下游叢集重複以下步驟：

1. 取得 Agent 註冊 kubectl 指令：

   1. 找到下游叢集的叢集 ID（c-xxxxx），在 Rancher UI 的叢集管理下檢視叢集時，可以在 URL 中看到
   2. 將 Rancher 伺服器 URL 和叢集 ID 新增到以下 URL：https://<RANCHER_SERVER_URL>/v3/clusterregistrationtokens?clusterId=<CLUSTER_ID>
   3. 從 insecureCommand 欄位複製指令，使用此指令是因為正在使用私有 CA

2. 使用下游叢集的 kubeconfig，透過以下方法之一執行上一步驟的 kubectl 指令：

   1. 如果為叢集啟用了 ACE，可以調整上下文以直接連線到下游叢集
   2. 或者，SSH 進入控制平面節點：
      • RKE：使用此處文件中的步驟生成 kubeconfig
      • RKE2/K3s：使用安裝期間填入的 kubeconfig

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 核發的憑證變更為公開或自簽 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 secret：

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 檔案和目前的 Chart 版本更新 Rancher Chart 的 Helm 值，以防止升級：

  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 使用的憑證。