hunfabric/modules/organization/README.md

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.

TOC

• TOC
• Example
• IAM
• Organization Policies
  • Organization Policy Factory
  • Organization Policy Custom Constraints
  • Organization Policy Custom Constraints Factory
• Hierarchical Firewall Policy Attachments
• Log Sinks
• Data Access Logs
• Custom Roles
  • Custom Roles Factory
• Tags
  • Tags Factory
• Files
• Variables
• Outputs

Example

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  iam_by_principals = {
    "group:${var.group_email}" = ["roles/owner"]
  }
  iam = {
    "roles/resourcemanager.projectCreator" = ["group:${var.group_email}"]
  }
  iam_bindings_additive = {
    am1-storage-admin = {
      member = "group:${var.group_email}"
      role   = "roles/storage.admin"
    }
  }
  tags = {
    allowexternal = {
      description = "Allow external identities."
      values = {
        true = {}, false = {}
      }
    }
  }
  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 = { 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=13 inventory=basic.yaml e2e serial

IAM

IAM is managed via several variables that implement different features and levels of control:

• iam and iam_by_principals configure authoritative bindings that manage individual roles exclusively, and are internally merged
• iam_bindings configure authoritative bindings with optional support for conditions, and are not internally merged with the previous two variables
• iam_bindings_additive configure additive bindings via individual role/member pairs with optional support conditions

The authoritative and additive approaches can be used together, provided different roles are managed by each. Some care must also be taken with the iam_by_principals variable to ensure that variable keys are static values, so that Terraform is able to compute the dependency graph.

IAM also supports variable interpolation for both roles and principals, via the respective attributes in the var.context variable. Refer to the project module for examples of the IAM interface.

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
  factories_config = {
    org_policy_custom_constraints = "configs/custom-constraints"
  }
  org_policies = {
    "custom.gkeEnableAutoUpgrade" = {
      rules = [{ enforce = true }]
    }
  }
}
# tftest modules=1 resources=3 files=gke inventory=custom-constraints.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=gke path=configs/custom-constraints/gke.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.

# tftest-file id=dataproc path=configs/custom-constraints/dataproc.yaml

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 = var.organization_id
  # attachment via the firewall policy module
  # attachments = {
  #   org = var.organization_id
  # }
}

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  # attachment via the organization module
  firewall_policy = {
    name   = "test-1"
    policy = module.firewall-policy.id
  }
}
# tftest modules=2 resources=2 e2e serial

Log Sinks

The following example shows how to define organization-level log sinks, which support interpolation in the destination argument.

module "gcs" {
  source        = "./fabric/modules/gcs"
  project_id    = var.project_id
  prefix        = var.prefix
  name          = "gcs_sink"
  location      = "EU"
  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 = var.project_id
  name   = "${var.prefix}-bucket"
}

module "destination-project" {
  source          = "./fabric/modules/project"
  name            = "dest-prj"
  billing_account = var.billing_account_id
  parent          = var.folder_id
  prefix          = var.prefix
  services = [
    "logging.googleapis.com"
  ]
}

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  context = {
    storage_buckets = {
      my_bucket = "test-prod-log-audit-0"
    }
  }
  logging_sinks = {
    audit = {
      destination = "$storage_buckets:my_bucket"
      filter      = "log_id('cloudaudit.googleapis.com/activity')"
      type        = "storage"
    }
    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"
    }
    alert = {
      destination = module.destination-project.id
      filter      = "severity=ALERT"
      type        = "project"
    }
  }
  logging_exclusions = {
    no-gce-instances = "resource.type=gce_instance"
  }
}
# tftest modules=6 resources=19 inventory=logging.yaml

Data Access Logs

Activation of data access logs can be controlled via the logging_data_access variable.

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  logging_data_access = {
    allServices = {
      ADMIN_READ = {
        exempted_members = ["group:${var.group_email}"]
      }
    }
    "storage.googleapis.com" = {
      DATA_READ  = {}
      DATA_WRITE = {}
    }
  }
}
# tftest modules=1 resources=2 inventory=logging-data-access.yaml e2e serial

Custom Roles

Custom roles can be defined via the custom_roles variable, and referenced via the custom_role_id output (this also provides explicit dependency on the custom role):

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  custom_roles = {
    "myRole" = [
      "compute.instances.list",
    ]
  }
  iam = {
    (module.org.custom_role_id.myRole) = ["group:${var.group_email}"]
  }
}
# tftest modules=1 resources=2 inventory=roles.yaml e2e serial

Custom Roles Factory

Custom roles can also be specified via a factory in a similar way to organization policies and policy constraints. Each file is mapped to a custom role, where

• the role name defaults to the file name but can be overridden via a name attribute in the yaml
• role permissions are defined in an includedPermissions map

Custom roles defined via the variable are merged with those coming from the factory, and override them in case of duplicate names.

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  factories_config = {
    custom_roles = "data/custom_roles"
  }
}
# tftest modules=1 resources=2 files=custom-role-1,custom-role-2 inventory=custom-roles.yaml

# tftest-file id=custom-role-1 path=data/custom_roles/test_1.yaml

includedPermissions:
 - compute.globalOperations.get

# tftest-file id=custom-role-2 path=data/custom_roles/test_2.yaml

name: projectViewer
includedPermissions:
  - resourcemanager.projects.get
  - resourcemanager.projects.getIamPolicy
  - resourcemanager.projects.list

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:${var.group_email}"]
      }
      iam_bindings = {
        viewer = {
          role    = "roles/resourcemanager.tagViewer"
          members = ["group:gcp-support@example.org"]
        }
      }
      iam_bindings_additive = {
        user_app1 = {
          role   = "roles/resourcemanager.tagUser"
          member = "group:app1-team@example.org"
        }
      }
      values = {
        dev = {
          iam_bindings_additive = {
            user_app2 = {
              role   = "roles/resourcemanager.tagUser"
              member = "group:app2-team@example.org"
            }
          }
        }
        prod = {
          description = "Environment: production."
          iam = {
            "roles/resourcemanager.tagViewer" = ["group:app1-team@example.org"]
          }
          iam_bindings = {
            admin = {
              role    = "roles/resourcemanager.tagAdmin"
              members = ["group:gcp-support@example.org"]
              condition = {
                title      = "gcp_support"
                expression = <<-END
                  request.time.getHours("Europe/Berlin") <= 9 &&
                  request.time.getHours("Europe/Berlin") >= 17
                END
              }
            }
          }
        }
      }
    }
  }
  tag_bindings = {
    env-prod = module.org.tag_values["environment/prod"].id
  }
}
# tftest modules=1 resources=10 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     = "${var.project_id}/${var.vpc.name}"
      iam = {
        "roles/resourcemanager.tagAdmin" = ["group:${var.group_email}"]
      }
      values = {
        dev = {}
        prod = {
          description = "Environment: production."
          iam = {
            "roles/resourcemanager.tagUser" = ["group:${var.group_email}"]
          }
        }
      }
    }
  }
}
# tftest modules=1 resources=5 inventory=network-tags.yaml e2e serial

Tags Factory

Tags can also be specified via a factory in a similar way to organization policies and policy constraints. Each file is mapped to tag key, where

• the key name defaults to the file name but can be overridden via a name attribute in the yaml
• The structure of the YAML file allows defining the description, iam bindings, and a map of values for the tag key, including their own descriptions and IAM.
• Tags defined via the tags and network_tags variables are merged with those from the factory, and will override factory definitions in case of duplicate names.

The example below deploys a cost-center tag key and its values from a YAML file. Context expansion supports interpolation via the context.tag_keys and context.tag_values variables, as shown below.

module "org" {
  source          = "./fabric/modules/organization"
  organization_id = var.organization_id
  context = {
    tag_keys = {
      environment = "tagKeys/1234567890"
    }
    tag_values = {
      "environment/production" = "tagValues/1234567890"
    }
  }
  factories_config = {
    tags = "data/tags"
  }
}
# tftest modules=1 resources=7 files=0,1 inventory=tags-factory.yaml

# tftest-file id=0 path=data/tags/cost-center.yaml

description: "Tag for internal cost allocation."
iam:
  "roles/resourcemanager.tagViewer":
    - "group:finance-team@example.com"
values:
  engineering:
    description: "Engineering department."
  marketing:
    description: "Marketing department."

# tftest-file id=1 path=data/tags/environment.yaml

id: $tag_keys:environment
iam:
  "roles/resourcemanager.tagViewer":
    - "group:gcp-devops@example.com"
values:
  development:
    description: "Development."
  production:
    id: $tag_values:environment/production
    iam:
      "roles/resourcemanager.tagUser":
        - "group:gcp-devops@example.com"

Files

name	description	resources
iam.tf	IAM bindings.	google_organization_iam_binding · google_organization_iam_custom_role · google_organization_iam_member
logging.tf	Log sinks and data access logs.	google_bigquery_dataset_iam_member · google_logging_organization_exclusion · google_logging_organization_settings · 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_compute_firewall_policy_association · 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	Manages GCP Secure Tags, keys, values, and IAM.	google_tags_tag_binding · google_tags_tag_key · google_tags_tag_key_iam_binding · google_tags_tag_key_iam_member · google_tags_tag_value · google_tags_tag_value_iam_binding · google_tags_tag_value_iam_member
variables-iam.tf	None
variables-logging.tf	None
variables-tags.tf	None
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))		{}
context	Context-specific interpolations.	object({…})		{}
custom_roles	Map of role name => list of permissions to create in this project.	map(list(string))		{}
factories_config	Paths to data files and folders that enable factory functionality.	object({…})		{}
firewall_policy	Hierarchical firewall policies to associate to the organization.	object({…})		null
iam	Authoritative IAM bindings in {ROLE => [MEMBERS]} format.	map(list(string))		{}
iam_bindings	Authoritative IAM bindings in {KEY => {role = ROLE, members = [], condition = {}}}. Keys are arbitrary.	map(object({…}))		{}
iam_bindings_additive	Individual additive IAM bindings. Keys are arbitrary.	map(object({…}))		{}
iam_by_principals	Authoritative IAM binding in {PRINCIPAL => [ROLES]} format. Principals need to be statically defined to avoid errors. Merged internally with the iam variable.	map(list(string))		{}
iam_by_principals_additive	Additive IAM binding in {PRINCIPAL => [ROLES]} format. Principals need to be statically defined to avoid errors. Merged internally with the iam_bindings_additive variable.	map(list(string))		{}
logging_data_access	Control activation of data access logs. The special 'allServices' key denotes configuration for all services.	map(object({…}))		{}
logging_exclusions	Logging exclusions for this organization in the form {NAME -> FILTER}.	map(string)		{}
logging_settings	Default settings for logging resources.	object({…})		null
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_policy_custom_constraints	Organization policy custom constraints keyed by constraint name.	map(object({…}))		{}
tag_bindings	Tag bindings for this organization, in key => tag value id format.	map(string)		{}
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({…}))		{}
tags_config	Fine-grained control on tag resource and IAM creation.	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.
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.