docs: Fix missing GCP IAM permissions for workspace creation (#5114)

Add critical iam.serviceAccounts.list permission and PSC/CMK-related
permissions to GCP workspace creation guides.

This fixes workspace creation failures caused by missing permissions:
- Added iam.serviceAccounts.list (critical for workspace creation)
- Added compute.forwardingRules.get and .list (for Private Service Connect)
- Added cloudkms.cryptoKeys permissions as commented examples (for CMK)
- Reorganized permissions with descriptive comments
- Added clarifying note to PSC guide

Resolves #5114

Author: alexott

NEXT_CHANGELOG.md

@@ -11,6 +11,7 @@
 ### Documentation
 
 * Document `git_email` in `databricks_git_credential` resource ([#5099](https://github.com/databricks/terraform-provider-databricks/pull/5099))
+* Fix missing GCP IAM permissions for workspace creation in GCP guides ([#5123](https://github.com/databricks/terraform-provider-databricks/pull/5123)).
 
 ### Exporter
 

docs/guides/gcp-private-service-connect-workspace.md

@@ -12,6 +12,8 @@ Secure a workspace with private connectivity and mitigate data exfiltration risk
 
 To work with Databricks in GCP in an automated way, please create a service account and manually add it in the [Accounts Console](https://accounts.gcp.databricks.com/users) as an account admin. Databricks account-level APIs can only be called by account owners and account admins, and can only be authenticated using Google-issued OIDC tokens. The simplest way to do this would be via [Google Cloud CLI](https://cloud.google.com/sdk/gcloud). For details, please refer to [Provisioning Databricks workspaces on GCP](gcp-workspace.md).
 
+-> **Note** When using Private Service Connect, ensure that your service account has the `compute.forwardingRules.get` and `compute.forwardingRules.list` permissions in addition to the base permissions listed in the [gcp-workspace.md](gcp-workspace.md) guide. These permissions are required for managing VPC endpoints.
+
 ## Creating a VPC network
 
 The very first step is VPC creation with the necessary resources. Please consult [main documentation page](https://docs.gcp.databricks.com/administration-guide/cloud-configurations/gcp/customer-managed-vpc.html) for **the most complete and up-to-date details on networking**. A GCP VPC is registered as [databricks_mws_networks](../resources/mws_networks.md) resource.

docs/guides/gcp-workspace.md

@@ -55,28 +55,41 @@ resource "google_project_iam_custom_role" "workspace_creator" {
   role_id = "${var.prefix}_workspace_creator"
   title   = "Databricks Workspace Creator"
   permissions = [
-    "iam.serviceAccounts.getIamPolicy",
-    "iam.serviceAccounts.setIamPolicy",
-    "iam.serviceAccounts.create",
-    "iam.serviceAccounts.get",
+    # IAM Role Management
     "iam.roles.create",
     "iam.roles.delete",
     "iam.roles.get",
     "iam.roles.update",
+    # Service Account Management
+    "iam.serviceAccounts.create",
+    "iam.serviceAccounts.get",
+    "iam.serviceAccounts.getIamPolicy",
+    "iam.serviceAccounts.setIamPolicy",
+    # Project Management
     "resourcemanager.projects.get",
     "resourcemanager.projects.getIamPolicy",
     "resourcemanager.projects.setIamPolicy",
+    # Service Usage
     "serviceusage.services.get",
     "serviceusage.services.list",
     "serviceusage.services.enable",
+    # Network Management
     "compute.networks.get",
     "compute.networks.updatePolicy",
     "compute.projects.get",
     "compute.subnetworks.get",
     "compute.subnetworks.getIamPolicy",
     "compute.subnetworks.setIamPolicy",
+    # Firewall Management
     "compute.firewalls.get",
     "compute.firewalls.create",
+    # Private Service Connect (required if using PSC)
+    "compute.forwardingRules.get",
+    "compute.forwardingRules.list",
+    # Customer-Managed Keys (required if using CMK)
+    # Uncomment these if you plan to use customer-managed encryption keys:
+    # "cloudkms.cryptoKeys.getIamPolicy",
+    # "cloudkms.cryptoKeys.setIamPolicy",
   ]
 }