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

Co-authored-by: Chris Hawk <[email protected]>

Author: cdutra-google

mmv1/products/iam3/FoldersPolicyBinding.yaml

@@ -14,7 +14,8 @@
 ---
 name: 'FoldersPolicyBinding'
 api_resource_type_kind: PolicyBinding
-description: A policy binding to a folder
+description: |
+  A policy binding to a folder. This is a Terraform resource, and maps to a policy binding resource in GCP.
 references:
   guides:
     'Apply a policy binding': 'https://cloud.google.com/iam/docs/principal-access-boundary-policies-create#create_binding'
@@ -44,14 +45,14 @@ async:
   include_project: true
 examples:
   - name: 'iam_folders_policy_binding'
-    primary_resource_id: 'my-folder-binding'
+    primary_resource_id: 'binding-for-all-folder-principals'
     test_env_vars:
       org_id: 'ORG_ID'
     vars:
       pab_policy_id: 'my-pab-policy'
-      display_name: 'test folder binding'
-      folder_binding_id: 'test-folder-binding'
-      folder_name: 'test folder'
+      display_name: 'binding for all principals in the folder'
+      folder_binding_id: 'binding-for-all-folder-principals'
+      folder_name: 'my folder'
     external_providers: ["time"]
 parameters:
   - name: 'folder'
@@ -108,8 +109,10 @@ properties:
       - name: 'principalSet'
         type: String
         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).
+          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).
         immutable: true
   - name: 'policyKind'
     type: String

mmv1/products/iam3/OrganizationsPolicyBinding.yaml

@@ -14,7 +14,8 @@
 ---
 name: 'OrganizationsPolicyBinding'
 api_resource_type_kind: PolicyBinding
-description: A policy binding to an organizations
+description: |
+  A policy binding to an organization. This is a Terraform resource, and maps to a policy binding resource in GCP.
 references:
   guides:
     'Apply a policy binding': 'https://cloud.google.com/iam/docs/principal-access-boundary-policies-create#create_binding'
@@ -44,13 +45,13 @@ async:
   include_project: true
 examples:
   - name: 'iam_organizations_policy_binding'
-    primary_resource_id: 'my-org-binding'
+    primary_resource_id: 'binding-for-all-org-principals'
     test_env_vars:
       org_id: 'ORG_ID'
     vars:
       pab_policy_id: 'my-pab-policy'
-      display_name: 'test org binding'
-      org_binding_id: 'test-org-binding'
+      display_name: 'binding for all principals in the Organization'
+      org_binding_id: 'binding-for-all-org-principals'
     external_providers: ["time"]
 parameters:
   - name: 'organization'
@@ -107,8 +108,12 @@ properties:
       - name: 'principalSet'
         type: String
         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).
+          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).
         immutable: true
   - name: 'policyKind'
     type: String

mmv1/products/iam3/PrincipalAccessBoundaryPolicy.yaml

@@ -13,7 +13,12 @@
 
 ---
 name: 'PrincipalAccessBoundaryPolicy'
-description: An IAM Principal Access Boundary Policy resource
+description: |
+  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)
 references:
   guides:
     'Create and apply Principal Access Boundaries': 'https://cloud.google.com/iam/docs/principal-access-boundary-policies-create'
@@ -41,12 +46,24 @@ async:
   include_project: true
 examples:
   - name: 'iam_principal_access_boundary_policy'
+    primary_resource_id: 'pab-policy-for-org'
+    external_providers: ["time"]
+    test_env_vars:
+      org_id: 'ORG_ID'
+    vars:
+      display_name: 'PAB policy for Organization'
+      pab_id: 'pab-policy-for-org'
+  - name: 'iam_organizations_policy_binding'
     primary_resource_id: 'my-pab-policy'
+    external_providers: ["time"]
     test_env_vars:
       org_id: 'ORG_ID'
     vars:
-      display_name: 'test pab policy'
-      pab_id: 'test-pab-policy'
+      pab_policy_id: 'my-pab-policy'
+      display_name: 'Binding for all principals in the Organization'
+      org_binding_id: 'binding-for-all-org-principals'
+    # This example is already used as a test in OrganizationsPolicyBinding
+    exclude_test: true
 parameters:
   - name: 'organization'
     type: String

mmv1/products/iam3/ProjectsPolicyBinding.yaml

@@ -14,7 +14,8 @@
 ---
 name: 'ProjectsPolicyBinding'
 api_resource_type_kind: PolicyBinding
-description: A policy binding to a Project
+description: |
+  A policy binding to a project. This is a Terraform resource, and maps to a policy binding resource in GCP.
 references:
   guides:
     'Apply a policy binding': 'https://cloud.google.com/iam/docs/principal-access-boundary-policies-create#create_binding'
@@ -43,14 +44,14 @@ async:
     resource_inside_response: true
 examples:
   - name: 'iam_projects_policy_binding'
-    primary_resource_id: 'my-project-binding'
+    primary_resource_id: 'binding-for-all-project-principals'
     external_providers: ["time"]
     test_env_vars:
       org_id: 'ORG_ID'
     vars:
       pab_policy_id: 'my-pab-policy'
-      display_name: 'test project binding'
-      project_binding_id: 'test-project-binding'
+      display_name: 'binding for all principals in the project'
+      project_binding_id: 'binding-for-all-project-principals'
 parameters:
   - name: 'location'
     type: String
@@ -99,8 +100,13 @@ properties:
       - name: 'principalSet'
         type: String
         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).
+          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).
         immutable: true
   - name: 'policyKind'
     type: String