排查 Backup for GKE 中的系统错误

Autopilot Standard

本页面介绍了您在使用 Backup for GKE 时可能会遇到的系统相关错误、备份资源时需要考虑的事项，以及问题排查步骤。

错误 100010108：无法备份 PersistentVolumeClaim - 加密磁盘缺少备份方案 CMEK

创建区域级卷备份时出现错误 100010108，并且由于 GKE 集群引用了加密磁盘，因此必须使用备份方案 CMEK。

了解错误

创建区域级范围的卷备份时，如果 GKE 集群引用了任何加密磁盘，则必须使用备份方案 CMEK。对于区域级卷备份，这是一项严格的要求；如果源磁盘已加密，则只有在提供备份方案 CMEK 的情况下，才能为该磁盘创建快照。如果您的备份方案缺少此 CMEK 配置，快照创建操作将会失败，并且您会看到类似如下的出错提示：

failed to create snapshot as disk "pvc-1" is encrypted with CMEK "projects/proj1/locations/us-east1/keyRings/keyring1/cryptoKeys/key1/cryptoKeyVersions/1", but no Backup Plan CMEK is provided. Please add CMEK to the Backup Plan.

问题排查步骤

1. 确定缺失的 CMEK 配置：出错提示确认正在备份的 PVC 已加密，但备份方案配置缺少加密密钥。
2. 向备份计划添加 CMEK：更新备份计划配置，以添加客户管理的加密密钥 (CMEK)。此密钥将用于加密备份数据，包括区域范围的卷备份。
3. 确保权限正确无误：验证 Backup for GKE 服务代理 ([e-mail]) 是否已获分配新添加的 CMEK 的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色。
4. 重新测试备份操作：使用 CMEK 更新备份方案并授予权限后，重试备份操作。

错误 100020102：CustomResourceDefinition - 具有无效的架构 - 不支持 v1beta1 API 版本

当尝试备份最初以 apiextensions.k8s.io/v1beta1 版本应用的 CustomResourceDefinition 时，如果因缺少 apiextensions.k8s.io/v1 API 版本中所需的结构化架构而失败，则会发生错误 100020102。此错误会导致以下错误消息：CustomResourceDefinition - has an invalid schema. The resource was originally applied as v1beta1, which has been removed from Kubernetes 1.22+。

出现此错误的原因是 apiextensions.k8s.io/v1beta1 API 版本已在 Google Kubernetes Engine 1.22 版中被移除。如需详细了解 GKE 1.22 版中移除的 API，请参阅 GKE v1.22 中移除的 API。

非宽容模式下的备份操作行为

在非宽容模式或严格备份方案中，如果备份操作遇到无法备份的资源（例如使用 v1beta1 API 创建的 CustomResourceDefinition），则备份操作会失败。出现此错误是因为资源缺少 v1 API 所需的结构化架构。如果存在此 CustomResourceDefinition，则会被视为严重错误，因为它可能无法正确恢复到较新的集群。

如需解决此错误，请按照以下说明操作：

1. 运行 kubectl get crd 命令，找出有问题的 CustomResourceDefinition：

   kubectl get crd CRD_NAME
   

   将 CRD_NAME 替换为错误消息中的 CustomResourceDefinition 的名称。

2. 在 YAML 输出中，通过查找以下条件来确认 CustomResourceDefinition 是否已从 vbeta1 API 正确转换为 v1 API：

   1. spec.versions：通过查看 spec.versions 字段下列出的每个版本，找到 spec.versions 条件。如果任何 spec.versions 缺少 schema.openAIV3Schema 字段，则表示 CustomResourceDefinition 没有为相应版本定义结构化架构。

   2. status.conditions：通过查找 type:NonStructuralSchema 条件来找到 status.conditions 条件。如果 status.conditions 的 status 为 true，则表明该架构不是结构化架构。

3. 按照以下步骤将 CustomResourceDefinition 升级到 v1 API 版本：

   1. 通过添加结构化架构来修改现有 CustomResourceDefinition，使其与 v1 标准兼容，该架构定义了自定义资源的每个字段及其类型。如需详细了解如何添加结构化架构，请参阅指定结构化架构。

   2. 将兼容的 v1 清单应用到您的集群。

      注意：在某些情况下，您可能需要删除之前创建的缺少结构化架构的 CustomResourceDefinition，并重新应用 v1 版本，以便 API 服务器正确处理资源惯例。

4. 如果升级成功，请重新尝试备份操作。否则，请使用以下方法之一来解决此问题：

   • 如果集群中未使用 CustomResourceDefinition，请运行 kubectl delete crd 命令删除 CustomResourceDefinition。

     注意： 如果 CustomResourceDefinition 正在集群中供现有自定义资源使用，则不应尝试删除该条目。您需要再次尝试将 CustomResourceDefinition 升级到 v1 API 版本，或者启用宽容模式。

     kubectl delete crd CRD_NAME
     

     将 CRD_NAME 替换为您要删除的 CustomResourceDefinition 的名称。

   • 对备份方案启用宽容模式，这样一来，Backup for GKE 便可跳过资源（包括 v1beta1 API 版本中的 CustomResourceDefinitions），并继续执行其余的备份操作。如需详细了解如何启用宽容模式，请参阅对备份方案启用宽容模式。

     警告：有问题的 CustomResourceDefinition 及其关联的自定义资源不会被备份，也不会包含在恢复中。如需成功恢复此类备份，您需要从恢复中排除使用 CustomResourceDefinition 的资源，或者在开始恢复之前在目标集群中创建 CustomResourceDefinition。

5. 重新尝试备份操作。如果操作仍失败，请与 Cloud Customer Care 联系以获取进一步帮助。

错误 100020103：未能查询 API 资源

当 Backup for GKE 在执行备份之前未能发现自定义或聚合的 Kubernetes API 服务时，会发生错误 100020103，导致显示错误消息 Failed to query API resources. Please check if any API service is unavailable by using 'kubectl get apiservice'。如果聚合 API 服务配置错误，或者其支持服务和 pod 不正常或无法访问，就会发生这种情况。在非宽容模式或严格备份方案中，如果 Backup for GKE 遇到不可用的 APIService，则会停止备份操作，以避免捕获不完整或不一致的集群状态。

如需解决此错误，请按照以下说明操作：

1. 运行以下命令，确定不可用的 API 服务：

   kubectl get apiservice
   

   在输出中，查找 AVAILABLE 列为 False 的 API 服务。

2. 运行以下命令，检查失败的 APIService 的详细信息：

   kubectl describe apiservice APISERVICE_NAME
   

   将 APISERVICE_NAME 替换为失败的 API 服务的名称，例如 v1beta1.custom.metrics.k8s.io。

   在输出中，查看 spec.service 下的 Service 字段和 Conditions 部分，以确定后备服务、其命名空间和故障原因（例如缺少端点或目标端口无法访问）。

3. 请使用以下方法之一来解决此错误：

   • 恢复支持性服务：运行以下命令，验证支持性服务是否具有就绪端点：

     kubectl get endpoints -n NAMESPACE SERVICE_NAME
     

     替换以下内容：

     • NAMESPACE：支持性服务的命名空间。
     • SERVICE_NAME：支持性服务的名称。

     验证支持该服务的 Pod 是否存在且处于 Running 状态。解决任何导致流量无法到达后端服务的崩溃的 Pod、映像拉取失败或网络政策配置错误。

   • 删除孤立的 APIService：如果 APIService 属于已移除或不再使用的应用、运算符或监控工具，请删除过时的 APIService：

     kubectl delete apiservice APISERVICE_NAME
     

     将 APISERVICE_NAME 替换为孤立 API 服务的名称。

     警告： 请勿删除集群中工作负载或控制器所依赖的有效 APIService，因为这可能会导致集群管理和自定义资源查询中断。

   • 启用宽容模式：如果您无法立即修复或移除不可用的 API 服务，请在备份方案中启用宽容模式。启用宽容模式后，Backup for GKE 会继续执行备份操作。不过，属于不可用 API 组的资源将不会备份。如需详细了解如何启用宽容模式，请参阅对备份方案启用宽容模式。

4. 重新尝试备份操作。如果操作仍失败，请与 Cloud Customer Care 联系以获取进一步帮助。

错误 100040102：未找到命名空间

尝试执行备份操作失败时，发生错误 100040102，该错误表明无法在集群内找到在备份范围中指定的命名空间。Backup for GKE 代理无法找到在 BackupPlan 配置的 selectedNamespaces 字段中明确列出的一个或多个命名空间。Backup for GKE 要求在启动备份操作时，所有指定的命名空间都必须存在于集群中。如果找不到命名空间，则会出现以下错误消息：

Namespace [NAMESPACE_NAME] is not found.

如需解决此问题，请按照以下说明操作：

1. 通过检查 BackupPlan 配置中的 selectedNamespaces 列表，验证命名空间是否已正确输入。

2. 运行 kubectl get namespace 命令，确认错误消息中报告的命名空间是否存在：

   kubectl get namespace NAMESPACE_NAME
   

   将 NAMESPACE_NAME 替换为错误消息中报告的命名空间的名称。

   如果命名空间不存在，系统会显示一条消息，指出未找到该命名空间，例如 Error from server (NotFound): namespaces "[NAMESPACE_NAME]" not found。

3. 更正 BackupPlan。如果命名空间拼写有误，请使用正确的命名空间名称更新 BackupPlan。如果命名空间确实已不存在，且无需备份，请将其从 BackupPlan 配置的 selectedNamespaces 列表中移除。

4. 在对 BackupPlan 进行必要的更正后，重新尝试备份操作并启动新的备份。

如果操作仍失败，请与 Cloud Customer Care 联系以获取进一步帮助。

后续步骤

• 阅读“Backup for GKE 错误代码概览”页面。