cloud-foundation-fabric/modules/folder/README.md

Google Cloud Folder Module

This module allows the creation and management of folders, including support for IAM bindings, organization policies, and hierarchical firewall rules.

• Basic example with IAM bindings
• IAM
• Organization policies
  • Organization Policy Factory
• Hierarchical Firewall Policy Attachments
• Log Sinks
• Data Access Logs
• Tags
• Files
• Variables
• Outputs

Basic example with IAM bindings

module "folder" {
  source = "./fabric/modules/folder"
  parent = "organizations/1234567890"
  name   = "Folder name"
  group_iam = {
    "cloud-owners@example.org" = [
      "roles/owner",
      "roles/resourcemanager.folderAdmin",
      "roles/resourcemanager.projectCreator"
    ]
  }
  iam = {
    "roles/owner" = ["user:one@example.org"]
  }
  iam_additive = {
    "roles/compute.admin"  = ["user:a1@example.org", "user:a2@example.org"]
    "roles/compute.viewer" = ["user:a2@example.org"]
  }
  iam_additive_members = {
    "user:am1@example.org" = ["roles/storage.admin"]
    "user:am2@example.org" = ["roles/storage.objectViewer"]
  }
}
# tftest modules=1 resources=9 inventory=iam.yaml

IAM

There are three mutually exclusive ways at the role level of managing IAM in this module

• non-authoritative via the iam_additive and iam_additive_members variables, where bindings created outside this module will coexist with those managed here
• authoritative via the group_iam and iam variables, where bindings created outside this module (eg in the console) will be removed at each terraform apply cycle if the same role is also managed here
• authoritative policy via the iam_policy variable, where any binding created outside this module (eg in the console) will be removed at each terraform apply cycle regardless of the role

The authoritative and additive approaches can be used together, provided different roles are managed by each. The IAM policy is incompatible with the other approaches, and must be used with extreme care.

Some care must be taken with the groups_iam variable (and in some situations with the additive variables) to ensure that variable keys are static values, so that Terraform is able to compute the dependency graph.

Organization policies

To manage organization policies, the orgpolicy.googleapis.com service should be enabled in the quota project.

module "folder" {
  source = "./fabric/modules/folder"
  parent = "organizations/1234567890"
  name   = "Folder name"
  org_policies = {
    "compute.disableGuestAttributesAccess" = {
      rules = [{ enforce = true }]
    }
    "compute.skipDefaultNetworkCreation" = {
      rules = [{ enforce = true }]
    }
    "iam.disableServiceAccountKeyCreation" = {
      rules = [{ enforce = true }]
    }
    "iam.disableServiceAccountKeyUpload" = {
      rules = [
        {
          condition = {
            expression  = "resource.matchTagId('tagKeys/1234', 'tagValues/1234')"
            title       = "condition"
            description = "test condition"
            location    = "somewhere"
          }
          enforce = true
        },
        {
          enforce = false
        }
      ]
    }
    "iam.allowedPolicyMemberDomains" = {
      rules = [{
        allow = {
          values = ["C0xxxxxxx", "C0yyyyyyy"]
        }
      }]
    }
    "compute.trustedImageProjects" = {
      rules = [{
        allow = {
          values = ["projects/my-project"]
        }
      }]
    }
    "compute.vmExternalIpAccess" = {
      rules = [{ deny = { all = true } }]
    }
  }
}
# tftest modules=1 resources=8 inventory=org-policies.yaml

Organization Policy Factory

See the organization policy factory in the project module.

Hierarchical Firewall Policy Attachments

Hierarchical firewall policies can be managed via the net-firewall-policy module, including support for factories. Once a policy is available, attaching it to the organization can be done either in the firewall policy module itself, or here:

module "firewall-policy" {
  source    = "./fabric/modules/net-firewall-policy"
  name      = "test-1"
  parent_id = module.folder.id
  # attachment via the firewall policy module
  # attachments = {
  #   folder-1 = module.folder.id
  # }
}

module "folder" {
  source = "./fabric/modules/folder"
  parent = "organizations/1234567890"
  name   = "Folder name"
  # attachment via the organization module
  firewall_policy_associations = {
    test-1 = module.firewall-policy.id
  }
}
# tftest modules=2 resources=3

Log Sinks

module "gcs" {
  source        = "./fabric/modules/gcs"
  project_id    = "my-project"
  name          = "gcs_sink"
  force_destroy = true
}

module "dataset" {
  source     = "./fabric/modules/bigquery-dataset"
  project_id = "my-project"
  id         = "bq_sink"
}

module "pubsub" {
  source     = "./fabric/modules/pubsub"
  project_id = "my-project"
  name       = "pubsub_sink"
}

module "bucket" {
  source      = "./fabric/modules/logging-bucket"
  parent_type = "project"
  parent      = "my-project"
  id          = "bucket"
}

module "folder-sink" {
  source = "./fabric/modules/folder"
  parent = "folders/657104291943"
  name   = "my-folder"
  logging_sinks = {
    warnings = {
      destination = module.gcs.id
      filter      = "severity=WARNING"
      type        = "storage"
    }
    info = {
      destination = module.dataset.id
      filter      = "severity=INFO"
      type        = "bigquery"
    }
    notice = {
      destination = module.pubsub.id
      filter      = "severity=NOTICE"
      type        = "pubsub"
    }
    debug = {
      destination = module.bucket.id
      filter      = "severity=DEBUG"
      exclusions = {
        no-compute = "logName:compute"
      }
      type = "logging"
    }
  }
  logging_exclusions = {
    no-gce-instances = "resource.type=gce_instance"
  }
}
# tftest modules=5 resources=14 inventory=logging.yaml

Data Access Logs

Activation of data access logs can be controlled via the logging_data_access variable. If the iam_bindings_authoritative variable is used to set a resource-level IAM policy, the data access log configuration will also be authoritative as part of the policy.

This example shows how to set a non-authoritative access log configuration:

module "folder" {
  source = "./fabric/modules/folder"
  parent = "folders/657104291943"
  name   = "my-folder"
  logging_data_access = {
    allServices = {
      # logs for principals listed here will be excluded
      ADMIN_READ = ["group:organization-admins@example.org"]
    }
    "storage.googleapis.com" = {
      DATA_READ  = []
      DATA_WRITE = []
    }
  }
}
# tftest modules=1 resources=3 inventory=logging-data-access.yaml

While this sets an authoritative policies that has exclusive control of both IAM bindings for all roles and data access log configuration, and should be used with extreme care:

module "folder" {
  source = "./fabric/modules/folder"
  parent = "folders/657104291943"
  name   = "my-folder"
  iam_policy = {
    "roles/owner"                             = ["group:org-admins@example.com"]
    "roles/resourcemanager.folderAdmin"       = ["group:org-admins@example.com"]
    "roles/resourcemanager.organizationAdmin" = ["group:org-admins@example.com"]
    "roles/resourcemanager.projectCreator"    = ["group:org-admins@example.com"]
  }
  logging_data_access = {
    allServices = {
      ADMIN_READ = ["group:organization-admins@example.org"]
    }
    "storage.googleapis.com" = {
      DATA_READ  = []
      DATA_WRITE = []
    }
  }
}
# tftest modules=1 resources=2 inventory=iam-policy.yaml

Tags

Refer to the Creating and managing tags documentation for details on usage.

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  tags = {
    environment = {
      description = "Environment specification."
      iam         = null
      values = {
        dev  = null
        prod = null
      }
    }
  }
}

module "folder" {
  source = "./fabric/modules/folder"
  name   = "Test"
  parent = module.org.organization_id
  tag_bindings = {
    env-prod = module.org.tag_values["environment/prod"].id
    foo      = "tagValues/12345678"
  }
}
# tftest modules=2 resources=6 inventory=tags.yaml

Files

name	description	resources
iam.tf	IAM bindings, roles and audit logging resources.	google_folder_iam_binding · google_folder_iam_member · google_folder_iam_policy
logging.tf	Log sinks and supporting resources.	google_bigquery_dataset_iam_member · google_folder_iam_audit_config · google_logging_folder_exclusion · google_logging_folder_sink · google_project_iam_member · google_pubsub_topic_iam_member · google_storage_bucket_iam_member
main.tf	Module-level locals and resources.	google_compute_firewall_policy_association · google_essential_contacts_contact · google_folder
organization-policies.tf	Folder-level organization policies.	google_org_policy_policy
outputs.tf	Module outputs.
tags.tf	None	google_tags_tag_binding
variables.tf	Module variables.
versions.tf	Version pins.

Variables

name	description	type	required	default
contacts	List of essential contacts for this resource. Must be in the form EMAIL -> [NOTIFICATION_TYPES]. Valid notification types are ALL, SUSPENSION, SECURITY, TECHNICAL, BILLING, LEGAL, PRODUCT_UPDATES.	map(list(string))		{}
firewall_policy_associations	Hierarchical firewall policies to associate to this folder, in association name => policy id format.	map(string)		{}
folder_create	Create folder. When set to false, uses id to reference an existing folder.	bool		true
group_iam	Authoritative IAM binding for organization groups, in {GROUP_EMAIL => [ROLES]} format. Group emails need to be static. Can be used in combination with the iam variable.	map(list(string))		{}
iam	IAM bindings in {ROLE => [MEMBERS]} format.	map(list(string))		{}
iam_additive	Non authoritative IAM bindings, in {ROLE => [MEMBERS]} format.	map(list(string))		{}
iam_additive_members	IAM additive bindings in {MEMBERS => [ROLE]} format. This might break if members are dynamic values.	map(list(string))		{}
iam_policy	IAM authoritative policy in {ROLE => [MEMBERS]} format. Roles and members not explicitly listed will be cleared, use with extreme caution.	map(list(string))		null
id	Folder ID in case you use folder_create=false.	string		null
logging_data_access	Control activation of data access logs. Format is service => { log type => [exempted members]}. The special 'allServices' key denotes configuration for all services.	map(map(list(string)))		{}
logging_exclusions	Logging exclusions for this folder in the form {NAME -> FILTER}.	map(string)		{}
logging_sinks	Logging sinks to create for the organization.	map(object({…}))		{}
name	Folder name.	string		null
org_policies	Organization policies applied to this folder keyed by policy name.	map(object({…}))		{}
org_policies_data_path	Path containing org policies in YAML format.	string		null
parent	Parent in folders/folder_id or organizations/org_id format.	string		null
tag_bindings	Tag bindings for this folder, in key => tag value id format.	map(string)		null

Outputs

name	description	sensitive
folder	Folder resource.
id	Fully qualified folder id.
name	Folder name.
sink_writer_identities	Writer identities created for each sink.