Clean up IAM Scopes in the documentation (#4321) (#2801)

* remove unneeded scopes

Co-authored-by: upodroid <cy@borg.dev>

* apply suggestions

* typo fix

Signed-off-by: Modular Magician <magic-modules@google.com>

.changelog/4321.txt

@@ -0,0 +1,3 @@
+```release-note:none
+
+```

website/docs/d/service_account_access_token.html.markdown

@@ -20,7 +20,7 @@ To allow `service_A` to impersonate `service_B`, grant the [Service Account Toke
 
 In the IAM policy below, `service_A` is given the Token Creator role impersonate `service_B`
 
-```sh
+```hcl
 resource "google_service_account_iam_binding" "token-creator-iam" {
 	service_account_id = "projects/-/serviceAccounts/service_B@projectB.iam.gserviceaccount.com"
 	role               = "roles/iam.serviceAccountTokenCreator"
@@ -70,7 +70,7 @@ output "target-email" {
 The following arguments are supported:
 
 * `target_service_account` (Required) - The service account _to_ impersonate (e.g. `service_B@your-project-id.iam.gserviceaccount.com`)
-* `scopes` (Required) - The scopes the new credential should have (e.g. `["storage-ro", "cloud-platform"]`)
+* `scopes` (Required) - The scopes the new credential should have (e.g. `["cloud-platform"]`)
 * `delegates` (Optional) - Delegate chain of approvals needed to perform full impersonation. Specify the fully qualified service account name.  (e.g. `["projects/-/serviceAccounts/delegate-svc-account@project-id.iam.gserviceaccount.com"]`)
 * `lifetime` (Optional) Lifetime of the impersonated token (defaults to its max: `3600s`).
 

website/docs/guides/version_2_upgrade.html.markdown

@@ -172,13 +172,11 @@ To have resources at different API versions, set up provider blocks for each ver
 
 ```hcl
 provider "google" {
-  credentials = "${file("account.json")}"
   project     = "my-project-id"
   region      = "us-central1"
 }
 
 provider "google-beta" {
-  credentials = "${file("account.json")}"
   project     = "my-project-id"
   region      = "us-central1"
 }

website/docs/r/composer_environment.html.markdown

@@ -21,7 +21,7 @@ To get more information about Environments, see:
     * [Configuring Shared VPC for Composer Environments](https://cloud.google.com/composer/docs/how-to/managing/configuring-shared-vpc)
 * [Apache Airflow Documentation](http://airflow.apache.org/)
 
-~> **Warning:** We **STRONGLY** recommend  you read the [GCP guides](https://cloud.google.com/composer/docs/how-to)
+~> **Warning:** We **STRONGLY** recommend you read the [GCP guides](https://cloud.google.com/composer/docs/how-to)
   as the Environment resource requires a long deployment process and involves several layers of GCP infrastructure, 
   including a Kubernetes Engine cluster, Cloud Storage, and Compute networking resources. Due to limitations of the API,
   Terraform will not be able to automatically find or manage many of these underlying resources. In particular:
@@ -31,6 +31,7 @@ To get more information about Environments, see:
     against GCP Cloud Composer before filing bugs against the Terraform provider. 
   * **Environments create Google Cloud Storage buckets that do not get cleaned up automatically** on environment 
     deletion. [More about Composer's use of Cloud Storage](https://cloud.google.com/composer/docs/concepts/cloud-storage).
+  * Please review the [known issues](https://cloud.google.com/composer/docs/known-issues) for Composer if you are having problems.
 
 ## Example Usage
 
@@ -44,9 +45,8 @@ resource "google_composer_environment" "test" {
 
 ### With GKE and Compute Resource Dependencies
 
-**NOTE** To use service accounts, you need to give `role/composer.worker` to the service account on any resources that may be created for the environment
-(i.e. at a project level). This will probably require an explicit dependency
-on the IAM policy binding (see `google_project_iam_member` below).
+**NOTE** To use custom service accounts, you need to give at least `role/composer.worker` to the service account being used by the GKE Nodes on the Composer project.
+You may need to assign additional roles depending on what the Airflow DAGs will be running.
 
 ```hcl
 resource "google_composer_environment" "test" {
@@ -65,8 +65,6 @@ resource "google_composer_environment" "test" {
       service_account = google_service_account.test.name
     }
   }
-
-  depends_on = [google_project_iam_member.composer-worker]
 }
 
 resource "google_compute_network" "test" {

website/docs/r/compute_instance.html.markdown

@@ -18,6 +18,11 @@ and
 ## Example Usage
 
 ```hcl
+resource "google_service_account" "default" {
+  account_id   = "service_account_id"
+  display_name = "Service Account"
+}
+
 resource "google_compute_instance" "default" {
   name         = "test"
   machine_type = "e2-medium"
@@ -51,7 +56,9 @@ resource "google_compute_instance" "default" {
   metadata_startup_script = "echo hi > /test.txt"
 
   service_account {
-    scopes = ["userinfo-email", "compute-ro", "storage-ro"]
+    # Google recommends custom service accounts that have cloud-platform scope and permissions granted via IAM Roles.
+    email  = google_service_account.default.email
+    scopes = ["cloud-platform"]
   }
 }
 ```

website/docs/r/compute_instance_template.html.markdown

@@ -18,6 +18,11 @@ and
 ## Example Usage
 
 ```hcl
+resource "google_service_account" "default" {
+  account_id   = "service_account_id"
+  display_name = "Service Account"
+}
+
 resource "google_compute_instance_template" "default" {
   name        = "appserver-template"
   description = "This template is used to create app server instances."
@@ -61,7 +66,9 @@ resource "google_compute_instance_template" "default" {
   }
 
   service_account {
-    scopes = ["userinfo-email", "compute-ro", "storage-ro"]
+    # Google recommends custom service accounts that have cloud-platform scope and permissions granted via IAM Roles.
+    email  = google_service_account.default.email
+    scopes = ["cloud-platform"]
   }
 }
 

website/docs/r/container_cluster.html.markdown

@@ -26,6 +26,11 @@ plaintext. [Read more about sensitive data in state](/docs/state/sensitive-data.
 ## Example Usage - with a separately managed node pool (recommended)
 
 ```hcl
+resource "google_service_account" "default" {
+  account_id   = "service_account_id"
+  display_name = "Service Account"
+}
+
 resource "google_container_cluster" "primary" {
   name     = "my-gke-cluster"
   location = "us-central1"
@@ -35,15 +40,6 @@ resource "google_container_cluster" "primary" {
   # node pool and immediately delete it.
   remove_default_node_pool = true
   initial_node_count       = 1
-
-  master_auth {
-    username = ""
-    password = ""
-
-    client_certificate_config {
-      issue_client_certificate = false
-    }
-  }
 }
 
 resource "google_container_node_pool" "primary_preemptible_nodes" {
@@ -56,11 +52,9 @@ resource "google_container_node_pool" "primary_preemptible_nodes" {
     preemptible  = true
     machine_type = "e2-medium"
 
-    metadata = {
-      disable-legacy-endpoints = "true"
-    }
-
-    oauth_scopes = [
+    # Google recommends custom service accounts that have cloud-platform scope and permissions granted via IAM Roles.
+    service_account = google_service_account.default.email
+    oauth_scopes    = [
       "https://www.googleapis.com/auth/cloud-platform"
     ]
   }
@@ -74,32 +68,17 @@ resource "google_container_cluster" "primary" {
   name               = "marcellus-wallace"
   location           = "us-central1-a"
   initial_node_count = 3
-
-  master_auth {
-    username = ""
-    password = ""
-
-    client_certificate_config {
-      issue_client_certificate = false
-    }
-  }
-
   node_config {
+    # Google recommends custom service accounts that have cloud-platform scope and permissions granted via IAM Roles.
+    service_account = google_service_account.default.email
     oauth_scopes = [
       "https://www.googleapis.com/auth/cloud-platform"
     ]
-
-    metadata = {
-      disable-legacy-endpoints = "true"
-    }
-
     labels = {
       foo = "bar"
     }
-
     tags = ["foo", "bar"]
   }
-
   timeouts {
     create = "30m"
     update = "40m"
@@ -203,7 +182,7 @@ Kubernetes master. Some values in this block are only returned by the API if
 your service account has permission to get credentials for your GKE cluster. If
 you see an unexpected diff removing a username/password or unsetting your client
 cert, ensure you have the `container.clusters.getCredentials` permission.
-Structure is documented below.
+Structure is documented below. This has been deprecated as of GKE 1.19.
 
 * `master_authorized_networks_config` - (Optional) The desired configuration options
     for master authorized networks. Omit the nested `cidr_blocks` attribute to disallow
@@ -551,10 +530,10 @@ pick a specific range to use.
 The `master_auth` block supports:
 
 * `password` - (Optional) The password to use for HTTP basic authentication when accessing
-    the Kubernetes master endpoint.
+    the Kubernetes master endpoint. This has been deprecated as of GKE 1.19.
 
 * `username` - (Optional) The username to use for HTTP basic authentication when accessing
-    the Kubernetes master endpoint. If not present basic auth will be disabled.
+    the Kubernetes master endpoint. If not present basic auth will be disabled. This has been deprecated as of GKE 1.19.
 
 * `client_certificate_config` - (Optional) Whether client certificate authorization is enabled for this cluster.  For example:
 
@@ -642,11 +621,6 @@ The `node_config` block supports:
 
 * `service_account` - (Optional) The service account to be used by the Node VMs.
     If not specified, the "default" service account is used.
-    In order to use the configured `oauth_scopes` for logging and monitoring, the service account being used needs the
-    [roles/logging.logWriter](https://cloud.google.com/iam/docs/understanding-roles#stackdriver_logging_roles) and
-    [roles/monitoring.metricWriter](https://cloud.google.com/iam/docs/understanding-roles#stackdriver_monitoring_roles) roles.
-
-     -> Projects that enable the [Cloud Compute Engine API](https://cloud.google.com/compute/) with Terraform may need these roles added manually to the service account. Projects that enable the API in the Cloud Console should have them added automatically.
 
 * `shielded_instance_config` - (Optional) Shielded Instance options. Structure is documented below.
 

website/docs/r/container_node_pool.html.markdown

@@ -19,6 +19,11 @@ and [the API reference](https://cloud.google.com/kubernetes-engine/docs/referenc
 ### Example Usage - using a separately managed node pool (recommended)
 
 ```hcl
+resource "google_service_account" "default" {
+  account_id   = "service_account_id"
+  display_name = "Service Account"
+}
+
 resource "google_container_cluster" "primary" {
   name     = "my-gke-cluster"
   location = "us-central1"
@@ -40,6 +45,8 @@ resource "google_container_node_pool" "primary_preemptible_nodes" {
     preemptible  = true
     machine_type = "e2-medium"
 
+    # Google recommends custom service accounts that have cloud-platform scope and permissions granted via IAM Roles.
+    service_account = google_service_account.default.email
     oauth_scopes = [
       "https://www.googleapis.com/auth/cloud-platform"
     ]
@@ -50,12 +57,23 @@ resource "google_container_node_pool" "primary_preemptible_nodes" {
 ### Example Usage - 2 node pools, 1 separately managed + the default node pool
 
 ```hcl
+resource "google_service_account" "default" {
+  account_id   = "service_account_id"
+  display_name = "Service Account"
+}
+
 resource "google_container_node_pool" "np" {
   name       = "my-node-pool"
   location   = "us-central1-a"
   cluster    = google_container_cluster.primary.name
-  node_count = 3
-
+  node_config {
+    machine_type = "e2-medium"
+    # Google recommends custom service accounts that have cloud-platform scope and permissions granted via IAM Roles.
+    service_account = google_service_account.default.email
+    oauth_scopes    = [
+      "https://www.googleapis.com/auth/cloud-platform"
+    ]
+  }
   timeouts {
     create = "30m"
     update = "20m"
@@ -71,24 +89,12 @@ resource "google_container_cluster" "primary" {
     "us-central1-c",
   ]
 
-  master_auth {
-    username = ""
-    password = ""
-
-    client_certificate_config {
-      issue_client_certificate = false
-    }
-  }
-
   node_config {
+    # Google recommends custom service accounts that have cloud-platform scope and permissions granted via IAM Roles.
+    service_account = google_service_account.default.email
     oauth_scopes = [
       "https://www.googleapis.com/auth/cloud-platform"
     ]
-
-    metadata = {
-      disable-legacy-endpoints = "true"
-    }
-
     guest_accelerator {
       type  = "nvidia-tesla-k80"
       count = 1

website/docs/r/dataproc_cluster.html.markdown

@@ -29,6 +29,11 @@ resource "google_dataproc_cluster" "simplecluster" {
 ## Example Usage - Advanced
 
 ```hcl
+resource "google_service_account" "default" {
+  account_id   = "service_account_id"
+  display_name = "Service Account"
+}
+
 resource "google_dataproc_cluster" "mycluster" {
   name     = "mycluster"
   region   = "us-central1"
@@ -73,11 +78,10 @@ resource "google_dataproc_cluster" "mycluster" {
 
     gce_cluster_config {
       tags = ["foo", "bar"]
+      # Google recommends custom service accounts that have cloud-platform scope and permissions granted via IAM Roles.
+      service_account = google_service_account.default.email
       service_account_scopes = [
-        "https://www.googleapis.com/auth/monitoring",
-        "useraccounts-ro",
-        "storage-rw",
-        "logging-write",
+        "cloud-platform"
       ]
     }
 
@@ -238,13 +242,9 @@ The `cluster_config.gce_cluster_config` block supports:
 
 * `service_account_scopes` - (Optional, Computed) The set of Google API scopes
     to be made available on all of the node VMs under the `service_account`
-    specified. These can be	either FQDNs, or scope aliases. The following scopes
-    must be set if any other scopes are set. They're necessary to ensure the
-    correct functioning ofthe cluster, and are set automatically by the API:
-
-  * `useraccounts-ro` (`https://www.googleapis.com/auth/cloud.useraccounts.readonly`)
-  * `storage-rw`      (`https://www.googleapis.com/auth/devstorage.read_write`)
-  * `logging-write`   (`https://www.googleapis.com/auth/logging.write`)
+    specified. Both OAuth2 URLs and gcloud
+    short names are supported. To allow full access to all Cloud APIs, use the
+    `cloud-platform` scope. See a complete list of scopes [here](https://cloud.google.com/sdk/gcloud/reference/alpha/compute/instances/set-scopes#--scopes).
 
 * `tags` - (Optional) The list of instance tags applied to instances in the cluster.
    Tags are used to identify valid sources or targets for network firewalls.