organization

Organization Module

This module allows managing several organization properties:

• IAM bindings, both authoritative and additive
• custom IAM roles
• audit logging configuration for services
• organization policies
• organization policy custom constraints

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

Features

• IAM
• Organization Policies
  • Factory
  • Custom Constraints
  • Custom Constraints Factory
• Hierarchical Firewall Policies
  • Directly Defined
  • Factory
• Log Sinks
• Data Access Logs
• Custom Roles
• Tags

Example

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = "organizations/1234567890"
  group_iam = {
    "[email protected]" = ["roles/owner", "roles/projectCreator"]
  }
  iam = {
    "roles/resourcemanager.projectCreator" = ["group:[email protected]"]
  }
  iam_additive_members = {
    "user:[email protected]" = ["roles/compute.admin", "roles/container.viewer"]
  }
  tags = {
    allowexternal = {
      description = "Allow external identities."
      values = {
        true = {}, false = {}
      }
    }
  }
  org_policies = {
    "custom.gkeEnableAutoUpgrade" = {
      rules = [{ enforce = true }]
    }
    "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 = { all = true }
          condition = {
            expression  = "resource.matchTag('1234567890/allowexternal', 'true')"
            title       = "Allow external identities"
            description = "Allow external identities when resource has the `allowexternal` tag set to true."
          }
        },
        {
          allow = { values = ["C0xxxxxxx", "C0yyyyyyy"] }
          condition = {
            expression  = "!resource.matchTag('1234567890/allowexternal', 'true')"
            title       = ""
            description = "For any resource without allowexternal=true, only allow identities from restricted domains."
          }
        }
      ]
    }

    "compute.trustedImageProjects" = {
      rules = [{
        allow = {
          values = ["projects/my-project"]
        }
      }]
    }
    "compute.vmExternalIpAccess" = {
      rules = [{ deny = { all = true } }]
    }
  }
}
# tftest modules=1 resources=16 inventory=basic.yaml

IAM

There are three mutually exclusive ways 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 also be taken with the group_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

Organization Policy Factory

See the organization policy factory in the project module.

Organization Policy Custom Constraints

Refer to the Creating and managing custom constraints documentation for details on usage. To manage organization policy custom constraints, the orgpolicy.googleapis.com service should be enabled in the quota project.

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id

  org_policy_custom_constraints = {
    "custom.gkeEnableAutoUpgrade" = {
      resource_types = ["container.googleapis.com/NodePool"]
      method_types   = ["CREATE"]
      condition      = "resource.management.autoUpgrade == true"
      action_type    = "ALLOW"
      display_name   = "Enable node auto-upgrade"
      description    = "All node pools must have node auto-upgrade enabled."
    }
  }

  # not necessarily to enforce on the org level, policy may be applied on folder/project levels
  org_policies = {
    "custom.gkeEnableAutoUpgrade" = {
      rules = [{ enforce = true }]
    }
  }
}
# tftest modules=1 resources=2 inventory=custom-constraints.yaml

You can use the id or custom_constraint_ids outputs to prevent race conditions between the creation of a custom constraint and an organization policy using that constraint. Both of these outputs depend on the actual constraint, which would make any resource referring to them to wait for the creation of the constraint.

Organization Policy Custom Constraints Factory

Org policy custom constraints can be loaded from a directory containing YAML files where each file defines one or more custom constraints. The structure of the YAML files is exactly the same as the org_policy_custom_constraints variable.

The example below deploys a few org policy custom constraints split between two YAML files.

module "org" {
  source                                  = "./fabric/modules/organization"
  organization_id                         = var.organization_id
  org_policy_custom_constraints_data_path = "configs/custom-constraints"
  org_policies = {
    "custom.gkeEnableAutoUpgrade" = {
      rules = [{ enforce = true }]
    }
  }
}
# tftest modules=1 resources=3 files=gke inventory=custom-constraints.yaml

# tftest-file id=gke path=configs/custom-constraints/gke.yaml
custom.gkeEnableLogging:
  resource_types:
  - container.googleapis.com/Cluster
  method_types:
  - CREATE
  - UPDATE
  condition: resource.loggingService == "none"
  action_type: DENY
  display_name: Do not disable Cloud Logging
custom.gkeEnableAutoUpgrade:
  resource_types:
  - container.googleapis.com/NodePool
  method_types:
  - CREATE
  condition: resource.management.autoUpgrade == true
  action_type: ALLOW
  display_name: Enable node auto-upgrade
  description: All node pools must have node auto-upgrade enabled.

# tftest-file id=dataproc path=configs/custom-constraints/dataproc.yaml
custom.dataprocNoMoreThan10Workers:
  resource_types:
  - dataproc.googleapis.com/Cluster
  method_types:
  - CREATE
  - UPDATE
  condition: resource.config.workerConfig.numInstances + resource.config.secondaryWorkerConfig.numInstances > 10
  action_type: DENY
  display_name: Total number of worker instances cannot be larger than 10
  description: Cluster cannot have more than 10 workers, including primary and secondary workers.

Hierarchical Firewall Policies

Hierarchical firewall policies can be managed in two ways:

• via the firewall_policies variable, to directly define policies and rules in Terraform
• via the firewall_policy_factory variable, to leverage external YaML files via a simple "factory" embedded in the module (see here for more context on factories)

Once you have policies (either created via the module or externally), you can associate them using the firewall_policy_association variable.

Directly Defined Firewall Policies

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  firewall_policies = {
    iap-policy = {
      allow-admins = {
        description             = "Access from the admin subnet to all subnets"
        direction               = "INGRESS"
        action                  = "allow"
        priority                = 1000
        ranges                  = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
        ports                   = { all = [] }
        target_service_accounts = null
        target_resources        = null
        logging                 = false
      }
      allow-iap-ssh = {
        description = "Always allow ssh from IAP."
        direction   = "INGRESS"
        action      = "allow"
        priority    = 100
        ranges      = ["35.235.240.0/20"]
        ports = {
          tcp = ["22"]
        }
        target_service_accounts = null
        target_resources        = null
        logging                 = false
      }
    }
  }
  firewall_policy_association = {
    iap_policy = "iap-policy"
  }
}
# tftest modules=1 resources=4 inventory=hfw.yaml

Firewall Policy Factory

The in-built factory allows you to define a single policy, using one file for rules, and an optional file for CIDR range substitution variables. Remember that non-absolute paths are relative to the root module (the folder where you run terraform).

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  firewall_policy_factory = {
    cidr_file   = "configs/firewall-policies/cidrs.yaml"
    policy_name = "iap-policy"
    rules_file  = "configs/firewall-policies/rules.yaml"
  }
  firewall_policy_association = {
    iap_policy = module.org.firewall_policy_id["iap-policy"]
  }
}
# tftest modules=1 resources=4 files=cidrs,rules inventory=hfw.yaml

# tftest-file id=cidrs path=configs/firewall-policies/cidrs.yaml
rfc1918:
  - 10.0.0.0/8
  - 172.16.0.0/12
  - 192.168.0.0/16

# tftest-file id=rules path=configs/firewall-policies/rules.yaml
allow-admins:
  description: Access from the admin subnet to all subnets
  direction: INGRESS
  action: allow
  priority: 1000
  ranges:
    - $rfc1918
  ports:
    all: []
  target_resources: null
  logging: false

allow-iap-ssh:
  description: "Always allow ssh from IAP."
  direction: INGRESS
  action: allow
  priority: 100
  ranges:
    - 35.235.240.0/20
  ports:
    tcp: ["22"]
  target_resources: null
  logging: false

Log Sinks

The following example shows how to define organization-level log sinks:

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

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

module "pubsub" {
  source     = "./fabric/modules/pubsub"
  project_id = var.project_id
  name       = "pubsub_sink"
}

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

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id

  logging_sinks = {
    warnings = {
      destination = module.gcs.id
      filter      = "severity=WARNING"
      type        = "storage"
    }
    info = {
      bq_partitioned_table = true
      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=13 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 "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  logging_data_access = {
    allServices = {
      # logs for principals listed here will be excluded
      ADMIN_READ = ["group:[email protected]"]
    }
    "storage.googleapis.com" = {
      DATA_READ  = []
      DATA_WRITE = []
    }
  }
}
# tftest modules=1 resources=2 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 "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  iam_policy = {
    "roles/owner"                             = ["group:[email protected]"]
    "roles/resourcemanager.folderAdmin"       = ["group:[email protected]"]
    "roles/resourcemanager.organizationAdmin" = ["group:[email protected]"]
    "roles/resourcemanager.projectCreator"    = ["group:[email protected]"]
  }
  logging_data_access = {
    allServices = {
      ADMIN_READ = ["group:[email protected]"]
    }
    "storage.googleapis.com" = {
      DATA_READ  = []
      DATA_WRITE = []
    }
  }
}
# tftest modules=1 resources=1 inventory=iam-policy.yaml

Custom Roles

Custom roles can be defined via the custom_roles variable, and referenced via the custom_role_id output:

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  custom_roles = {
    "myRole" = [
      "compute.instances.list",
    ]
  }
  iam = {
    (module.org.custom_role_id.myRole) = ["user:[email protected]"]
  }
}
# tftest modules=1 resources=2 inventory=roles.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 = {
        "roles/resourcemanager.tagAdmin" = ["group:[email protected]"]
      }
      values = {
        dev = {}
        prod = {
          description = "Environment: production."
          iam = {
            "roles/resourcemanager.tagViewer" = ["user:[email protected]"]
          }
        }
      }
    }
  }
  tag_bindings = {
    env-prod = module.org.tag_values["environment/prod"].id
    foo      = "tagValues/12345678"
  }
}
# tftest modules=1 resources=7 inventory=tags.yaml

You can also define network tags, through a dedicated variable network_tags:

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  network_tags = {
    net-environment = {
      description = "This is a network tag."
      network     = "my_project/my_vpc"
      iam = {
        "roles/resourcemanager.tagAdmin" = ["group:[email protected]"]
      }
      values = {
        dev = null
        prod = {
          description = "Environment: production."
          iam = {
            "roles/resourcemanager.tagUser" = ["user:[email protected]"]
          }
        }
      }
    }
  }
}
# tftest modules=1 resources=5 inventory=network-tags.yaml

Files

name	description	resources
firewall-policies.tf	Hierarchical firewall policies.	google_compute_firewall_policy · google_compute_firewall_policy_association · google_compute_firewall_policy_rule
iam.tf	IAM bindings, roles and audit logging resources.	google_organization_iam_binding · google_organization_iam_custom_role · google_organization_iam_member · google_organization_iam_policy
logging.tf	Log sinks and data access logs.	google_bigquery_dataset_iam_member · google_logging_organization_exclusion · google_logging_organization_sink · google_organization_iam_audit_config · google_project_iam_member · google_pubsub_topic_iam_member · google_storage_bucket_iam_member
main.tf	Module-level locals and resources.	google_essential_contacts_contact
org-policy-custom-constraints.tf	None	google_org_policy_custom_constraint
organization-policies.tf	Organization-level organization policies.	google_org_policy_policy
outputs.tf	Module outputs.
tags.tf	None	google_tags_tag_binding · google_tags_tag_key · google_tags_tag_key_iam_binding · google_tags_tag_value · google_tags_tag_value_iam_binding
variables.tf	Module variables.
versions.tf	Version pins.

Variables

name	description	type	required	default
organization_id	Organization id in organizations/nnnnnn format.	string	✓
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))		{}
custom_roles	Map of role name => list of permissions to create in this project.	map(list(string))		{}
firewall_policies	Hierarchical firewall policy rules created in the organization.	map(map(object({…})))		{}
firewall_policy_association	The hierarchical firewall policy to associate to this folder. Must be either a key in the firewall_policies map or the id of a policy defined somewhere else.	map(string)		{}
firewall_policy_factory	Configuration for the firewall policy factory.	object({…})		null
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
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 organization in the form {NAME -> FILTER}.	map(string)		{}
logging_sinks	Logging sinks to create for the organization.	map(object({…}))		{}
network_tags	Network tags by key name. If id is provided, key creation is skipped. The iam attribute behaves like the similarly named one at module level.	map(object({…}))		{}
org_policies	Organization policies applied to this organization keyed by policy name.	map(object({…}))		{}
org_policies_data_path	Path containing org policies in YAML format.	string		null
org_policy_custom_constraints	Organization policy custom constraints keyed by constraint name.	map(object({…}))		{}
org_policy_custom_constraints_data_path	Path containing org policy custom constraints in YAML format.	string		null
tag_bindings	Tag bindings for this organization, in key => tag value id format.	map(string)		null
tags	Tags by key name. If id is provided, key or value creation is skipped. The iam attribute behaves like the similarly named one at module level.	map(object({…}))		{}

Outputs

name	description	sensitive
custom_constraint_ids	Map of CUSTOM_CONSTRAINTS => ID in the organization.
custom_role_id	Map of custom role IDs created in the organization.
custom_roles	Map of custom roles resources created in the organization.
firewall_policies	Map of firewall policy resources created in the organization.
firewall_policy_id	Map of firewall policy ids created in the organization.
id	Fully qualified organization id.
network_tag_keys	Tag key resources.
network_tag_values	Tag value resources.
organization_id	Organization id dependent on module resources.
sink_writer_identities	Writer identities created for each sink.
tag_keys	Tag key resources.
tag_values	Tag value resources.