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

Example

module "org" {
  source          = "./modules/organization"
  organization_id = "organizations/1234567890"
  group_iam       = {
    "[email protected]" = ["roles/owner", "roles/projectCreator"]
  }
  iam             = {
    "roles/resourcemanager.projectCreator" = ["group:[email protected]"]
  }
  policy_boolean = {
    "constraints/compute.disableGuestAttributesAccess" = true
    "constraints/compute.skipDefaultNetworkCreation"   = true
  }
  policy_list = {
    "constraints/compute.trustedImageProjects" = {
      inherit_from_parent = null
      suggested_value     = null
      status              = true
      values              = ["projects/my-project"]
    }
  }
}
# tftest modules=1 resources=6

IAM

There are several 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_bindings_authoritative variable, where any binding created outside this module (eg in the console) will be removed at each terraform apply cycle regardless of the role

If you set audit policies via the iam_audit_config_authoritative variable, be sure to also configure IAM bindings via iam_bindings_authoritative, as audit policies use the underlying google_organization_iam_policy resource, which is also authoritative for any role.

Some care must also be takend 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.

Hierarchical firewall policies

Hirerarchical 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          = "./modules/organization"
  organization_id = var.organization_id
  firewall_policies = {
    iap-policy = {
      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=3

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          = "./modules/organization"
  organization_id = var.organization_id
  firewall_policy_factory = {
    cidr_file   = "data/cidrs.yaml"
    policy_name = null
    rules_file  = "data/rules.yaml"
  }
  firewall_policy_association = {
    factory-policy = module.org.firewall_policy_id["factory"]
  }
}
# tftest skip

# cidrs.yaml

rfc1918:
  - 10.0.0.0/8
  - 172.16.0.0/12
  - 192.168.0.0/16

# 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
  enable_logging: false

allow-ssh-from-iap:
  description: Enable SSH from IAP
  direction: INGRESS
  action: allow
  priority: 1002
  ranges:
    - 35.235.240.0/20
  ports:
    tcp: ["22"]
  target_resources: null
  enable_logging: false

Logging Sinks

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

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

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

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

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

  logging_sinks = {
    warnings = {
      type                 = "storage"
      destination          = module.gcs.name
      filter               = "severity=WARNING"
      include_children     = true
      bq_partitioned_table = null
      exclusions           = {}
    }
    info = {
      type                 = "bigquery"
      destination          = module.dataset.id
      filter               = "severity=INFO"
      include_children     = true
      bq_partitioned_table = true
      exclusions           = {}
    }
    notice = {
      type                 = "pubsub"
      destination          = module.pubsub.id
      filter               = "severity=NOTICE"
      include_children     = true
      bq_partitioned_table = null
      exclusions           = {}
    }
    debug = {
      type                 = "logging"
      destination          = module.bucket.id
      filter               = "severity=DEBUG"
      include_children     = false
      bq_partitioned_table = null
      exclusions           = {
        no-compute = "logName:compute"
      }
    }
  }
  logging_exclusions = {
    no-gce-instances = "resource.type=gce_instance"
  }
}
# tftest modules=5 resources=13

Custom Roles

module "org" {
  source          = "./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

Tags

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

module "org" {
  source          = "./modules/organization"
  organization_id = var.organization_id
  tags = {
    environment = {
      description  = "Environment specification."
      iam          = {
        "roles/resourcemanager.tagAdmin" = ["group:[email protected]"]
      }
      values = {
        dev  = null
        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

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_audit_config · google_organization_iam_binding · google_organization_iam_custom_role · google_organization_iam_member · google_organization_iam_policy
logging.tf	Log sinks and supporting resources.	google_bigquery_dataset_iam_member · google_logging_organization_exclusion · google_logging_organization_sink · 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
organization-policies.tf	Organization-level organization policies.	google_organization_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_audit_config	Service audit logging configuration. Service as key, map of log permission (eg DATA_READ) and excluded members as value for each service.	map(map(list(string)))		{}
iam_audit_config_authoritative	IAM Authoritative service audit logging configuration. Service as key, map of log permission (eg DATA_READ) and excluded members as value for each service. Audit config should also be authoritative when using authoritative bindings. Use with caution.	map(map(list(string)))		null
iam_bindings_authoritative	IAM authoritative bindings, in {ROLE => [MEMBERS]} format. Roles and members not explicitly listed will be cleared. Bindings should also be authoritative when using authoritative audit config. Use with caution.	map(list(string))		null
logging_exclusions	Logging exclusions for this organization in the form {NAME -> FILTER}.	map(string)		{}
logging_sinks	Logging sinks to create for this organization.	map(object({…}))		{}
policy_boolean	Map of boolean org policies and enforcement value, set value to null for policy restore.	map(bool)		{}
policy_list	Map of list org policies, status is true for allow, false for deny, null for restore. Values can only be used for allow or deny.	map(object({…}))		{}
tag_bindings	Tag bindings for this organization, in key => tag value id format.	map(string)		null
tags	Tags by key name. The iam attribute behaves like the similarly named one at module level.	map(object({…}))		null

Outputs

name	description	sensitive
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.
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.