如何使用gcloud命令为服务账号添加自定义角色？（含报错排查）

问题重现 #

已创建服务账号name@project.iam.gserviceaccount.com和自定义角色mycustomrole，执行以下gcloud命令时收到INVALID_ARGUMENT错误：

gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:myserviceaccount@myproject.iam.gserviceaccount.com" \
  --role=projects/myproject/roles/mycustomrole \
  --verbosity=debug

错误信息：

ERROR: (gcloud.projects.add-iam-policy-binding) INVALID_ARGUMENT: The role name must be in the form "roles/{role}", "organizations/{organization_id}/roles/{role}", or "projects/{project_id}/roles/{role}".

测试过以下--role格式仍未解决：

--role=roles/mycustomrole
--role=projects/myproject/roles/mycustomrole
--role=projects/myproject/roles/customrole/mycustomrole

正确操作方法 #

1. 确认自定义角色的完整正确名称
   执行命令列出项目内所有自定义角色，获取目标角色的完整name字段值：

   gcloud iam roles list --project=my-project
   

   在输出中找到mycustomrole对应的name，格式应为projects/my-project/roles/mycustomrole（注意项目ID需与实际GCP项目ID完全一致，包括大小写、连字符等细节）。

2. 执行正确的绑定命令
   确保--role参数严格匹配查询到的完整角色名称，同时检查--member中的服务账号邮箱是否正确，最终命令示例：

   gcloud projects add-iam-policy-binding my-project \
     --member="serviceAccount:name@my-project.iam.gserviceaccount.com" \
     --role="projects/my-project/roles/mycustomrole"
   

常见排查点 #

• 项目ID拼写错误：命令中的项目ID必须和GCP控制台显示的完全一致，避免大小写、连字符等错误。
• 角色名称拼写错误：自定义角色名称区分大小写，需与创建时的名称完全匹配。
• 角色有效性验证：如果角色未正确创建，会导致无法识别，可通过以下命令验证角色是否存在：

  gcloud iam roles describe projects/my-project/roles/mycustomrole
  

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