clarify docs around service account id (#2663)

<!-- This change is generated by MagicModules. -->
/cc @danawillow

google/resource_google_service_account_iam_test.go

@@ -122,7 +122,7 @@ resource "google_service_account" "test_account" {
 }
 
 resource "google_service_account_iam_binding" "foo" {
-  service_account_id = "${google_service_account.test_account.id}"
+  service_account_id = "${google_service_account.test_account.name}"
   role        = "roles/viewer"
   members     = ["serviceAccount:${google_service_account.test_account.email}"]
 }
@@ -137,7 +137,7 @@ resource "google_service_account" "test_account" {
 }
 
 resource "google_service_account_iam_member" "foo" {
-  service_account_id = "${google_service_account.test_account.id}"
+  service_account_id = "${google_service_account.test_account.name}"
   role   = "roles/editor"
   member = "serviceAccount:${google_service_account.test_account.email}"
 }
@@ -160,7 +160,7 @@ data "google_iam_policy" "foo" {
 }
 
 resource "google_service_account_iam_policy" "foo" {
-  service_account_id = "${google_service_account.test_account.id}"
+  service_account_id = "${google_service_account.test_account.name}"
   policy_data = "${data.google_iam_policy.foo.policy_data}"
 }
 `, account)

website/docs/r/google_service_account.html.markdown

@@ -26,8 +26,10 @@ resource "google_service_account" "object_viewer" {
 
 The following arguments are supported:
 
-* `account_id` - (Required) The service account ID.
-    Changing this forces a new service account to be created.
+* `account_id` - (Required) The account id that is used to generate the service
+    account email address and a stable unique id. It is unique within a project,
+    must be 6-30 characters long, and match the regular expression `[a-z]([-a-z0-9]*[a-z0-9])`
+    to comply with RFC1035. Changing this forces a new service account to be created.
 
 * `display_name` - (Optional) The display name for the service account.
     Can be updated without creating a new resource.

website/docs/r/google_service_account_iam.html.markdown

@@ -8,7 +8,7 @@ description: |-
 
 # IAM policy for service account
 
-When managing IAM roles, you can treat a service account either as a resource or as an identity. This resource is to add iam policy bindings to a service account resource to configure permissions for who can edit the service account. To configure permissions for a service account to act as an identity that can manage other GCP resources, use the [google_project_iam](google_project_iam.html) set of resources.
+When managing IAM roles, you can treat a service account either as a resource or as an identity. This resource is to add iam policy bindings to a service account resource **to configure permissions for who can edit the service account**. To configure permissions for a service account to act as an identity that can manage other GCP resources, use the [google_project_iam](google_project_iam.html) set of resources.
 
 Three different resources help you manage your IAM policy for a service account. Each of these resources serves a different use case:
 
@@ -25,26 +25,37 @@ Three different resources help you manage your IAM policy for a service account.
 ```hcl
 data "google_iam_policy" "admin" {
   binding {
-    role = "roles/editor"
+    role = "roles/iam.serviceAccountUser"
 
     members = [
       "user:[email protected]",
     ]
   }
 }
 
+resource "google_service_account" "sa" {
+  account_id   = "my-service-account"
+  display_name = "A service account that only Jane can interact with"
+}
+
 resource "google_service_account_iam_policy" "admin-account-iam" {
-	service_account_id = "your-service-account-id"
+	service_account_id = "${google_service_account.sa.name}"
 	policy_data = "${data.google_iam_policy.admin.policy_data}"
 }
 ```
 
 ## google\_service\_account\_iam\_binding
 
 ```hcl
+
+resource "google_service_account" "sa" {
+  account_id   = "my-service-account"
+  display_name = "A service account that only Jane can use"
+}
+
 resource "google_service_account_iam_binding" "admin-account-iam" {
-  service_account_id = "your-service-account-id"
-  role        = "roles/editor"
+  service_account_id = "${google_service_account.sa.name}"
+  role               = "roles/iam.serviceAccountUser"
 
   members = [
     "user:[email protected]",
@@ -55,18 +66,23 @@ resource "google_service_account_iam_binding" "admin-account-iam" {
 ## google\_service\_account\_iam\_member
 
 ```hcl
+resource "google_service_account" "sa" {
+  account_id   = "my-service-account"
+  display_name = "A service account that Jane can use"
+}
+
 resource "google_service_account_iam_member" "admin-account-iam" {
-  service_account_id = "your-service-account-id"
-  role        = "roles/editor"
-  member      = "user:[email protected]"
+  service_account_id = "${google_service_account.sa.name}"
+  role               = "roles/iam.serviceAccountUser"
+  member             = "user:[email protected]"
 }
 ```
 
 ## Argument Reference
 
 The following arguments are supported:
 
-* `service_account_id` - (Required) The service account id to apply policy to.
+* `service_account_id` - (Required) The fully-qualified name of the service account to apply policy to.
 
 * `member/members` - (Required) Identities that will be granted the privilege in `role`.
   Each entry can have one of the following values: