本文說明使用 Backup for GKE 執行還原作業時，可能遇到的錯誤和對應代碼。每個章節都會說明執行動作來解決還原錯誤時的注意事項，以及如何解決還原作業錯誤。
錯誤 200010301：由於准入 Webhook 服務無法使用，因此無法完成還原作業
如果嘗試完成還原作業時，因准入 Webhook 服務 (也稱為 HTTP 回呼) 無法使用而失敗，就會發生錯誤 200010301，並顯示下列錯誤訊息。錯誤訊息表示 GKE API 伺服器嘗試在還原資源時聯絡許可控制器 Webhook，但支援該 Webhook 的服務無法使用或找不到：
resource [/example-group/ClusterSecretStore/example-store] restore failed:
Internal error occurred: failed calling webhook "example-webhook.io":
failed to call webhook: Post "https://example-webhook.example-namespace.svc:443/validate-example": service "example-webhook" not found.
如果目標叢集中有作用中的 ValidatingAdmissionWebhook 或 MutatingAdmissionWebhook GKE 資源，但 GKE API 伺服器無法連上 Webhook 中設定的端點，就會發生這個錯誤。准入 Webhook 會攔截傳送至 GKE API 伺服器的要求，而其設定會指定 GKE API 伺服器應如何查詢要求。
Webhook 的 clientConfig 會指定處理准入要求的後端，可以是內部叢集服務或外部網址。這兩個選項的選擇取決於 Webhook 的具體作業和架構需求。視選項類型而定，還原作業可能因下列原因而失敗：
叢集內服務：GKE API 伺服器嘗試呼叫 Webhook 時，GKE 服務及其支援 Pod 未還原或準備就緒。在還原作業期間，如果叢集範圍的 Webhook 設定在命名空間服務完全處於
ready狀態前套用，就會發生這種情況。外部網址：由於 GKE 叢集與外部端點之間的網路連線問題，或 DNS 解析問題或防火牆規則，外部端點暫時無法使用。
如要解決這項錯誤，請按照下列說明操作：
找出錯誤訊息中提及的失敗 Webhook。例如
failed calling webhook "..."。執行
kubectl get validatingwebhookconfigurations指令，檢查 Webhook：kubectl get validatingwebhookconfigurations WEBHOOK_NAME -o yaml將
WEBHOOK_NAME替換為錯誤訊息中識別的 Webhook 名稱。您也可以執行
kubectl get mutatingwebhookconfigurations指令來檢查 Webhook：kubectl get mutatingwebhookconfigurations WEBHOOK_NAME -o yaml將
WEBHOOK_NAME替換為錯誤訊息中識別出的 Webhook 名稱。請根據設定類型執行下列疑難排解步驟：
根據服務
clientConfig如要定義自訂還原順序，請修改
RestorePlan資源，加入含有GroupKindDependency項目 的RestoreOrder。這樣一來，系統就能在ValidatingWebhookConfiguration或MutatingWebhookConfiguration之前，還原並準備好支援 Webhook 的元件，例如Deployment、StatefulSet或Service。如需如何定義自訂還原順序的操作說明，請參閱「在還原期間指定資源還原順序」。
這種做法可能會失敗，因為即使建立
Service物件，服務的 Pod 也不會進入完全ready狀態。失敗的另一個原因可能是其他應用程式意外建立 Webhook 設定。或者，您也可以按照下列步驟執行兩階段還原作業：使用備份建立
Restore資源，方法是透過精細的還原篩選器設定還原作業，其中會包含 Webhook 運作所需的特定資源，例如Namespaces、Deployments、StatefulSets或Services。如要進一步瞭解如何使用精細還原篩選器設定還原作業，請參閱「啟用精細還原功能」。
為備份作業建立另一個
Restore資源，並設定您選擇的其餘資源。
以網址為準
clientConfig驗證外部 HTTPS 端點，並確認該端點處於啟用狀態、可連線，且運作正常。
確認 GKE 叢集節點和控制層可連線至外部網址。您可能也需要檢查防火牆規則，例如使用虛擬私有雲、內部部署或代管 Webhook 的雲端服務供應商、網路政策和 DNS 解析時。
請重試還原作業。如果作業持續失敗，請聯絡 Cloud Customer Care 團隊，取得進一步協助。
錯誤 200010302：資源建立要求遭拒，因此無法完成還原作業
如果准入 Webhook 拒絕資源建立要求，導致還原作業無法完成，就會發生 200010302 錯誤。這時系統會顯示下列錯誤訊息，指出備份中的資源無法在目標叢集中建立，因為作用中的准入 Webhook 攔截了要求，並根據自訂政策拒絕要求：
[KubeError]; e.g. resource
[/example-namespace/example-api/ExampleResource/example-name]
restore failed: admission webhook "example-webhook.example.com" denied the request: {reason for denial}
這個錯誤是由目標 GKE 叢集中設定的 ValidatingAdmissionWebhook 或 MutatingAdmissionWebhook 所致，這類設定會對資源建立和修改作業強制執行特定規則，導致資源建立要求遭到封鎖。舉例來說，Webhook 會禁止建立資源，因為叢集中已有相關但衝突的資源。舉例來說，如果部署作業已由 HorizontalPodAutoscaler GKE API 資源管理，Webhook 可能會拒絕建立該部署作業。
如要解決這項錯誤，請按照下列說明操作：
使用還原作業失敗時發生的錯誤訊息，找出拒絕要求的 Webhook。舉例來說，
webhook WEBHOOK_NAME denied the request錯誤訊息包含下列資訊：Webhook 名稱：拒絕要求的 Webhook 名稱。
拒絕原因：拒絕要求的具體原因。
執行
kubectl get validatingwebhookconfigurations指令，檢查 Webhook：kubectl get validatingwebhookconfigurations WEBHOOK_NAME -o yaml將
WEBHOOK_NAME替換為錯誤訊息中識別的 Webhook 名稱。您也可以執行
kubectl get mutatingwebhookconfigurations指令來檢查 Webhook：kubectl get mutatingwebhookconfigurations WEBHOOK_NAME -o yaml將
WEBHOOK_NAME替換為您從錯誤訊息中識別的 Webhook 名稱。解決目標叢集中的根本問題。正確的動作取決於具體錯誤。以這個例子來說，如果發生
HorizontalPodAutoscaler衝突，您必須先刪除目標叢集中的現有HorizontalPodAutoscaler，再執行還原作業，才能建立備份的工作負載及其相關資源。請重試還原作業。如果還原作業持續失敗，請與 Cloud Customer Care 團隊聯絡，尋求進一步協助。
錯誤 200060202：工作負載驗證期間缺少 GKE 資源，因此無法完成還原作業
在還原作業的工作負載驗證階段，如果 Backup for GKE 預期要驗證的 GKE 資源在目標叢集中找不到，就會發生錯誤 200060202，並顯示下列錯誤訊息：
Workload Validation Error: [KIND] "[NAME]" not found
例如 Example: Workload Validation Error: pods "jenkins-0" not found。
當 GKE 備份功能在還原作業程序中，成功建立或更新 GKE 資源，但驗證階段開始時，一或多個 GKE 資源已不在目標叢集中，就會發生這個錯誤。這是因為資源在還原程序最初建立或更新後，但在 GKE 資源的工作負載驗證完成前遭到刪除。發生這類錯誤的可能原因如下：
手動刪除：使用者或管理員使用
kubectl或其他 Google Cloud 工具手動刪除資源。外部自動化：GitOps 控制器 (例如 Config Sync、ArgoCD、Flux、自訂指令碼或其他叢集管理工具) 還原或刪除了資源，以符合存放區中的所需狀態。
GKE 控制器：GKE 控制器刪除資源，是因為該資源與其他資源或政策衝突，或是
OwnerReference鏈結導致垃圾收集，或是 GKE 的自動清除程序在刪除依附資源的owner資源時，一併刪除依附資源。
如要解決這項錯誤，請按照下列說明操作：
如果還原作業無法完成，請使用顯示的錯誤訊息找出缺少的資源。
使用下列其中一種方法，找出資源所屬的命名空間：
GKE 稽核記錄：檢查您嘗試還原作業時產生的 GKE 稽核記錄。您可以篩選資源
Kind和Name的刪除作業記錄。稽核記錄項目包含原始命名空間。備份詳細資料：查看還原作業的範圍和備份內容。備份索引會顯示資源的原始命名空間。您也可以驗證
RestorePlan是否包含TransformationRule，其中指定了在所選命名空間中還原資源的規則。跨命名空間搜尋：執行
kubectl get指令，在所有命名空間中搜尋資源：kubectl get KIND --all-namespaces | grep NAME將
KIND和NAME替換為錯誤訊息中的值。如果資源仍存在，這項指令會顯示其命名空間。
執行
kubectl get指令，確認是否已刪除：kubectl get KIND NAME -n [NAMESPACE]將
KIND和NAME替換為錯誤訊息中的值。您應該會收到not found錯誤訊息。請使用下列其中一種方法，調查刪除原因：
GKE 稽核記錄：識別發出刪除要求的實體。例如使用者、服務帳戶或控制器。
檢查已設定的自動化程序：如果您使用 GitOps 或其他自動化工具，請檢查這些工具的記錄和狀態，確認是否干擾了還原的資源。
檢查相關事件：執行
kubectl get events指令，檢查所判斷命名空間中的 GKE 事件：kubectl get events -n NAMESPACE_NAME --sort-by='.lastTimestamp'將
NAMESPACE_NAME替換為命名空間的名稱。
根據上一步的結果，解決資源刪除的原因。例如暫停衝突的自動化作業、修正設定錯誤，或調整使用者權限。
請使用下列其中一種方法復原遺失的資源：
重新套用資訊清單檔案：如果遺漏的資源有資訊清單，可以重新套用至正確的命名空間。
執行精細還原：執行精細還原作業，從相同備份中選擇性還原遺失的資源，確保您指定正確的命名空間。如要進一步瞭解如何執行精細還原作業，請參閱「啟用精細還原功能」。
請重試還原作業。如果還原作業持續失敗，請與 Cloud Customer Care 團隊聯絡，尋求進一步協助。
錯誤 200060201：工作負載驗證逾時，因此無法完成還原作業
如果叢集中的資源建立完成後，一或多個還原的工作負載未在預期時間內完全 ready，就會發生錯誤 200060201，並顯示下列錯誤訊息：
Workload Validation Error: Timedout waiting for workloads to be ready - [namespace/workload_name, ...]
發生這項錯誤的原因是，GKE 備份功能會在還原 GKE 資源設定後執行驗證步驟，確保重要工作負載正常運作。GKE 備份服務會等待特定工作負載達到 ready 狀態，但至少有一個工作負載未在分配的逾時期間內，達到下列就緒條件：
針對
Pods：status.Phase為Running針對
Deployments：status.ReadyReplicas等於spec.Replicas針對
StatefulSets：status.ReadyReplicas等於spec.Replicas針對
DaemonSets：status.NumberReady等於status.DesiredNumberScheduled
如要解決這項錯誤，請按照下列說明操作：
找出錯誤訊息中未處於
ready狀態的工作負載。錯誤訊息會列出工作負載及其命名空間，這些工作負載無法進入ready狀態。執行
kubectl describe指令，檢查工作負載狀態，並取得失敗工作負載的詳細資料和事件：kubectl describe WORKLOAD_TYPE WORKLOAD_NAME -n NAMESPACE_NAME kubectl get pods -n NAMESPACE_NAME -l SELECTOR_FOR_WORKLOAD更改下列內容：
WORKLOAD_TYPE：工作負載類型，例如Deployment、StatefulSet或DaemonSet。WORKLOAD_NAME：特定工作負載例項的名稱。NAMESPACE_NAME：工作負載所在的命名空間。SELECTOR_FOR_WORKLOAD：標籤選取器，用於尋找與工作負載相關聯的Pods。例如：app=my-app。
如果是
Deployments或StatefulSets工作負載類型中的 Pod，請執行kubectl describe pod指令，檢查個別 Pod 的狀態：kubectl describe pod POD_NAME -n NAMESPACE_NAME更改下列內容：
POD_NAME：特定 Pod 的名稱。NAMESPACE_NAME：Pod 所在的命名空間。
在
Events區段中，分析describe輸出內容中的事件和記錄，並找出下列資訊：ImagePullBackOff / ErrImagePull：表示擷取容器映像檔時發生問題。CrashLoopBackOff：表示容器正在啟動並當機。
在
Containers區段中，分析describe輸出內容中的容器記錄，然後執行kubectl logs指令找出容器名稱：kubectl logs POD_NAME -n NAMESPACE_NAME -c CONTAINER_NAME更改下列內容：
POD_NAME：特定 Pod 的名稱。NAMESPACE_NAME：Pod 所在的命名空間。CONTAINER_NAME：Pod 內的容器名稱。
根據
describe輸出內容，Pod 可能不會顯示在資源輸出內容中，原因包括：就緒探測失敗：容器的就緒探測未成功。
資源問題：叢集中的 CPU、記憶體或其他資源不足，或已達到配額限制。
Init 容器問題：Init 容器發生故障，導致主要容器無法啟動。
設定錯誤：
ConfigMaps、Secrets或環境變數發生錯誤。網路問題：
Pods無法與必要服務通訊。
檢查 GKE 叢集資源，確保 GKE 叢集有足夠的節點容量、CPU 和記憶體，可執行還原的工作負載。在 Autopilot 叢集中，節點自動佈建可能需要額外時間，因此建議您檢查是否有任何節點擴充限制或錯誤。根據調查結果解決根本問題，並修正導致工作負載無法進入
ready狀態的問題。這類做法可能包括修正資訊清單、調整資源要求或限制、修正網路政策，或是確保符合依附元件需求。解決相關問題後，請等待工作負載進入
ready狀態。不需要再次執行還原作業。
如果問題仍未解決，請與 Cloud Customer Care 團隊聯絡，尋求進一步協助。
錯誤 200060102：磁碟區驗證錯誤，因此無法完成還原作業
發生 200060102 錯誤的原因是，在還原作業的磁碟區驗證階段，有一或多個 VolumeRestore 資源 (負責管理從 VolumeBackup 還原資料至 PersistentVolume 的程序) 進入 failed 或 deleting 狀態。如果磁碟區還原失敗，還原資源的 stateReason 欄位會顯示下列錯誤訊息：
Volume Validation Error: Some of the volume restores failed - [projects/PROJECT_ID/locations/LOCATION/restorePlans/RESTORE_PLAN_ID/restores/RESTORE_ID/volumeRestores/VOLUME_RESTORE_ID (PVC: NAMESPACE/PVC_NAME), ...]
錯誤訊息會列出失敗 VolumeRestore 的完整資源名稱，包括目標 PersistentVolumeClaim 名稱和命名空間。錯誤訊息指出，當 Backup for GKE 啟動 VolumeRestore 資源以從 VolumeBackups 佈建 PersistentVolumes 時，受影響 PersistentVolumeClaim 的資料還原程序未順利完成，且從快照建立基礎永久磁碟的作業失敗。VolumeRestore 失敗的原因如下：
配額不足：專案或區域中分配的永久磁碟配額不足，例如
SSD_TOTAL_GB。權限問題：Backup for GKE 使用的服務帳戶缺少建立磁碟或存取快照的必要權限。
網路問題：有暫時性或持續性網路問題，導致磁碟建立程序中斷。
無效快照：來源
VolumeBackup或基礎永久磁碟快照已損毀或無法存取。資源限制：其他叢集資源限制會阻礙磁碟區佈建。
內部錯誤：Persistent Disk 服務發生內部問題。
如要解決這項錯誤，請按照下列說明操作：
找出錯誤訊息中列出的失敗
PersistentVolumeClaims，其中列出失敗的VolumeRestore物件完整資源名稱。執行
gcloud beta container backup-restore volume-restores describe指令，取得每個失敗VolumeRestore資源的詳細資料：gcloud beta container backup-restore volume-restores describe VOLUME_RESTORE_ID \ --project=PROJECT_ID \ --location=LOCATION \ --restore-plan=RESTORE_PLAN_ID \ --restore=RESTORE_ID更改下列內容：
VOLUME_RESTORE_ID：失敗的VolumeRestore資源 ID。PROJECT_ID：您的 Google Cloud 專案 ID。LOCATION：還原的 Google Cloud 位置。RESTORE_PLAN_ID：還原計畫的 ID。RESTORE_ID：還原作業的 ID。
檢查輸出內容中的
state和stateMessage欄位，瞭解失敗的詳細資訊。執行
kubectl get pvc指令，檢查目標PersistentVolumeClaim的狀態：kubectl get pvc PVC_NAME -n NAMESPACE_NAME -o yaml更改下列內容：
PVC_NAME：資源的名稱。PersistentVolumeClaimNAMESPACE_NAME：PersistentVolumeClaim所在的命名空間。
確認輸出內容的
status.phase區段顯示Pending階段。這個階段表示PersistentVolumeClaim尚未繫結至PersistentVolume，如果VolumeRestore失敗，這是預期行為。檢查 YAML 輸出內容中的
Events區段，查看與佈建失敗相關的訊息，例如ProvisioningFailed：Cloud KMS error when using key projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/CRYPTO_KEY: Permission 'cloudkms.cryptoKeyVersions.useToEncrypt' denied on resource 'projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/CRYPTO_KEY' (or it may not exist).輸出內容指出，在磁碟建立期間存取加密金鑰時發生權限問題。如要提供存取金鑰的
compute service agent相關權限，請按照 GKE 備份說明文件中啟用 CMEK 加密的指示操作。在
PersistentVolumeClaim命名空間中查看 GKE 事件，方法是執行kubectl get events指令，即可取得來自PersistentVolume控制器或 CSI 驅動程式的詳細錯誤訊息：kubectl get events -n NAMESPACE_NAME --sort-by='.lastTimestamp'將
NAMESPACE_NAME替換為PersistentVolumeClaim的命名空間，找出與
PersistentVolumeClaim名稱相關的事件，其中包含FailedProvisioning或ExternalProvisioning等關鍵字。事件也可能包含儲存空間佈建程式的錯誤，例如pd.csi.storage.gke.io。在 Cloud Logging 中查看 Cloud 稽核記錄和 Persistent Disk 記錄，檢查磁碟建立作業在失敗前後是否有任何相關錯誤，藉此檢查 Persistent Disk 記錄。
根據產生的錯誤訊息，解決下列根本問題：
如果系統顯示
(QUOTA_EXCEEDED}: Quota SSD_TOTAL_GB exceeded等訊息，請提高永久磁碟配額。驗證並修正 IAM 權限。
調查並解決網路問題。
如要解決快照或 Persistent Disk 服務的問題，請與 Cloud Customer Care 團隊聯絡。
PersistentVolumeClaim仍處於Pending狀態。還原作業程序不會自動重試
VolumeRestore。如要解決這個問題，請針對使用受影響PersistentVolumeClaim的Deployment或StatefulSet工作負載觸發還原作業。使用精細還原功能，選擇性還原與失敗
PersistentVolumeClaim相關聯的Deployment或StatefulSet工作負載。如果根本問題已修正，這個方法可讓標準 GKE 機制再次處理PersistentVolumeClaim的建立和繫結程序。如要進一步瞭解精細還原功能，請參閱「啟用精細還原功能」。
如果問題仍未解決或 VolumeRestore 失敗的原因不明，請與 Cloud Customer Care 團隊聯絡，取得進一步協助。
錯誤 200060101：磁碟區驗證逾時，導致還原作業無法完成
當 Backup for GKE 停止等待時，還原作業的磁碟區驗證階段會發生 200060101 錯誤，因為至少有一個資源 (負責從 VolumeBackup 還原資料) 未在分配的逾時時間內達到 succeeded 狀態。VolumeRestore其他VolumeRestore資源也可能不完整。
Restore 資源的 stateReason 欄位中的錯誤訊息，會顯示在檢查逾時時，第一個不在 succeeded 狀態的 VolumeRestore 資源。其中包含特定 VolumeRestore 的目標 PersistentVolumeClaim 名稱和命名空間，例如：
Volume Validation Error: Timed out waiting for volume restore [projects/PROJECT_ID/locations/LOCATION/restorePlans/RESTORE_PLAN_NAME/restores/RESTORE_NAME/volumeRestores/VOLUME_RESTORE_ID (PVC: PVC_NAMESPACE/PVC_NAME)]
Backup for GKE 會啟動 VolumeRestore 資源，從 VolumeBackups 佈建 PersistentVolumes。這項錯誤表示從快照建立基礎永久磁碟，以及後續將 PersistentVolumeClaim 繫結至 PersistentVolume 的時間，都超過所引用 VolumeRestore 的計算逾時時間。同一項還原作業的其他 VolumeRestores 也可能處於未完成狀態。
即使從 Backup for GKE 的角度來看，已達到逾時時間，但上述 VolumeRestore 資源和可能 VolumeRestore 資源的基礎磁碟建立程序，可能仍在進行中或失敗。
如要解決這個問題，請按照下列指示操作：
在錯誤訊息中找出逾時的
PersistentVolumeClaim名稱和命名空間，例如(PVC: PVC_NAMESPACE/PVC_NAME)。執行
gcloud beta container backup-restore volume-restores list指令，列出與還原作業相關聯的所有VolumeRestores，查看目前的狀態：gcloud beta container backup-restore volume-restores list \ --project=PROJECT_ID \ --location=LOCATION \ --restore-plan=RESTORE_PLAN_NAME \ --restore=RESTORE_NAME更改下列內容：
PROJECT_ID： Google Cloud 專案的 ID。LOCATION：還原的 Google Cloud 位置。RESTORE_PLAN_NAME：還原計畫的名稱。RESTORE_NAME：還原作業的名稱。
找出不在
succeeded狀態的VolumeRestores。執行
gcloud beta container backup-restore volume-restores describe指令，取得錯誤中提及的VolumeRestore詳細資料，以及任何不在succeeded狀態的VolumeRestores：gcloud beta container backup-restore volume-restores describe VOLUME_RESTORE_ID \ --project=PROJECT_ID \ --location=LOCATION \ --restore-plan=RESTORE_PLAN_NAME \ --restore=RESTORE_NAME更改下列內容：
VOLUME_RESTORE_ID：VolumeRestore資源的 ID。PROJECT_ID：您的 Google Cloud 專案 ID。LOCATION：還原的 Google Cloud 位置。RESTORE_PLAN_NAME：還原計畫的名稱。RESTORE_NAME：還原作業的名稱。
檢查
state和stateMessage欄位。state欄位的值可能是creating或restoring。stateMessage欄位可能會提供更多背景資訊，並包含目標PersistentVolumeClaim詳細資料。執行
kubectl get pvc指令，檢查所識別目標的狀態：PersistentVolumeClaimskubectl get pvc PVC_NAME -n PVC_NAMESPACE -o yaml更改下列內容：
PVC_NAME：PersistentVolumeClaim的名稱。PVC_NAMESPACE：PersistentVolumeClaim的命名空間。
PersistentVolumeClaim'sstatus.phase的值可能為Pending。檢查「Events」部分是否有下列錯誤：Waiting for first consumer to be created before binding：表示StorageClass具有volumeBindingMode: WaitForFirstConsumer。系統會延遲佈建
PersistentVolume，直到建立並排定使用PersistentVolumeClaim的Pod為止。問題可能出在Pod排程，而非磁碟區佈建本身。因此，建議您確認Pods消耗PersistentVolumeClaim的Pods未排定或未開始的原因。FailedProvisioning或儲存空間佈建程式的錯誤： 例如pd.csi.storage.gke.io。
執行
kubectl get events指令，查看相關命名空間中的 GKE 事件：kubectl get events -n PVC_NAMESPACE --sort-by='.lastTimestamp'將
PVC_NAMESPACE替換為PersistentVolumeClaim的命名空間。尋找與
PersistentVolumeClaim名稱相關的事件，例如佈建訊息或錯誤。在 Cloud Logging 中查看 Cloud 稽核記錄和永久磁碟記錄。
監控
creating和restoring狀態中所有VolumeRestores的狀態。修正問題後，
VolumeRestores的狀態可以轉換為succeeded或failed狀態。如果VolumeRestores達到succeeded狀態，PersistentVolumeClaims應會變成Bound，且工作負載應可正常運作。如果任何VolumeRestore進入failed狀態，請執行疑難排解步驟，解決磁碟區驗證錯誤。詳情請參閱「錯誤 200060102：因磁碟區驗證錯誤而無法完成還原作業」。
如果 VolumeRestores 處於 creating 或 restoring 狀態的時間過長，請與 Cloud Customer Care 團隊聯絡，以取得進一步協助。