如何为GCP服务账号分配权限解决Terraform CreateFolder 403报错

这个报错由两类原因触发：一是Terraform调用GCP API的令牌授权范围不足，二是服务账号缺少组织层级的文件夹创建权限，按以下步骤操作即可解决：

1. 修复API授权范围不足问题 #

报错中明确返回ACCESS_TOKEN_SCOPE_INSUFFICIENT，说明当前Terraform使用的访问令牌没有覆盖资源管理器API的调用范围，优先修复这个配置：

• 如果你使用服务账号JSON密钥做认证，在Terraform的Google Provider配置块中显式添加Cloud Platform全访问范围，参考配置：

provider "google" {
  credentials = file("/path/to/your/service-account-private-key.json")
  # 必须声明该scope，否则默认令牌范围不包含组织资源操作权限
  scopes = ["https://www.googleapis.com/auth/cloud-platform"]
}

• 如果你在GCE/GKE/Cloud Shell等GCP托管环境中绑定服务账号运行Terraform，需要先修改对应运行环境的服务账号访问范围，将Cloud Resource Manager权限设置为完全访问，或者直接在上述provider配置中强制指定scope。

2. 分配文件夹创建所需IAM权限 #

创建组织根节点下的文件夹，权限必须绑定在组织层级，在项目/子文件夹层级绑定权限不会生效：

• 使用组织管理员账号打开GCP控制台，进入「IAM与管理」-「IAM」页面
• 顶部资源选择器切换到对应组织（ID为报错信息中organizations/后的字符串）
• 点击「授予访问权限」，主体选择Terraform使用的服务账号，按需绑定对应角色：
  • 最小权限选择：roles/resourcemanager.folderCreator（仅包含文件夹创建权限，符合最小权限原则）
  • 如果后续需要管理组织下的其他资源，可选择绑定roles/resourcemanager.organizationAdmin（组织管理员角色，权限范围更大）
• 也可以直接通过gcloud CLI完成权限绑定，执行命令：

gcloud organizations add-iam-policy-binding 替换为你的组织ID \
  --member="serviceAccount:替换为你的服务账号邮箱地址" \
  --role="roles/resourcemanager.folderCreator"

3. 生效验证 #

配置完成后先执行terraform init --upgrade重载provider配置，再执行terraform plan确认无权限报错。

注意：GCP IAM权限生效存在1-2分钟延迟，如果刚配置完仍返回403，等待2分钟后重试即可，无需重复绑定权限。

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