[Rancher] Downstream cluster 因 cattle-controllers leader lease 過期未釋放而顯示「Waiting for cluster agent to connect」

環境

• SUSE Rancher Manager v2.13.2（HA 部署，3 個 replicas）
• RKE2 v1.34.4+rke2r1 downstream cluster（3 台 control plane + 3 台 worker 節點）
• SUSE Linux Enterprise Server 15 SP7
• 管理叢集與 downstream cluster 皆使用 Kubernetes v1.34.x

狀況

在 Rancher deployment 更新（例如 rollout restart、Helm upgrade 或 pod 重新排程）之後，一個或多個 downstream cluster 在 Rancher UI 上進入 Reconciling 或 Updating 狀態。受影響的 machine 顯示以下訊息：

Waiting for cluster agent to connect

叢集本身功能完全正常 — 所有節點為 Ready，所有 pod 皆在運行，對 downstream cluster 執行 kubectl 指令也能正常回應。然而 Rancher UI 持續顯示叢集處於已斷線狀態。

症狀

1. Rancher UI 顯示叢集狀態為 Updating，且一台或多台 machine 處於 Reconciling 狀態，並附帶訊息「Waiting for cluster agent to connect」。

   

2. Downstream cluster 的 cattle-cluster-agent 日誌顯示已成功建立 WebSocket 連線至 Rancher server：

   Connected to proxy  url="wss://rancher.example.com/v3/connect/register"

3. 儘管看似已連線，但 Rancher server 的日誌顯示 tunnel 認證失敗：

   Failed to handle tunnel request from remote address 10.42.x.x:xxxxx
   (X-Forwarded-For: x.x.x.x): response 401: failed authentication

4. 管理叢集的 clusters.management.cattle.io 物件顯示 Connected: False：

   type: Connected
   status: "False"

5. Provisioning cluster 的 conditions 顯示：

   type: Updated
   status: Unknown
   message: "configuring bootstrap node(s) custom-xxxxxxxx: waiting for cluster agent to connect"
   
   type: Ready
   status: "False"
   message: "Cluster agent is not connected"
   reason: Disconnected

6. kube-system namespace 中的 cattle-controllers leader lease 指向一個已不存在的 pod：

   $ kubectl get lease cattle-controllers -n kube-system -o yaml
   spec:
     holderIdentity: rancher-<old-replicaset>-<old-pod>
     leaseDurationSeconds: 162000

原因

Rancher 的 management controllers（負責叢集狀態調解、tunnel 認證、agent 部署與 machine 狀態更新）使用 kube-system namespace 中名為 cattle-controllers 的 Kubernetes Lease 物件進行 leader election。只有 leader pod 才會處理叢集管理操作。

當 Rancher deployment 更新（rolling restart、Helm upgrade 等）時，舊的 pod 會被終止並由新 ReplicaSet 的新 pod 取代。然而，Rancher 將 cattle-controllers lease 的 leaseDurationSeconds 設定為 162,000 秒（45 小時）。這是刻意設定的長時間值，目的是避免短暫網路中斷時發生不必要的 leader 切換。

問題發生的流程如下：

1. 當前的 leader pod 在 deployment 更新過程中被終止。
2. 過期的 lease 仍然指向已終止 pod 的身份識別。
3. 新的 Rancher pod 檢查 lease 後發現 renewTime + leaseDurationSeconds 尚未到期。
4. 所有新 pod 等待 lease 自然過期 — 最長需要等待 45 小時。
5. 在這段等待期間，沒有任何 management controller 在運作，導致所有 downstream cluster 的管理操作停擺。

這會引發一連串連鎖故障：

• Cluster agent 的 tunnel 認證請求無人處理（401 錯誤）。
• Cluster 物件上的 Connected 狀態永遠不會被更新。
• Machine reconciliation 不會被執行。
• Rancher UI 持續反映過期的「Waiting for cluster agent to connect」狀態。

解決方案

立即修復

刪除過期的 leader lease，讓當前的 Rancher pod 立即取得 leadership：

kubectl delete lease cattle-controllers -n kube-system

在 30 秒內，一個新的 Rancher pod 將取得 lease，management controllers 將恢復正常運作。驗證新的 leader：

kubectl get lease cattle-controllers -n kube-system \
  -o jsonpath='{.spec.holderIdentity}'

確認 holder identity 與當前運行中的 Rancher pod 相符：

kubectl get pods -n cattle-system -l app=rancher -o name

在 lease 被取得之後，downstream cluster 的狀態應在 1–3 分鐘內從 Updating/Reconciling 轉為 Active。

驗證

1. 確認叢集已恢復連線：

   kubectl get clusters.management.cattle.io <cluster-id> \
     -o jsonpath='{.status.conditions[?(@.type=="Connected")]}' | python3 -m json.tool

   預期輸出："status": "True"

2. 在 Rancher UI 確認所有 machine 都顯示 Running 狀態。

3. 驗證對所有節點上的 pod 執行 kubectl logs 時不再出現 502 錯誤。

預防措施

為降低未來 Rancher 更新時再次遇到此問題的影響：

1. 在更新後監控 lease。 每次 Rancher deployment 重啟或升級後，驗證 cattle-controllers lease 是否指向正在運行的 pod：

   LEADER=$(kubectl get lease cattle-controllers -n kube-system \
     -o jsonpath='{.spec.holderIdentity}')
   kubectl get pod -n cattle-system "$LEADER" 2>/dev/null \
     || echo "警告：Leader pod $LEADER 不存在 — lease 已過期"

2. 將 lease 檢查納入升級手冊。 在您的標準 Rancher 升級流程中，於 rollout 完成後立即加入 lease 驗證步驟。

3. 考慮提交 feature request。 162,000 秒（45 小時）的 lease 過期時間設定過於保守。較短的過期時間（例如 300–600 秒）可以縮短 failover 視窗，同時仍能提供對短暫網路中斷的韌性。

診斷步驟摘要

以下指令用於診斷此問題，可在類似的故障排查中重複使用：

補充資訊

• 此問題可能同時影響任意數量的 downstream cluster，因為所有叢集管理操作皆依賴單一的 cattle-controllers leader。
• 此問題不限於 Rancher v2.13.x，任何使用長 leaseDurationSeconds 設定的 cattle-controllers lease 版本都可能發生。
• 在此期間，downstream cluster 本身保持完全正常運作。僅 Rancher 的 management plane 操作受到影響。
• 刪除 lease 是非破壞性操作。新的 leader 將根據系統的當前狀態從頭開始重新調解所有叢集狀態。