Merge branch 'master' into elia-gcve

modules/__docs/20230816-iam-refactor.md

@@ -5,11 +5,11 @@
 
 ## Status
 
-Discussed.
+Implemented in [#1595](https://github.com/GoogleCloudPlatform/cloud-foundation-fabric/pull/1595).
 
 ## Context
 
-Our modules IAM interface has evolved organically to progressively support more functionality, resulting in a large variable surface, lack of support for some key features like conditions, and some fragility for specific use cases.
+The IAM interface in our modules has evolved organically to progressively support more functionality, resulting in a large variable surface, lack of support for some key features like conditions, and some fragility for specific use cases.
 
 We currently support, with uneven coverage across modules:
 
@@ -115,34 +115,16 @@ The proposal above summarizes the state of discussions between the authors, and
 
 ## Consequences
 
-A few data blueprints that leverage `iam_additive` will need to be refactored to use the new variable, using one of the following patterns:
+### FAST
 
-```hcl
-locals {
-  network_sa_roles = [
-    "roles/compute.orgFirewallPolicyAdmin",
-    "roles/compute.xpnAdmin"
-  ]
-}
+IAM implementation in the bootstrap stage and matching multitenant bootstrap has radically changed, with the addition of a new [`organization-iam.tf`](https://github.com/GoogleCloudPlatform/cloud-foundation-fabric/blob/master/fast/stages/0-bootstrap/organization-iam.tf) file which contains IAM binding definitions in an abstracted format, that is then converted to the specific formats required by the `iam`, `iam_bindings` and `iam_bindings_additive` variables.
 
-module "organization" {
-  source          = "../../../modules/organization"
-  organization_id = "organizations/${var.organization.id}"
-  iam_bindings_additive = merge(
-    # IAM bindings via locals pattern
-    {
-      for r in local.network_sa_roles : "network_sa-${r}" : {
-        member = module.branch-network-sa.iam_email
-        role   = r
-      }
-    },
-    # IAM bindings via explicit reference pattern
-    {
-      security_sa = {
-        member = module.branch-security-sa.iam_email
-        role   = "roles/accesscontextmanager.policyAdmin"
-      }
-    }
-  )
-}
-```
+This brings several advantages over the previous handling of IAM:
+
+- authoritative and additive bindings are now grouped by principal in an easy to read and change format that serves as its own documentation
+- support for IAM conditions has removed the need for standalone resources and made the intent behind those more explicit
+- some subtle bugs on the intersection of user-specified bindings and internally-specified ones have been addressed
+
+### Blueprints
+
+A few data blueprints that leverage `iam_additive` have been refactored to use the new variable. This is most notable in data blueprints, where extra files have been added to the more complex examples like data foundations, to abstract IAM bindings in a way similar to what is described above for FAST.

modules/__docs/README.md

@@ -1,3 +1,3 @@
-# FAST architectural documents
+# Fabric modules architectural documents
 
 This folder contains assorted bits of documentation used to log current architectural choices, or past decisions. Format is inspired by [Michael Nygard's decision record template](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md).