使用 bmctl 備份及還原叢集

本文說明如何使用 bmctl 備份及還原僅透過 Distributed Cloud 軟體建立的叢集 (僅限裸機)。這些操作說明適用於所有叢集類型。

警告： 使用備份檔案還原叢集是最後手段。還原程序會重設現有叢集，並覆寫叢集資訊。除非叢集發生嚴重故障，否則不建議從備份檔案還原。請向 Cloud Customer Care 團隊尋求協助，決定最佳做法。

系統會備份的內容和不會備份的內容

bmctl 備份和還原程序是在 Kubernetes 控制層運作，與其他備份解決方案不同。非 Kubernetes 備份解決方案會擷取工作負載資料、永久儲存空間，以及實體機器的主機作業系統。bmctl備份和還原程序會還原 Kubernetes 叢集，但不會備份任何其他元件。

控制層狀態 (由 bmctl 備份程序備份)

bmctl 會備份下列物件：

• etcd 儲存庫。所有 Kubernetes 資源和自訂物件，用於定義叢集的設定和所選狀態 (例如 Pod 規格、部署作業、ConfigMap 和 Secret)。
• PKI 憑證。用於叢集內安全通訊的憑證。
• 節點設定檔和資訊清單。與叢集節點相關的設定。

工作負載和 VM Runtime 儲存空間 (不會透過 bmctl 備份程序備份)

bmctl 不會備份下列資料：

• 即時 Pod 和容器執行階段狀態。bmctl不會儲存進行中的程序和記憶體中的應用程式資料。還原後，Kubernetes 會根據 etcd 規格重新啟動 Pod。所有未儲存的記憶體內狀態都會遺失。
• 永久磁碟區儲存空間。bmctl 不會備份儲存在永久磁碟區、本機磁碟區佈建程式 (LVP) 建立的磁碟區，或外部儲存空間驅動程式中的資料。
• 虛擬機器磁碟。bmctl 不會備份 VM 虛擬硬碟的內容，例如資料庫、檔案或 VM 內的作業系統狀態。

您必須使用 Kubernetes 原生或客內備份機制，保護應用程式資料和虛擬機器狀態。如果基礎儲存空間驅動程式支援 CSI 磁碟區快照，請使用標準 Kubernetes 磁碟區快照，建立永久磁碟區的時間點副本。如要進一步瞭解如何設定儲存空間，請參閱「儲存空間總覽」。

在 VM Runtime 虛擬機器的客體作業系統中執行備份代理程式，或在 Kubernetes 工作負載中部署應用程式原生備份工具。

實體主機作業系統 (不支援)

將 Google Distributed Cloud 節點上的實體 Linux 作業系統視為可拋棄式基礎架構。Kubernetes 網路架構不支援還原主機層級的 OS 映像檔。因此，Google 不支援直接在主機 OS 上安裝第三方主機層級備份代理程式，也不支援從 OS 層級映像檔備份或磁碟快照還原實體節點。

如果直接在主機 Linux 作業系統上安裝第三方實體備份代理程式，可能會造成嚴重風險。

許多備份代理程式會安裝專屬核心模組或區塊層級篩選器驅動程式，以便追蹤變更並在快照作業期間鎖定本機磁碟區塊，這可能會導致下列問題：

• etcd 資料庫無法附加至預先寫入記錄、節點心跳逾時、Raft 共識失敗，且叢集變得不穩定。
• 不支援的第三方核心驅動程式與低階核心常式和容器執行階段發生衝突，導致叢集升級失敗。
• 從映像檔備份或磁碟快照還原實體節點，會違反 Raft 共識通訊協定。etcd 資料庫與控制層節點上的記錄檔失去同步，導致叢集狀態嚴重損毀。
• 工作節點會與 API 伺服器的真實資訊來源失去同步、Dataplane V2 (Cilium) IP 位址發生衝突，且流量會遭到捨棄。

如要復原作業系統或硬體故障的實體節點，請勿還原 OS 映像檔。請從叢集中乾淨地移除節點，重新安裝乾淨的基礎作業系統，然後將節點重新加入節點集區。如需詳細的復原操作說明，請參閱「重設失敗的節點」。

如需其他協助，請與 Cloud Customer Care 團隊聯絡。如要進一步瞭解支援資源，包括：

• 建立客服案件的必要條件。
• 工具：協助您排解問題，例如環境設定、記錄和指標。
• 支援的元件。

備份叢集

bmctl backup cluster 指令會將叢集的 etcd 資料和 PKI 憑證封裝到 tar 檔案中。etcd 資料庫是所有叢集資料的中央資料儲存庫，包含管理叢集狀態所需的所有 Kubernetes 物件和自訂資源。PKI 憑證會透過 TLS 進行驗證。這項資料是從叢集的控制層備份，或是從高可用性 (HA) 部署作業的其中一個控制層備份。

備份 tar 檔案包含私密憑證，包括服務帳戶金鑰和 SSH 金鑰。將備份檔案儲存在安全的位置。為避免檔案意外曝光，Google Distributed Cloud 備份程序只會使用記憶體內檔案。

定期備份叢集，確保快照資料相對較新。請根據叢集重大變更的頻率，調整備份頻率。

用來備份叢集的 bmctl 版本必須與管理叢集的版本相符。

如果您在叢集上安裝 Node Agent，管理員節點和所有目標節點上的 /tmp 目錄必須有 12 GB 的可用空間。如果無法變更目標節點的 /tmp 目錄大小，請參閱「變更目標節點的本機儲存空間容量」。如果無法變更管理員節點的 /tmp 目錄大小，請參閱「變更管理員節點的本機儲存空間容量」。

如要備份叢集，請按照下列步驟操作：

1. 請確認叢集運作正常，且所有節點的憑證和 SSH 連線都正常運作。

   備份程序的目的是擷取叢集已知的良好狀態，以便在發生災難性故障時還原作業。

   使用下列指令檢查叢集：

   bmctl check cluster -c CLUSTER_NAME --kubeconfig ADMIN_KUBECONFIG
   

   更改下列內容：

   • CLUSTER_NAME：您打算備份的叢集名稱。
   • ADMIN_KUBECONFIG：管理員叢集的 kubeconfig 檔案路徑。

2. 執行下列指令，確保目標叢集未處於協調狀態：

   kubectl describe cluster CLUSTER_NAME -n CLUSTER_NAMESPACE --kubeconfig ADMIN_KUBECONFIG
   

   更改下列內容：

   • CLUSTER_NAME：要備份的叢集名稱。
   • CLUSTER_NAMESPACE：叢集的命名空間。根據預設，Google Distributed Cloud 的叢集命名空間是叢集名稱加上 cluster- 前置字串。舉例來說，如果將叢集命名為 test，命名空間的名稱會類似 cluster-test。
   • ADMIN_KUBECONFIG：管理員叢集的 kubeconfig 檔案路徑。

3. 在指令輸出內容中，檢查 Status 區段是否有 Reconciling 類型的 Conditions。

   如下例所示，這些 的Conditions狀態為 False，表示叢集穩定且已準備好備份。

   ...
   Status:
     ...
     Cluster State:  Running
     ...
     Control Plane Node Pool Status:
       ...
       Conditions:
         Last Transition Time:  2023-11-03T16:37:15Z
         Observed Generation:   1
         Reason:                ReconciliationCompleted
         Status:                False
         Type:                  Reconciling
     ...
   

4. 執行下列指令來備份叢集：

   bmctl backup cluster -c CLUSTER_NAME --kubeconfig ADMIN_KUBECONFIG
   

   更改下列內容：

   • CLUSTER_NAME：要備份的叢集名稱。
   • ADMIN_KUBECONFIG：管理員叢集 kubeconfig 檔案的路徑。

   根據預設，備份 tar 檔案會儲存在管理員工作站的工作區目錄 (預設為 bmctl-workspace)。tar 檔案名為「CLUSTER_NAME_backup_TIMESTAMP.tar.gz」，其中 CLUSTER_NAME 是要備份的叢集名稱，TIMESTAMP 則是備份的日期和時間。舉例來說，如果叢集名稱為 testuser，備份檔案的名稱會類似 testuser_backup_2006-01-02T150405Z0700.tar.gz。

   如要為備份檔案指定其他名稱和位置，請使用 --backup-file 旗標。

備份檔案會在一年後過期，叢集還原程序無法使用過期的備份檔案。

還原叢集

從備份還原叢集是最後手段，只有在叢集發生災難性故障，且無法以其他方式恢復服務時才應使用。舉例來說，etcd 資料已損毀，或 etcd Pod 處於當機迴圈。

注意： 為提升叢集效能，Google Distributed Cloud 會使用個別的 etcd 執行個體儲存事件物件。這些 Event 物件的存留時間 (TTL) 為一小時。叢集還原作業會建立新的空白 etcd 事件例項，因此您會遺失現有的事件物件。不過，遺失 Event 物件不會影響叢集運作。事件應視為僅供參考的補充資料，並盡可能提供。

備份 tar 檔案包含私密憑證，包括服務帳戶金鑰和 SSH 金鑰。為避免檔案遭到意外曝光，Google Distributed Cloud 還原程序只會使用記憶體內檔案。

用於還原叢集的 bmctl 版本必須與管理叢集的版本相符。

如要還原叢集，請按照下列步驟操作：

1. 確認備份時叢集可用的所有節點機器都正常運作且可連線。

2. 確認節點之間的 SSH 連線可搭配備份時使用的 SSH 金鑰組運作。

   這些 SSH 金鑰會在還原程序中恢復。

3. 確認備份時使用的服務帳戶金鑰仍有效。

   系統會為還原的叢集恢復這些服務帳戶金鑰。

4. 如要還原管理員、混合式或獨立叢集，請執行下列指令：

   bmctl restore cluster -c CLUSTER_NAME --backup-file BACKUP_FILE
   

   更改下列內容：

   • CLUSTER_NAME：要還原的叢集名稱。
   • BACKUP_FILE：您使用的備份檔案路徑和名稱。

5. 如要還原使用者叢集，請執行下列指令：

   bmctl restore cluster -c CLUSTER_NAME --backup-file BACKUP_FILE \
       --kubeconfig ADMIN_KUBECONFIG
   

   更改下列內容：

   • CLUSTER_NAME：要還原的叢集名稱。
   • BACKUP_FILE：您使用的備份檔案路徑和名稱。
   • ADMIN_KUBECONFIG：管理員叢集 kubeconfig 檔案的路徑。

還原程序完成後，系統會為還原的叢集產生新的 kubeconfig 檔案。

還原程序完成後，請按照下列步驟確認是否成功：

1. 執行下列指令，使用產生的 kubeconfig 檔案驗證節點就緒狀態和系統 Pod 執行狀態：

   etcd Pod 分為兩種類型：

   • etcd-HOST_NAME，對應於主要etcd Pod
   • etcd-events-HOST_NAME，對應於 etcd-events Pod

   kubectl get pods -n kube-system --kubeconfig GENERATED_KUBECONFIG
   kubectl get nodes --kubeconfig GENERATED_KUBECONFIG
   

2. 針對每個 etcd Pod，執行下列指令來驗證 etcd 健康狀態：

   kubectl exec ETCD_POD_NAME -n kube-system \
       --kubeconfig GENERATED_KUBECONFIG \
       -- /bin/sh -c 'ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
       --cacert=/etc/kubernetes/pki/etcd/ca.crt --key=/etc/kubernetes/pki/etcd/peer.key \
       --cert=/etc/kubernetes/pki/etcd/peer.crt endpoint health'
   

   如果 etcd 成員運作正常，回應內容應如下所示：

   https://127.0.0.1:2379 is healthy: successfully committed proposal: took = 11.514177ms
   

3. 針對每個 etcd-events Pod，執行下列指令來驗證 etcd-events 健康狀態：

   kubectl exec ETCD_EVENTS_POD_NAME -n kube-system \
       --kubeconfig GENERATED_KUBECONFIG \
       -- /bin/sh -c 'ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2382 \
       --cacert=/etc/kubernetes/pki/etcd/ca.crt --key=/etc/kubernetes/pki/etcd/peer.key \
       --cert=/etc/kubernetes/pki/etcd/peer.crt endpoint health'
   

   如果 etcd-events 成員運作正常，回應應如下所示：

   https://127.0.0.1:2382 is healthy: successfully committed proposal: took = 14.308148ms
   

疑難排解

如果備份或還原程序發生問題，請參閱下列各節，或許有助於排解問題。

如需其他協助，請與 Google 支援團隊聯絡。

備份或還原期間記憶體不足

備份或還原程序可能會顯示錯誤訊息，但這些訊息不一定能清楚說明問題或後續步驟。如果您執行 bmctl 指令的工作站 RAM 不足，可能無法順利完成備份或還原程序。

Google Distributed Cloud 1.13 以上版本可以在備份指令中使用 --use-disk 參數。為保留檔案權限，這個參數會修改檔案權限，因此執行指令的使用者必須是超級使用者 (或使用 sudo)。

還原檔案時權限不足

還原作業成功後，刪除 bootstrap 可能會失敗，並顯示類似下列範例的錯誤訊息：

  Error: failed to restore node config files: sftp: "Failure" (SSH_FX_FAILURE)

這項錯誤可能表示還原作業所需的某些目錄無法寫入。

Google Distributed Cloud 1.14 以上版本會顯示更清楚的錯誤訊息，說明哪些目錄必須可寫入。請確認報告中的目錄可寫入，並視需要更新目錄的權限。

備份後重新整理 SSH 金鑰會中斷還原程序

如果在執行備份作業後重新整理 SSH 金鑰，還原程序期間的 SSH 相關作業可能會失敗。在這種情況下，新的 SSH 金鑰會對還原程序失效。

如要解決這個問題，可以暫時加回原始 SSH 金鑰，然後執行還原作業。還原程序完成後，即可輪替 SSH 金鑰。

無法為節點代理程式節點建立備份

如果您使用節點代理程式，並收到建立備份時無法建立封存檔的錯誤訊息 (類似如下)：

  I0508 15:29:36.831790  657351 backup_cluster.go:255] Retrying backup node: 128.187.102.133, due to error: failed receive chunk data: rpc error: code = Unknown desc = archiver.CreateArchiveWithList
  failed: failed to create archive file: failed to copy data from file: var/lib/etcd-events/member/snap/db, file size: 26136576, copy bytes: 12478464,
  error: write /tmp/uploadFileTemp1561164777: no space left on device

確認管理員節點和所有目標節點的 /tmp 目錄中，都有 12 GB 的可用空間。如果無法變更目標節點的 /tmp 目錄大小，請參閱「增加節點代理程式備份的本機儲存空間容量」。

確認管理員節點和所有目標節點的 /tmp 目錄都有 12 GB 的可用空間後，請再次嘗試備份。