Update IAM v3 documentation for Principal Access Boundary Policies, and Policy Bindings. (#13072) (#21684)

[upstream:d6528c7710ab14a25df1989d52937c029d6ad909]

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

Author: modular-magician

.changelog/13072.txt

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

google/services/iam3/resource_iam_folders_policy_binding.go

@@ -91,8 +91,10 @@ func ResourceIAM3FoldersPolicyBinding() *schema.Resource {
 							Type:     schema.TypeString,
 							Optional: true,
 							ForceNew: true,
-							Description: `Required. Immutable. The resource name of the policy to be bound.
-The binding parent and policy must belong to the same Organization (or Project).`,
+							Description: `Required. Immutable. Full Resource Name of the principal set used for principal access boundary policy bindings.
+Examples for each one of the following supported principal set types:
+* Folder: '//cloudresourcemanager.googleapis.com/folders/FOLDER_ID'
+It must be parent by the policy binding's parent (the folder).`,
 						},
 					},
 				},

google/services/iam3/resource_iam_folders_policy_binding_generated_test.go

@@ -51,7 +51,7 @@ func TestAccIAM3FoldersPolicyBinding_iamFoldersPolicyBindingExample(t *testing.T
 				Config: testAccIAM3FoldersPolicyBinding_iamFoldersPolicyBindingExample(context),
 			},
 			{
-				ResourceName:            "google_iam_folders_policy_binding.my-folder-binding",
+				ResourceName:            "google_iam_folders_policy_binding.binding-for-all-folder-principals",
 				ImportState:             true,
 				ImportStateVerify:       true,
 				ImportStateVerifyIgnore: []string{"annotations", "folder", "location", "policy_binding_id"},
@@ -65,12 +65,12 @@ func testAccIAM3FoldersPolicyBinding_iamFoldersPolicyBindingExample(context map[
 resource "google_iam_principal_access_boundary_policy" "pab_policy" {
   organization   = "%{org_id}"
   location       = "global"
-  display_name   = "test folder binding%{random_suffix}"
+  display_name   = "binding for all principals in the folder%{random_suffix}"
   principal_access_boundary_policy_id = "tf-test-my-pab-policy%{random_suffix}"
 }
 
 resource "google_folder" "folder" {
-  display_name        = "test folder%{random_suffix}"
+  display_name        = "my folder%{random_suffix}"
   parent              = "organizations/%{org_id}"
   deletion_protection = false
 }
@@ -80,12 +80,12 @@ resource "time_sleep" "wait_120s" {
   create_duration = "120s"
 }
 
-resource "google_iam_folders_policy_binding" "my-folder-binding" {
+resource "google_iam_folders_policy_binding" "binding-for-all-folder-principals" {
   folder         = google_folder.folder.folder_id
   location       = "global"
-  display_name   = "test folder binding%{random_suffix}"
+  display_name   = "binding for all principals in the folder%{random_suffix}"
   policy_kind    = "PRINCIPAL_ACCESS_BOUNDARY"
-  policy_binding_id = "tf-test-test-folder-binding%{random_suffix}"
+  policy_binding_id = "tf-test-binding-for-all-folder-principals%{random_suffix}"
   policy         = "organizations/%{org_id}/locations/global/principalAccessBoundaryPolicies/${google_iam_principal_access_boundary_policy.pab_policy.principal_access_boundary_policy_id}"
   target {
     principal_set = "//cloudresourcemanager.googleapis.com/folders/${google_folder.folder.folder_id}"

google/services/iam3/resource_iam_organizations_policy_binding.go

@@ -91,8 +91,12 @@ func ResourceIAM3OrganizationsPolicyBinding() *schema.Resource {
 							Type:     schema.TypeString,
 							Optional: true,
 							ForceNew: true,
-							Description: `Required. Immutable. The resource name of the policy to be bound.
-The binding parent and policy must belong to the same Organization (or Project).`,
+							Description: `Required. Immutable. Full Resource Name of the principal set used for principal access boundary policy bindings.
+Examples for each one of the following supported principal set types:
+* Organization '//cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_ID'
+* Workforce Identity: '//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID'
+* Workspace Identity: '//iam.googleapis.com/locations/global/workspace/WORKSPACE_ID'
+It must be parent by the policy binding's parent (the organization).`,
 						},
 					},
 				},

google/services/iam3/resource_iam_organizations_policy_binding_generated_test.go

@@ -51,7 +51,7 @@ func TestAccIAM3OrganizationsPolicyBinding_iamOrganizationsPolicyBindingExample(
 				Config: testAccIAM3OrganizationsPolicyBinding_iamOrganizationsPolicyBindingExample(context),
 			},
 			{
-				ResourceName:            "google_iam_organizations_policy_binding.my-org-binding",
+				ResourceName:            "google_iam_organizations_policy_binding.binding-for-all-org-principals",
 				ImportState:             true,
 				ImportStateVerify:       true,
 				ImportStateVerifyIgnore: []string{"annotations", "location", "organization", "policy_binding_id"},
@@ -65,7 +65,7 @@ func testAccIAM3OrganizationsPolicyBinding_iamOrganizationsPolicyBindingExample(
 resource "google_iam_principal_access_boundary_policy" "pab_policy" {
   organization   = "%{org_id}"
   location       = "global"
-  display_name   = "test org binding%{random_suffix}"
+  display_name   = "binding for all principals in the Organization%{random_suffix}"
   principal_access_boundary_policy_id = "tf-test-my-pab-policy%{random_suffix}"
 }
 
@@ -74,13 +74,13 @@ resource "time_sleep" "wait_60_seconds" {
   depends_on = [google_iam_principal_access_boundary_policy.pab_policy]
 }
 
-resource "google_iam_organizations_policy_binding" "my-org-binding" {
+resource "google_iam_organizations_policy_binding" "binding-for-all-org-principals" {
   depends_on = [time_sleep.wait_60_seconds]
   organization   = "%{org_id}"
   location       = "global"
-  display_name   = "test org binding%{random_suffix}"
+  display_name   = "binding for all principals in the Organization%{random_suffix}"
   policy_kind    = "PRINCIPAL_ACCESS_BOUNDARY"
-  policy_binding_id = "tf-test-test-org-binding%{random_suffix}"
+  policy_binding_id = "tf-test-binding-for-all-org-principals%{random_suffix}"
   policy         = "organizations/%{org_id}/locations/global/principalAccessBoundaryPolicies/${google_iam_principal_access_boundary_policy.pab_policy.principal_access_boundary_policy_id}"
   target {
     principal_set = "//cloudresourcemanager.googleapis.com/organizations/%{org_id}"

google/services/iam3/resource_iam_principal_access_boundary_policy_generated_test.go

@@ -42,13 +42,16 @@ func TestAccIAM3PrincipalAccessBoundaryPolicy_iamPrincipalAccessBoundaryPolicyEx
 	acctest.VcrTest(t, resource.TestCase{
 		PreCheck:                 func() { acctest.AccTestPreCheck(t) },
 		ProtoV5ProviderFactories: acctest.ProtoV5ProviderFactories(t),
-		CheckDestroy:             testAccCheckIAM3PrincipalAccessBoundaryPolicyDestroyProducer(t),
+		ExternalProviders: map[string]resource.ExternalProvider{
+			"time": {},
+		},
+		CheckDestroy: testAccCheckIAM3PrincipalAccessBoundaryPolicyDestroyProducer(t),
 		Steps: []resource.TestStep{
 			{
 				Config: testAccIAM3PrincipalAccessBoundaryPolicy_iamPrincipalAccessBoundaryPolicyExample(context),
 			},
 			{
-				ResourceName:            "google_iam_principal_access_boundary_policy.my-pab-policy",
+				ResourceName:            "google_iam_principal_access_boundary_policy.pab-policy-for-org",
 				ImportState:             true,
 				ImportStateVerify:       true,
 				ImportStateVerifyIgnore: []string{"annotations", "location", "organization", "principal_access_boundary_policy_id"},
@@ -59,11 +62,11 @@ func TestAccIAM3PrincipalAccessBoundaryPolicy_iamPrincipalAccessBoundaryPolicyEx
 
 func testAccIAM3PrincipalAccessBoundaryPolicy_iamPrincipalAccessBoundaryPolicyExample(context map[string]interface{}) string {
 	return acctest.Nprintf(`
-resource "google_iam_principal_access_boundary_policy" "my-pab-policy" {
+resource "google_iam_principal_access_boundary_policy" "pab-policy-for-org" {
   organization   = "%{org_id}"
   location       = "global"
-  display_name   = "test pab policy%{random_suffix}"
-  principal_access_boundary_policy_id = "tf-test-test-pab-policy%{random_suffix}"
+  display_name   = "PAB policy for Organization%{random_suffix}"
+  principal_access_boundary_policy_id = "tf-test-pab-policy-for-org%{random_suffix}"
 }
 `, context)
 }

google/services/iam3/resource_iam_projects_policy_binding.go

@@ -86,8 +86,13 @@ func ResourceIAM3ProjectsPolicyBinding() *schema.Resource {
 							Type:     schema.TypeString,
 							Optional: true,
 							ForceNew: true,
-							Description: `Required. Immutable. The resource name of the policy to be bound.
-The binding parent and policy must belong to the same Organization (or Project).`,
+							Description: `Required. Immutable. Full Resource Name of the principal set used for principal access boundary policy bindings.
+Examples for each one of the following supported principal set types:
+* Project:
+  * '//cloudresourcemanager.googleapis.com/projects/PROJECT_NUMBER'
+  * '//cloudresourcemanager.googleapis.com/projects/PROJECT_ID'
+* Workload Identity Pool: '//iam.googleapis.com/projects/PROJECT_NUMBER/locations/LOCATION/workloadIdentityPools/WORKLOAD_POOL_ID'
+It must be parent by the policy binding's parent (the project).`,
 						},
 					},
 				},

google/services/iam3/resource_iam_projects_policy_binding_generated_test.go

@@ -51,7 +51,7 @@ func TestAccIAM3ProjectsPolicyBinding_iamProjectsPolicyBindingExample(t *testing
 				Config: testAccIAM3ProjectsPolicyBinding_iamProjectsPolicyBindingExample(context),
 			},
 			{
-				ResourceName:            "google_iam_projects_policy_binding.my-project-binding",
+				ResourceName:            "google_iam_projects_policy_binding.binding-for-all-project-principals",
 				ImportState:             true,
 				ImportStateVerify:       true,
 				ImportStateVerifyIgnore: []string{"annotations", "location", "policy_binding_id"},
@@ -69,7 +69,7 @@ data "google_project" "project" {
 resource "google_iam_principal_access_boundary_policy" "pab_policy" {
   organization   = "%{org_id}"
   location       = "global"
-  display_name   = "test project binding%{random_suffix}"
+  display_name   = "binding for all principals in the project%{random_suffix}"
   principal_access_boundary_policy_id = "tf-test-my-pab-policy%{random_suffix}"
 }
 
@@ -78,13 +78,13 @@ resource "time_sleep" "wait_60_seconds" {
   depends_on = [google_iam_principal_access_boundary_policy.pab_policy]
 }
 
-resource "google_iam_projects_policy_binding" "my-project-binding" {
+resource "google_iam_projects_policy_binding" "binding-for-all-project-principals" {
   depends_on = [time_sleep.wait_60_seconds]
   project        = data.google_project.project.project_id
   location       = "global"
-  display_name   = "test project binding%{random_suffix}"
+  display_name   = "binding for all principals in the project%{random_suffix}"
   policy_kind    = "PRINCIPAL_ACCESS_BOUNDARY"
-  policy_binding_id = "tf-test-test-project-binding%{random_suffix}"
+  policy_binding_id = "tf-test-binding-for-all-project-principals%{random_suffix}"
   policy         = "organizations/%{org_id}/locations/global/principalAccessBoundaryPolicies/${google_iam_principal_access_boundary_policy.pab_policy.principal_access_boundary_policy_id}"
   target {
     principal_set = "//cloudresourcemanager.googleapis.com/projects/${data.google_project.project.project_id}"

website/docs/r/iam_folders_policy_binding.html.markdown

@@ -16,12 +16,12 @@
 # ----------------------------------------------------------------------------
 subcategory: "Cloud IAM"
 description: |-
-  A policy binding to a folder
+  A policy binding to a folder.
 ---
 
 # google_iam_folders_policy_binding
 
-A policy binding to a folder
+A policy binding to a folder. This is a Terraform resource, and maps to a policy binding resource in GCP.
 
 
 To get more information about FoldersPolicyBinding, see:
@@ -37,12 +37,12 @@ To get more information about FoldersPolicyBinding, see:
 resource "google_iam_principal_access_boundary_policy" "pab_policy" {
   organization   = "123456789"
   location       = "global"
-  display_name   = "test folder binding"
+  display_name   = "binding for all principals in the folder"
   principal_access_boundary_policy_id = "my-pab-policy"
 }
 
 resource "google_folder" "folder" {
-  display_name        = "test folder"
+  display_name        = "my folder"
   parent              = "organizations/123456789"
   deletion_protection = false
 }
@@ -52,12 +52,12 @@ resource "time_sleep" "wait_120s" {
   create_duration = "120s"
 }
 
-resource "google_iam_folders_policy_binding" "my-folder-binding" {
+resource "google_iam_folders_policy_binding" "binding-for-all-folder-principals" {
   folder         = google_folder.folder.folder_id
   location       = "global"
-  display_name   = "test folder binding"
+  display_name   = "binding for all principals in the folder"
   policy_kind    = "PRINCIPAL_ACCESS_BOUNDARY"
-  policy_binding_id = "test-folder-binding"
+  policy_binding_id = "binding-for-all-folder-principals"
   policy         = "organizations/123456789/locations/global/principalAccessBoundaryPolicies/${google_iam_principal_access_boundary_policy.pab_policy.principal_access_boundary_policy_id}"
   target {
     principal_set = "//cloudresourcemanager.googleapis.com/folders/${google_folder.folder.folder_id}"
@@ -97,8 +97,10 @@ The following arguments are supported:
 
 * `principal_set` -
   (Optional)
-  Required. Immutable. The resource name of the policy to be bound.
-  The binding parent and policy must belong to the same Organization (or Project).
+  Required. Immutable. Full Resource Name of the principal set used for principal access boundary policy bindings.
+  Examples for each one of the following supported principal set types:
+  * Folder: `//cloudresourcemanager.googleapis.com/folders/FOLDER_ID`
+  It must be parent by the policy binding's parent (the folder).
 
 - - -
 

website/docs/r/iam_organizations_policy_binding.html.markdown

@@ -16,12 +16,12 @@
 # ----------------------------------------------------------------------------
 subcategory: "Cloud IAM"
 description: |-
-  A policy binding to an organizations
+  A policy binding to an organization.
 ---
 
 # google_iam_organizations_policy_binding
 
-A policy binding to an organizations
+A policy binding to an organization. This is a Terraform resource, and maps to a policy binding resource in GCP.
 
 
 To get more information about OrganizationsPolicyBinding, see:
@@ -37,7 +37,7 @@ To get more information about OrganizationsPolicyBinding, see:
 resource "google_iam_principal_access_boundary_policy" "pab_policy" {
   organization   = "123456789"
   location       = "global"
-  display_name   = "test org binding"
+  display_name   = "binding for all principals in the Organization"
   principal_access_boundary_policy_id = "my-pab-policy"
 }
 
@@ -46,13 +46,13 @@ resource "time_sleep" "wait_60_seconds" {
   depends_on = [google_iam_principal_access_boundary_policy.pab_policy]
 }
 
-resource "google_iam_organizations_policy_binding" "my-org-binding" {
+resource "google_iam_organizations_policy_binding" "binding-for-all-org-principals" {
   depends_on = [time_sleep.wait_60_seconds]
   organization   = "123456789"
   location       = "global"
-  display_name   = "test org binding"
+  display_name   = "binding for all principals in the Organization"
   policy_kind    = "PRINCIPAL_ACCESS_BOUNDARY"
-  policy_binding_id = "test-org-binding"
+  policy_binding_id = "binding-for-all-org-principals"
   policy         = "organizations/123456789/locations/global/principalAccessBoundaryPolicies/${google_iam_principal_access_boundary_policy.pab_policy.principal_access_boundary_policy_id}"
   target {
     principal_set = "//cloudresourcemanager.googleapis.com/organizations/123456789"
@@ -91,8 +91,12 @@ The following arguments are supported:
 
 * `principal_set` -
   (Optional)
-  Required. Immutable. The resource name of the policy to be bound.
-  The binding parent and policy must belong to the same Organization (or Project).
+  Required. Immutable. Full Resource Name of the principal set used for principal access boundary policy bindings.
+  Examples for each one of the following supported principal set types:
+  * Organization `//cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_ID`
+  * Workforce Identity: `//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID`
+  * Workspace Identity: `//iam.googleapis.com/locations/global/workspace/WORKSPACE_ID`
+  It must be parent by the policy binding's parent (the organization).
 
 - - -
 

website/docs/r/iam_principal_access_boundary_policy.html.markdown

@@ -16,12 +16,16 @@
 # ----------------------------------------------------------------------------
 subcategory: "Cloud IAM"
 description: |-
-  An IAM Principal Access Boundary Policy resource
+  An IAM Principal Access Boundary Policy resource.
 ---
 
 # google_iam_principal_access_boundary_policy
 
-An IAM Principal Access Boundary Policy resource
+An IAM Principal Access Boundary Policy resource. This resource has no effect on accesses until is bound to a target through policy bindings.
+You can see further documentation on policy bindings in:
+  - [Organizations](/providers/hashicorp/google/latest/docs/resources/iam_organizations_policy_binding)
+  - [Folders](/providers/hashicorp/google/latest/docs/resources/iam_folders_policy_binding)
+  - [Projects](/providers/hashicorp/google/latest/docs/resources/iam_projects_policy_binding)
 
 
 To get more information about PrincipalAccessBoundaryPolicy, see:
@@ -34,11 +38,40 @@ To get more information about PrincipalAccessBoundaryPolicy, see:
 
 
 ```hcl
-resource "google_iam_principal_access_boundary_policy" "my-pab-policy" {
+resource "google_iam_principal_access_boundary_policy" "pab-policy-for-org" {
   organization   = "123456789"
   location       = "global"
-  display_name   = "test pab policy"
-  principal_access_boundary_policy_id = "test-pab-policy"
+  display_name   = "PAB policy for Organization"
+  principal_access_boundary_policy_id = "pab-policy-for-org"
+}
+```
+## Example Usage - Iam Organizations Policy Binding
+
+
+```hcl
+resource "google_iam_principal_access_boundary_policy" "pab_policy" {
+  organization   = "123456789"
+  location       = "global"
+  display_name   = "Binding for all principals in the Organization"
+  principal_access_boundary_policy_id = "my-pab-policy"
+}
+
+resource "time_sleep" "wait_60_seconds" {
+  create_duration = "60s"
+  depends_on = [google_iam_principal_access_boundary_policy.pab_policy]
+}
+
+resource "google_iam_organizations_policy_binding" "my-pab-policy" {
+  depends_on = [time_sleep.wait_60_seconds]
+  organization   = "123456789"
+  location       = "global"
+  display_name   = "Binding for all principals in the Organization"
+  policy_kind    = "PRINCIPAL_ACCESS_BOUNDARY"
+  policy_binding_id = "binding-for-all-org-principals"
+  policy         = "organizations/123456789/locations/global/principalAccessBoundaryPolicies/${google_iam_principal_access_boundary_policy.pab_policy.principal_access_boundary_policy_id}"
+  target {
+    principal_set = "//cloudresourcemanager.googleapis.com/organizations/123456789"
+  }
 }
 ```