GCP自定义角色已删除，无法通过gcloud恢复及重建问题求助

问题背景 #

在某GCP项目中，Terraform管理的自定义角色被外部删除后，尝试通过Terraform apply或gcloud命令重建时，出现以下错误：

Error: Error creating the custom project role projects/project-id/roles/gcsManageNotifications: googleapi: Error 400: You can't create a role_id (gcsManageNotifications) which has been marked for deletion., failedPrecondition

同时执行以下命令均无有效结果：

# 尝试恢复角色
$ gcloud iam roles undelete cdnInvalidateCache --project project-id
ERROR: (gcloud.iam.roles.undelete) NOT_FOUND: The role named projects/project-id/roles/cdnInvalidateCache was not found.

# 查看已删除角色
$ gcloud iam roles list --project project-id --show-deleted
Listed 0 items.

相同Terraform配置在其他项目可正常运行，且未手动删除该项目的自定义角色。

排查与解决步骤 #

1. 角色ID的保留期限制 #

GCP自定义角色删除后，角色ID会进入7天左右的保留锁定期，这段时间内系统不允许复用相同ID，即使--show-deleted无法查到记录，内部仍会标记该ID处于删除状态。

处理方式：

• 临时修改Terraform配置中的role_id（例如改为gcsManageNotifications-v2），先完成权限部署；
• 若必须立即使用原ID，通过GCP控制台提交支持工单，申请提前释放该角色ID的锁定。

2. 项目元数据同步延迟 #

个别项目可能存在IAM元数据同步延迟，导致角色删除状态未正确更新。

处理方式：

• 执行gcloud projects get-iam-policy project-id检查是否有残留的角色绑定引用，清理后等待15分钟再尝试重建；
• 刷新IAM服务同步：

gcloud services disable iam.googleapis.com && gcloud services enable iam.googleapis.com

注意：此操作会短暂影响IAM服务，需在业务低峰期执行

3. Terraform状态文件冲突 #

如果Terraform状态文件中仍保留该角色的记录，可能导致重建时的状态冲突。

处理方式：

• 移除状态文件中的残留角色记录：

terraform state rm google_project_role.gcs_manage_notifications  # 替换为你的资源名称

• 重新执行terraform init和terraform apply

4. GCP服务端状态异常 #

若以上方法均无效，大概率是GCP IAM服务端存在状态不同步的bug。

处理方式：

• 提交GCP支持工单，提供以下信息：
  • 项目ID、角色ID
  • 完整的错误日志截图/文本
  • 已执行的排查步骤
    请求工程师排查并修复角色ID的锁定状态。

内容的提问来源于stack exchange，提问作者piotrekkr