[DOC] Fix missing GCP IAM permissions for workspace creation (#5114) (#5123)

## Changes
<!-- Summary of your changes that are easy to understand -->

Add PSC/CMK-related permissions to GCP workspace creation guides.

This fixes workspace creation failures caused by missing permissions:
- 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


## Tests
<!--
How is this tested? Please see the checklist below and also describe any
other relevant tests
-->

- [ ] `make test` run locally
- [x] relevant change in `docs/` folder
- [ ] covered with integration tests in `internal/acceptance`
- [ ] using Go SDK
- [ ] using TF Plugin Framework
- [x] has entry in `NEXT_CHANGELOG.md` file

Author: alexott

NEXT_CHANGELOG.md

@@ -17,6 +17,8 @@
 
 ### Documentation
 
+* Fix missing GCP IAM permissions for workspace creation in GCP guides ([#5123](https://github.com/databricks/terraform-provider-databricks/pull/5123)).
+
 ### Exporter
 
 ### Internal Changes

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",
   ]
 }