docs(iam): update comments and terminology in IAM samples (#13118)

* docs(iam): update comments and terminology in IAM samples

* docs(iam): fix comment in quickstart.py

* docs(iam): rename functions from '_member' to '_principal'

* docs(iam): add backoff on InvalidArgument exception

- Fix google.api_core.exceptions.InvalidArgument: 400 Service account [EMAIL] does not exist on Python 3.13

* docs(iam): add backoff to deleting service account

- Fix "The {email} service account was not deleted." for Python 3.13 CI

* docs(iam): add backoff to test_project_policies and test_service_account

- Fix 'NotFound: 404 Service account [NAME] does not exist.'
- Fix 'Aborted: 409 There were concurrent policy changes. Please retry the whole read-modify-write with exponential backoff.'

Author: eapl-gemugami

iam/cloud-client/snippets/iam_modify_policy_add_role.py

@@ -14,10 +14,10 @@
 
 
 # [START iam_modify_policy_add_role]
-def modify_policy_add_role(policy: dict, role: str, member: str) -> dict:
+def modify_policy_add_role(policy: dict, role: str, principal: str) -> dict:
     """Adds a new role binding to a policy."""
 
-    binding = {"role": role, "members": [member]}
+    binding = {"role": role, "members": [principal]}
     policy["bindings"].append(binding)
     print(policy)
     return policy

iam/cloud-client/snippets/modify_policy_add_member.py

@@ -20,29 +20,22 @@
 from snippets.set_policy import set_project_policy
 
 
-def modify_policy_add_member(
-    project_id: str, role: str, member: str
+def modify_policy_add_principal(
+    project_id: str, role: str, principal: str
 ) -> policy_pb2.Policy:
-    """Add a member to certain role in project policy.
+    """Add a principal to certain role in project policy.
 
     project_id: ID or number of the Google Cloud project you want to use.
-    role: role to which member need to be added.
-    member: The principals requesting access.
-
-    Possible format for member:
-        * user:{emailid}
-        * serviceAccount:{emailid}
-        * group:{emailid}
-        * deleted:user:{emailid}?uid={uniqueid}
-        * deleted:serviceAccount:{emailid}?uid={uniqueid}
-        * deleted:group:{emailid}?uid={uniqueid}
-        * domain:{domain}
+    role: role to which principal need to be added.
+    principal: The principal requesting access.
+
+    For principal ID formats, see https://cloud.google.com/iam/docs/principal-identifiers
     """
     policy = get_project_policy(project_id)
 
     for bind in policy.bindings:
         if bind.role == role:
-            bind.members.append(member)
+            bind.members.append(principal)
             break
 
     return set_project_policy(project_id, policy)
@@ -57,6 +50,6 @@ def modify_policy_add_member(
     PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT", "your-google-cloud-project-id")
 
     role = "roles/viewer"
-    member = f"serviceAccount:test-service-account@{PROJECT_ID}.iam.gserviceaccount.com"
+    principal = f"serviceAccount:test-service-account@{PROJECT_ID}.iam.gserviceaccount.com"
 
-    modify_policy_add_member(PROJECT_ID, role, member)
+    modify_policy_add_principal(PROJECT_ID, role, principal)

iam/cloud-client/snippets/modify_policy_remove_member.py

@@ -20,30 +20,23 @@
 from snippets.set_policy import set_project_policy
 
 
-def modify_policy_remove_member(
-    project_id: str, role: str, member: str
+def modify_policy_remove_principal(
+    project_id: str, role: str, principal: str
 ) -> policy_pb2.Policy:
-    """Remove a member from certain role in project policy.
+    """Remove a principal from certain role in project policy.
 
     project_id: ID or number of the Google Cloud project you want to use.
-    role: role to which member need to be added.
-    member: The principals requesting access.
-
-    Possible format for member:
-        * user:{emailid}
-        * serviceAccount:{emailid}
-        * group:{emailid}
-        * deleted:user:{emailid}?uid={uniqueid}
-        * deleted:serviceAccount:{emailid}?uid={uniqueid}
-        * deleted:group:{emailid}?uid={uniqueid}
-        * domain:{domain}
+    role: role to revoke.
+    principal: The principal to revoke access from.
+
+    For principal ID formats, see https://cloud.google.com/iam/docs/principal-identifiers
     """
     policy = get_project_policy(project_id)
 
     for bind in policy.bindings:
         if bind.role == role:
-            if member in bind.members:
-                bind.members.remove(member)
+            if principal in bind.members:
+                bind.members.remove(principal)
             break
 
     return set_project_policy(project_id, policy, False)
@@ -58,6 +51,6 @@ def modify_policy_remove_member(
     PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT", "your-google-cloud-project-id")
 
     role = "roles/viewer"
-    member = f"serviceAccount:test-service-account@{PROJECT_ID}.iam.gserviceaccount.com"
+    principal = f"serviceAccount:test-service-account@{PROJECT_ID}.iam.gserviceaccount.com"
 
-    modify_policy_remove_member(PROJECT_ID, role, member)
+    modify_policy_remove_principal(PROJECT_ID, role, principal)

iam/cloud-client/snippets/quickstart.py

@@ -18,30 +18,35 @@
 from google.iam.v1 import iam_policy_pb2, policy_pb2
 
 
-def quickstart(project_id: str, member: str) -> None:
-    """Gets a policy, adds a member, prints their permissions, and removes the member.
+def quickstart(project_id: str, principal: str) -> None:
+    """Demonstrates basic IAM operations.
 
-    project_id: ID or number of the Google Cloud project you want to use.
-    member: The principals requesting the access.
+    This quickstart shows how to get a project's IAM policy,
+    add a principal to a role, list members of a role,
+    and remove a principal from a role.
+
+    Args:
+        project_id: ID or number of the Google Cloud project you want to use.
+        principal: The principal ID requesting the access.
     """
 
     # Role to be granted.
     role = "roles/logging.logWriter"
     crm_service = resourcemanager_v3.ProjectsClient()
 
-    # Grants your member the 'Log Writer' role for the project.
-    modify_policy_add_role(crm_service, project_id, role, member)
+    # Grants your principal the 'Log Writer' role for the project.
+    modify_policy_add_role(crm_service, project_id, role, principal)
 
-    # Gets the project's policy and prints all members with the 'Log Writer' role.
+    # Gets the project's policy and prints all principals with the 'Log Writer' role.
     policy = get_policy(crm_service, project_id)
     binding = next(b for b in policy.bindings if b.role == role)
     print(f"Role: {(binding.role)}")
     print("Members: ")
     for m in binding.members:
         print(f"[{m}]")
 
-    # Removes the member from the 'Log Writer' role.
-    modify_policy_remove_member(crm_service, project_id, role, member)
+    # Removes the principal from the 'Log Writer' role.
+    modify_policy_remove_principal(crm_service, project_id, role, principal)
 
 
 def get_policy(
@@ -74,48 +79,49 @@ def modify_policy_add_role(
     crm_service: resourcemanager_v3.ProjectsClient,
     project_id: str,
     role: str,
-    member: str,
+    principal: str,
 ) -> None:
     """Adds a new role binding to a policy."""
 
     policy = get_policy(crm_service, project_id)
 
     for bind in policy.bindings:
         if bind.role == role:
-            bind.members.append(member)
+            bind.members.append(principal)
             break
     else:
         binding = policy_pb2.Binding()
         binding.role = role
-        binding.members.append(member)
+        binding.members.append(principal)
         policy.bindings.append(binding)
 
     set_policy(crm_service, project_id, policy)
 
 
-def modify_policy_remove_member(
+def modify_policy_remove_principal(
     crm_service: resourcemanager_v3.ProjectsClient,
     project_id: str,
     role: str,
-    member: str,
+    principal: str,
 ) -> None:
-    """Removes a  member from a role binding."""
+    """Removes a principal from a role binding."""
 
     policy = get_policy(crm_service, project_id)
 
     for bind in policy.bindings:
         if bind.role == role:
-            if member in bind.members:
-                bind.members.remove(member)
+            if principal in bind.members:
+                bind.members.remove(principal)
             break
 
     set_policy(crm_service, project_id, policy)
 
 
 if __name__ == "__main__":
-    # TODO: Replace with your project ID
+    # TODO: Replace with your project ID.
     project_id = "your-project-id"
-    # TODO: Replace with the ID of your member in the form 'user:[email protected]'.
-    member = "your-member"
-    quickstart(project_id, member)
+    # TODO: Replace with the ID of your principal.
+    # For examples, see https://cloud.google.com/iam/docs/principal-identifiers
+    principal = "your-principal"
+    quickstart(project_id, principal)
 # [END iam_quickstart]

iam/cloud-client/snippets/quickstart_test.py

@@ -78,6 +78,7 @@ def test_member(capsys: "pytest.CaptureFixture[str]") -> str:
 
 def test_quickstart(test_member: str, capsys: pytest.CaptureFixture) -> None:
     @backoff.on_exception(backoff.expo, Aborted, max_tries=6)
+    @backoff.on_exception(backoff.expo, InvalidArgument, max_tries=6)
     def test_call() -> None:
         quickstart(PROJECT_ID, test_member)
         out, _ = capsys.readouterr()

iam/cloud-client/snippets/test_project_policies.py

@@ -28,8 +28,8 @@
 from snippets.delete_service_account import delete_service_account
 from snippets.get_policy import get_project_policy
 from snippets.list_service_accounts import get_service_account
-from snippets.modify_policy_add_member import modify_policy_add_member
-from snippets.modify_policy_remove_member import modify_policy_remove_member
+from snippets.modify_policy_add_member import modify_policy_add_principal
+from snippets.modify_policy_remove_member import modify_policy_remove_principal
 from snippets.query_testable_permissions import query_testable_permissions
 from snippets.set_policy import set_project_policy
 
@@ -98,6 +98,7 @@ def execute_wrapped(
         pytest.skip("Service account wasn't created")
 
 
+@backoff.on_exception(backoff.expo, Aborted, max_tries=6)
 def test_set_project_policy(project_policy: policy_pb2.Policy) -> None:
     role = "roles/viewer"
     test_binding = policy_pb2.Binding()
@@ -119,7 +120,8 @@ def test_set_project_policy(project_policy: policy_pb2.Policy) -> None:
     assert binding_found
 
 
-def test_modify_policy_add_member(
+@backoff.on_exception(backoff.expo, Aborted, max_tries=6)
+def test_modify_policy_add_principal(
     project_policy: policy_pb2.Policy, service_account: str
 ) -> None:
     role = "roles/viewer"
@@ -141,7 +143,7 @@ def test_modify_policy_add_member(
     assert binding_found
 
     member = f"serviceAccount:{service_account}"
-    policy = execute_wrapped(modify_policy_add_member, PROJECT_ID, role, member)
+    policy = execute_wrapped(modify_policy_add_principal, PROJECT_ID, role, member)
 
     member_added = False
     for bind in policy.bindings:
@@ -151,6 +153,7 @@ def test_modify_policy_add_member(
     assert member_added
 
 
+@backoff.on_exception(backoff.expo, Aborted, max_tries=6)
 def test_modify_policy_remove_member(
     project_policy: policy_pb2.Policy, service_account: str
 ) -> None:
@@ -175,7 +178,7 @@ def test_modify_policy_remove_member(
             break
     assert binding_found
 
-    policy = execute_wrapped(modify_policy_remove_member, PROJECT_ID, role, member)
+    policy = execute_wrapped(modify_policy_remove_principal, PROJECT_ID, role, member)
 
     member_removed = False
     for bind in policy.bindings:

iam/cloud-client/snippets/test_service_account.py

@@ -98,6 +98,7 @@ def test_list_service_accounts(service_account_email: str) -> None:
 
 
 @backoff.on_exception(backoff.expo, AssertionError, max_tries=6)
+@backoff.on_exception(backoff.expo, NotFound, max_tries=6)
 def test_disable_service_account(service_account_email: str) -> None:
     account_before = get_service_account(PROJECT_ID, service_account_email)
     assert not account_before.disabled

iam/cloud-client/snippets/test_service_account_key.py

@@ -29,6 +29,31 @@
 PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT", "your-google-cloud-project-id")
 
 
+def delete_service_account_with_backoff(email: str) -> None:
+    """Check if the account was deleted correctly using exponential backoff."""
+
+    delete_service_account(PROJECT_ID, email)
+
+    backoff_delay_secs = 1  # Start wait with delay of 1 second
+    starting_time = time.time()
+    timeout_secs = 90
+
+    while time.time() < starting_time + timeout_secs:
+        try:
+            get_service_account(PROJECT_ID, email)
+        except (NotFound, InvalidArgument):
+            # Service account deleted successfully
+            return
+
+        # In case the account still exists, wait again.
+        print("- Waiting for the service account to be deleted...")
+        time.sleep(backoff_delay_secs)
+        # Double the delay to provide exponential backoff
+        backoff_delay_secs *= 2
+
+    pytest.fail(f"The {email} service account was not deleted.")
+
+
 @pytest.fixture
 def service_account(capsys: "pytest.CaptureFixture[str]") -> str:
     name = f"test-{uuid.uuid4().hex[:25]}"
@@ -50,14 +75,14 @@ def service_account(capsys: "pytest.CaptureFixture[str]") -> str:
             execution_finished = True
             created = True
         except (NotFound, InvalidArgument):
-            # Account not created yet, retry
+            # Account not created yet, retry getting it.
             pass
 
-        # If we haven't seen the result yet, wait again.
+        # If account is not found yet, wait again.
         if not execution_finished:
             print("- Waiting for the service account to be available...")
             time.sleep(backoff_delay_secs)
-            # Double the delay to provide exponential backoff.
+            # Double the delay to provide exponential backoff
             backoff_delay_secs *= 2
 
         if time.time() > starting_time + timeout_secs:
@@ -67,15 +92,7 @@ def service_account(capsys: "pytest.CaptureFixture[str]") -> str:
 
     # Cleanup after running the test
     if created:
-        delete_service_account(PROJECT_ID, email)
-        time.sleep(5)
-
-        try:
-            get_service_account(PROJECT_ID, email)
-        except NotFound:
-            pass
-        else:
-            pytest.fail(f"The {email} service account was not deleted.")
+        delete_service_account_with_backoff(email)
 
 
 def key_found(project_id: str, account: str, key_id: str) -> bool: