排查 Backup for GKE 中的权限错误

Autopilot Standard

本页面介绍了您在使用 Backup for GKE 时可能会遇到的权限错误、执行操作时需要考虑的事项，以及如何解决相应错误。

错误 100010101：无法备份 PersistentVolumeClaim - 租户项目缺少 IAM 绑定

当尝试备份 PersistentVolumeClaim 因租户项目缺少 Identity and Access Management 绑定而失败时，会发生错误 100010101，导致显示错误消息 Failed to backup PersistentVolumeClaim - Missing IAM binding for tenant project。

Backup for GKE 会创建 GKE 集群的永久性磁盘的快照。快照位于您的 Google Cloud 项目（也称为使用方项目）中， Google Cloud 会在其管理的租户项目中创建快照。租户项目位于 google.com 组织内，与您自己的组织分开。

租户项目中的服务代理需要特定权限才能使用客户管理的加密密钥 (CMEK) 来加密集群的 PersistentVolumeClaim 所引用的永久性磁盘。此权限用于加密和解密快照数据。如果 service-TENANT_PROJECT_NUMBER@compute-system.iam.gserviceaccount.com 服务代理缺少磁盘的 CMEK 的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色，则备份操作会失败。

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

在 Google Cloud 控制台中验证您是否拥有足够的 IAM 权限来修改 Cloud Key Management Service 密钥的 IAM 政策，例如 roles/cloudkms.admin 或 roles/owner。
使用备份操作失败的 status reason 消息中的 TENANT_PROJECT_NUMBER 值，找到租户项目的 Compute Engine 服务代理。例如 service-TENANT_PROJECT_NUMBER@compute-system.iam.gserviceaccount.com。
找到用于加密永久性磁盘的以下 CMEK 信息：
- 密钥名称：加密密钥的名称。
- 密钥环：密钥所在的密钥环的名称。
- 位置：密钥所在的 Google Cloud 位置。例如 global 或 us-central1。
如需向租户项目的 Compute Engine 服务代理授予 CMEK 的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色，请使用 Google Cloud CLI 运行 gcloud kms keys add-iam-policy-binding 命令：
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --member "serviceAccount:service-TENANT_PROJECT_NUMBER@compute-system.iam.gserviceaccount.com" \
    --role roles/cloudkms.cryptoKeyEncrypterDecrypter
```
替换以下内容：
- KEY_NAME：加密密钥的名称。
- KEY_RING：密钥环的名称。
- LOCATION：密钥的 Google Cloud 位置。例如 global 或 us-central1。
- TENANT_PROJECT_NUMBER：从备份操作失败的 status reason 消息中获取的租户项目编号。
如果该命令成功运行，则输出如下所示：
```
- members:
- serviceAccount:service-987654321098@compute-system.iam.gserviceaccount.com
role: roles/cloudkms.cryptoKeyEncrypterDecrypter
```
重新测试备份操作。如果该操作仍未成功，请与 Cloud Customer Care 联系以获取进一步帮助。

错误 100010104：无法备份 PersistentVolumeClaim - 创建快照时违反了组织政策限制条件

当尝试备份 PersistentVolumeClaim 时因创建快照期间违反了组织政策限制条件而失败，会发生错误 100010104，导致显示错误消息 Failed to backup PersistentVolumeClaim - Org policy constraint violation while creating snapshot。

Backup for GKE 会创建 GKE 集群的永久性磁盘的快照。快照位于您的 Google Cloud 项目（也称为使用方项目）中，并在由 Google Cloud管理的租户项目中创建。租户项目位于 google.com 组织内，与您自己的组织分开。

组织政策规定了您可以在何处创建存储资源。Constraint constraints/compute.storageResourceUseRestrictions violated 错误表示资源或快照违反了政策，因为它们是在不属于允许的组织结构的租户项目中创建的。由于租户项目位于 Google 的组织内，因此不在您定义的政策范围内，这会导致备份失败。

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

找到实施 constraints/compute.storageResourceUseRestrictions 限制条件的组织政策。如需详细了解如何使用 Google Cloud 控制台查看组织政策，请参阅查看组织政策。
修改 constraints/compute.storageResourceUseRestrictions 政策，以将 Backup for GKE 使用的 folders/77620796932 租户项目文件夹纳入其许可清单。

注意：请确保将指定的文件夹 ID 添加到允许的位置列表中，以允许 Backup for GKE 在其租户项目中创建快照，即使这些项目位于您的组织层次结构之外也是如此。
将文件夹添加到许可清单后，保存政策更改。
在组织政策更新并传播（通常需要几分钟）后，重新测试备份操作。备份应在不违反存储资源使用限制的情况下进行。如果操作仍未成功，请与 Cloud Customer Care 联系以获取进一步帮助。

错误 100010106：无法备份 PersistentVolumeClaim - Backup for GKE 服务代理缺少 IAM 绑定

当尝试备份 PersistentVolumeClaim 因 Backup for GKE 服务代理缺少 Identity and Access Management 绑定而失败时，会发生错误 100010106，导致显示错误消息 Failed to backup PVC - Missing IAM binding for Backup for GKE service agent。

Backup for GKE 需要拥有使用 BackupPlan 的客户管理的加密密钥 (CMEK) 来加密和解密卷永久性磁盘的权限。如果 Backup for GKE 服务代理缺少 BackupPlan CMEK 的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色，则备份操作会失败。

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

确定您的项目特有的 Google 管理的 Backup for GKE 服务代理。例如 service-PROJECT_NUMBER@gcp-sa-gkebackup.iam.gserviceaccount.com。您可以使用以下方法查找项目编号：
- 使用 Google Cloud 控制台中的 Google Cloud 项目信息中心。
- 使用 Google Cloud CLI 运行 gcloud projects describe 命令：
```
gcloud projects describe PROJECT_ID –format="value(projectNumber)"
```
  将 PROJECT_ID 替换为您的项目的唯一名称。
确定以下 CMEK 详细信息：
- 密钥名称：加密密钥的名称。
- 密钥环：密钥所在的密钥环的名称。
- 位置：BackupPlan CMEK 所在的 Google Cloud 位置。例如 global 或 us-central1。
如需向 Backup for GKE 服务代理授予 CMEK 的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色，请使用 Google Cloud CLI 运行 gcloud kms keys add-iam-policy-binding 命令：
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --member "serviceAccount:service-PROJECT_NUMBER@gcp-sa-gkebackup.iam.gserviceaccount.com" \
    --role roles/cloudkms.cryptoKeyEncrypterDecrypter
```
替换以下内容：
- KEY_NAME：加密密钥的名称。
- KEY_RING：密钥环的名称。
- LOCATION：密钥的 Google Cloud 位置。例如 global 或 us-central1。
- PROJECT_NUMBER：您的 Google Cloud 项目编号。
验证您是否拥有 Cloud Key Management Service 密钥所需的 Identity and Access Management 权限。例如 roles/cloudkms.admin 或 roles/owner。
验证您是否拥有已授予的权限。在上一个 gcloud kms keys add-iam-policy-binding 命令的输出中，查找类似于以下内容的条目：
```
-members:
-serviceAccount:service-123456789012@gcp-sa-gkebackup.iam.gserviceaccount.com
role: roles/cloudkms.cryptoKeyEncrypterDecrypter
```
授予必要权限后，重新测试备份操作。如果操作未成功完成，请与 Cloud Customer Care 联系以获取进一步帮助。

错误 100010107：无法备份 PersistentVolumeClaim - 缺少 IAM 绑定 - 代理服务账号 (KCP)

当您尝试执行 Backup for GKE 备份操作，但 Google Kubernetes Engine 集群服务代理无权访问客户管理的加密密钥 (CMEK) 时，会发生错误 100010107，导致显示消息 Failed to backup PVC - Missing IAM binding - agent service account (KCP)。

Google Kubernetes Engine 集群服务代理（通常采用 service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com 格式）对于 GKE 集群与 Google Cloud服务交互至关重要。当备份方案使用客户管理的加密密钥 (CMEK) 时。此服务代理需要拥有使用您的 CMEK 加密和解密备份数据的权限。如果备份方案缺少 CMEK 的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色，则从集群启动的备份操作会失败并显示 permission denied 错误。

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

验证您是否拥有修改 Cloud Key Management Service 密钥的 IAM 政策的适当权限。例如，cloudkms.admin 或 roles/owner。
确定 Google Kubernetes Engine 集群服务代理。此服务代理由 Google Cloud 为 GKE 集群自动创建和管理。例如 service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com。您需要项目编号才能组成完整的服务账号。您可以使用以下方法之一查找项目编号：
- 使用 Google Cloud 控制台中的 Google Cloud 项目信息中心。
- 使用 Google Cloud CLI 运行 gcloud projects describe 命令：
```
gcloud projects describe PROJECT_ID –-format="value(projectNumber)"
```
  将 PROJECT_ID 替换为您的项目 ID。
找到以下 CMEK 信息：
- 密钥名称：加密密钥的名称。
- 密钥环：密钥所在的密钥环的名称。
- 位置：密钥所在的 Google Cloud 位置。例如 global 或 us-central1。
在 CMEK 级层授予 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色。Google Kubernetes Engine 服务代理需要拥有加密密钥的权限。如需授予 CMEK 的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色，请使用 Google Cloud CLI 运行 gcloud kms key add-iam-policy-binding 命令：
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring KEY_RING \
    --location LOCATION \
    --member "serviceAccount:service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com" \
    --role roles/cloudkms.cryptoKeyEncrypterDecrypter
```
替换以下内容：
- KEY_NAME：加密密钥的名称。
- KEY_RING：密钥环的名称。
- LOCATION：密钥的 Google Cloud 位置。例如 global 或 us-central1。
- PROJECT_NUMBER：项目的名称。
输出类似于以下内容：
```
 - members:
 - serviceAccount:service-123456789012@container-engine-robot.iam.gserviceaccount.com
 role: roles/cloudkms.cryptoKeyEncrypterDecrypter
 ```
```
重新尝试 Backup for GKE 操作。如果操作仍失败，请与 Cloud Customer Care 联系以获取进一步帮助。

错误 100020101：无法备份 PersistentVolumeClaim - PersistentVolumeClaim 绑定到不受支持的 PersistentVolume 类型

当尝试备份 PersistentVolumeClaim 因 PersistentVolumeClaim 绑定到不受支持的 PersistentVolume 类型而失败时，会发生错误 100020101。此错误会导致以下错误消息：PersistentVolumeClaims are bound to PersistentVolumes of unsupported types and cannot be backed up.。

当 Backup for GKE 操作遇到绑定到使用以下卷类型的 PersistentVolume 的 PersistentVolumeClaim 时，会发生此错误：Backup for GKE 不支持使用该卷类型进行数据备份。Backup for GKE 主要支持备份永久性磁盘卷中的数据。如果 PersistentVolumeClaim 绑定到不是永久性磁盘的 PersistentVolume，则 PersistentVolumeClaim 的数据备份操作会失败。

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

通过运行 kubectl get pvc 命令，列出所有 PersistentVolumeClaims 以及与其绑定的 PersistentVolumes。查看此列表，以确定由不受支持的卷类型提供支持的 PersistentVolumes。
```
kubectl get pvc --all-namespaces -o wide
```
通过运行 kubectl describe pv 命令，确定由 Backup for GKE 不支持的卷类型提供支持的 PersistentVolume 的卷类型：
```
kubectl describe pv PERSISTENT_VOLUME_NAME
```
替换以下内容：

PERSISTENT_VOLUME_NAME：在上一步的输出中，以列 VOLUME 形式列出的具有不受支持的卷类型的 PersistentVolume 的名称。

在输出中，使用 Source 和 Driver 字段获取卷预配工具详细信息：
- 对于受支持的永久性磁盘：输出类似于 Source.Driver: pd.csi.storage.gke.io 或 Source.Type:GCEPersistentDisk。
- 对于导致错误的不受支持类型：输出为非永久性磁盘驱动程序，例如 Source.Driver:filestore.csi.storage.gke.io。
请使用以下方法之一来解决此错误：
- 迁移到永久性磁盘卷：我们建议使用此方法进行完整数据备份。如果您需要备份实际的卷数据，则必须使用永久性磁盘，这需要将数据从不受支持的卷类型迁移到新的永久性磁盘 CSI 卷。如需迁移永久性磁盘卷方面的帮助，请与 Cloud Customer Care 联系。
- 在 Backup for GKE 中启用宽容模式：如果不需要为不受支持的卷备份数据，我们建议使用此方法。如果迁移数据不可行或不必要（例如，如果卷由外部服务提供支持，并且您计划在恢复操作期间重新挂接该卷），您可以将 Backup for GKE 备份方案配置为允许在宽容模式下继续进行备份。如需详细了解如何启用宽容模式，请参阅对备份方案启用宽容模式。
重新尝试 Backup for GKE 操作。根据您选择的错误解决方法，Backup for GKE 操作的行为如下：
- 如果您已迁移到永久性磁盘卷，则该卷（包括其数据）备份应该会成功。
- 如果您启用了宽容模式，则备份操作应该会成功，但系统不会备份不受支持的卷的数据。

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

错误 100020104：无法备份 PersistentVolumeClaim - PersistentVolumeClaim 未绑定到 PersistentVolume

当尝试备份 PersistentVolumeClaim 因 PersistentVolumeClaim 未绑定到 PersistentVolume 而失败时，会发生错误 100020104。此错误会导致以下错误消息：Failed to backup PVC - PVC Not Bound to a Persistent Volume。

如果 Backup for GKE 操作尝试备份未成功绑定到 PersistentVolume 的 PersistentVolumeClaim，则会发生此错误。 PersistentVolumeClaim 必须绑定到 PersistentVolume，然后才能供使用方工作负载（例如 Pod）使用，并随后由 Backup for GKE 备份。如果 PersistentVolumeClaim 保持 Pending 状态，则表示没有合适的 PersistentVolume 可用，或者无法预配或绑定它，这会导致备份操作失败。PersistentVolumeClaim 保持未绑定的一个常见原因是，其关联的 StorageClass 使用 WaitForFirstConsumer 绑定模式，但尚无 Pod 或其他工作负载尝试使用 PersistentVolumeClaim。

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

如需检查集群中所有 PersistentVolumeClaims 的状态并确定未绑定的 PersistentVolumeClaim，请运行 kubectl get pvc 命令：
```
kubectl get pvc --all-namespaces | grep `Pending`
```
确定未绑定到 PersistentVolume 的 PersistentVolumeClaim 后，运行 kubectl describe pvc 命令，以检索有关未绑定 PersistentVolumeClaim 的信息：
```
kubectl describe pvc PVC_NAME -n NAMESPACE_NAME
```
替换以下内容：
- PVC_NAME：未能备份的 PersistentVolumeClaim 的名称。
- NAMESPACE_NAME：PersistentVolumeClaim 所在的命名空间的名称。
显示说明后，使用 Status 和 Events 字段确定 PersistentVolumeClaim 是否绑定到 PersistentVolume。如果您仍然无法确定 PersistentVolumeClaim 未绑定到 PersistentVolume 的原因，或者无法解决已发现的问题，可以在备份方案中启用宽容模式。如需详细了解如何启用宽容模式，请参阅对备份方案启用宽容模式。

后续步骤

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