449 lines
19 KiB
Markdown
449 lines
19 KiB
Markdown
# Google Cloud Folder Module
|
|
|
|
This module allows the creation and management of folders, including support for IAM bindings, organization policies, and hierarchical firewall rules.
|
|
|
|
|
|
<!-- BEGIN TOC -->
|
|
- [Basic example with IAM bindings](#basic-example-with-iam-bindings)
|
|
- [IAM](#iam)
|
|
- [Organization policies](#organization-policies)
|
|
- [Organization Policy Factory](#organization-policy-factory)
|
|
- [Hierarchical Firewall Policies](#hierarchical-firewall-policies)
|
|
- [Directly Defined Firewall Policies](#directly-defined-firewall-policies)
|
|
- [Firewall Policy Factory](#firewall-policy-factory)
|
|
- [Log Sinks](#log-sinks)
|
|
- [Data Access Logs](#data-access-logs)
|
|
- [Tags](#tags)
|
|
- [Files](#files)
|
|
- [Variables](#variables)
|
|
- [Outputs](#outputs)
|
|
<!-- END TOC -->
|
|
|
|
## Basic example with IAM bindings
|
|
|
|
```hcl
|
|
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.
|
|
|
|
```hcl
|
|
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](../project#organization-policy-factory).
|
|
|
|
## 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](../../blueprints/factories) 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
|
|
|
|
```hcl
|
|
module "folder1" {
|
|
source = "./fabric/modules/folder"
|
|
parent = var.organization_id
|
|
name = "policy-container"
|
|
|
|
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"
|
|
}
|
|
}
|
|
|
|
module "folder2" {
|
|
source = "./fabric/modules/folder"
|
|
parent = var.organization_id
|
|
name = "hf2"
|
|
firewall_policy_association = {
|
|
iap-policy = module.folder1.firewall_policy_id["iap-policy"]
|
|
}
|
|
}
|
|
# tftest modules=2 resources=7 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`).
|
|
|
|
```hcl
|
|
module "folder1" {
|
|
source = "./fabric/modules/folder"
|
|
parent = var.organization_id
|
|
name = "policy-container"
|
|
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 = "iap-policy"
|
|
}
|
|
}
|
|
|
|
module "folder2" {
|
|
source = "./fabric/modules/folder"
|
|
parent = var.organization_id
|
|
name = "hf2"
|
|
firewall_policy_association = {
|
|
iap-policy = module.folder1.firewall_policy_id["iap-policy"]
|
|
}
|
|
}
|
|
# tftest modules=2 resources=7 files=cidrs,rules inventory=hfw.yaml
|
|
```
|
|
|
|
```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
|
|
```
|
|
|
|
```yaml
|
|
# 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
|
|
|
|
```hcl
|
|
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:
|
|
|
|
```hcl
|
|
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:
|
|
|
|
```hcl
|
|
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](https://cloud.google.com/resource-manager/docs/tags/tags-creating-and-managing) documentation for details on usage.
|
|
|
|
```hcl
|
|
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
|
|
```
|
|
|
|
<!-- TFDOC OPTS files:1 -->
|
|
<!-- BEGIN TFDOC -->
|
|
|
|
## Files
|
|
|
|
| name | description | resources |
|
|
|---|---|---|
|
|
| [firewall-policies.tf](./firewall-policies.tf) | None | <code>google_compute_firewall_policy</code> · <code>google_compute_firewall_policy_association</code> · <code>google_compute_firewall_policy_rule</code> |
|
|
| [iam.tf](./iam.tf) | IAM bindings, roles and audit logging resources. | <code>google_folder_iam_binding</code> · <code>google_folder_iam_member</code> · <code>google_folder_iam_policy</code> |
|
|
| [logging.tf](./logging.tf) | Log sinks and supporting resources. | <code>google_bigquery_dataset_iam_member</code> · <code>google_folder_iam_audit_config</code> · <code>google_logging_folder_exclusion</code> · <code>google_logging_folder_sink</code> · <code>google_project_iam_member</code> · <code>google_pubsub_topic_iam_member</code> · <code>google_storage_bucket_iam_member</code> |
|
|
| [main.tf](./main.tf) | Module-level locals and resources. | <code>google_essential_contacts_contact</code> · <code>google_folder</code> |
|
|
| [organization-policies.tf](./organization-policies.tf) | Folder-level organization policies. | <code>google_org_policy_policy</code> |
|
|
| [outputs.tf](./outputs.tf) | Module outputs. | |
|
|
| [tags.tf](./tags.tf) | None | <code>google_tags_tag_binding</code> |
|
|
| [variables.tf](./variables.tf) | Module variables. | |
|
|
| [versions.tf](./versions.tf) | Version pins. | |
|
|
|
|
## Variables
|
|
|
|
| name | description | type | required | default |
|
|
|---|---|:---:|:---:|:---:|
|
|
| [contacts](variables.tf#L17) | 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. | <code>map(list(string))</code> | | <code>{}</code> |
|
|
| [firewall_policies](variables.tf#L24) | Hierarchical firewall policies created in this folder. | <code title="map(map(object({ action = string description = string direction = string logging = bool ports = map(list(string)) priority = number ranges = list(string) target_resources = list(string) target_service_accounts = list(string) })))">map(map(object({…})))</code> | | <code>{}</code> |
|
|
| [firewall_policy_association](variables.tf#L41) | 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. | <code>map(string)</code> | | <code>{}</code> |
|
|
| [firewall_policy_factory](variables.tf#L48) | Configuration for the firewall policy factory. | <code title="object({ cidr_file = string policy_name = string rules_file = string })">object({…})</code> | | <code>null</code> |
|
|
| [folder_create](variables.tf#L58) | Create folder. When set to false, uses id to reference an existing folder. | <code>bool</code> | | <code>true</code> |
|
|
| [group_iam](variables.tf#L64) | 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. | <code>map(list(string))</code> | | <code>{}</code> |
|
|
| [iam](variables.tf#L71) | IAM bindings in {ROLE => [MEMBERS]} format. | <code>map(list(string))</code> | | <code>{}</code> |
|
|
| [iam_additive](variables.tf#L78) | Non authoritative IAM bindings, in {ROLE => [MEMBERS]} format. | <code>map(list(string))</code> | | <code>{}</code> |
|
|
| [iam_additive_members](variables.tf#L85) | IAM additive bindings in {MEMBERS => [ROLE]} format. This might break if members are dynamic values. | <code>map(list(string))</code> | | <code>{}</code> |
|
|
| [iam_policy](variables.tf#L92) | IAM authoritative policy in {ROLE => [MEMBERS]} format. Roles and members not explicitly listed will be cleared, use with extreme caution. | <code>map(list(string))</code> | | <code>null</code> |
|
|
| [id](variables.tf#L98) | Folder ID in case you use folder_create=false. | <code>string</code> | | <code>null</code> |
|
|
| [logging_data_access](variables.tf#L104) | Control activation of data access logs. Format is service => { log type => [exempted members]}. The special 'allServices' key denotes configuration for all services. | <code>map(map(list(string)))</code> | | <code>{}</code> |
|
|
| [logging_exclusions](variables.tf#L119) | Logging exclusions for this folder in the form {NAME -> FILTER}. | <code>map(string)</code> | | <code>{}</code> |
|
|
| [logging_sinks](variables.tf#L126) | Logging sinks to create for the organization. | <code title="map(object({ bq_partitioned_table = optional(bool) description = optional(string) destination = string disabled = optional(bool, false) exclusions = optional(map(string), {}) filter = string include_children = optional(bool, true) type = string }))">map(object({…}))</code> | | <code>{}</code> |
|
|
| [name](variables.tf#L156) | Folder name. | <code>string</code> | | <code>null</code> |
|
|
| [org_policies](variables.tf#L162) | Organization policies applied to this folder keyed by policy name. | <code title="map(object({ inherit_from_parent = optional(bool) # for list policies only. reset = optional(bool) rules = optional(list(object({ allow = optional(object({ all = optional(bool) values = optional(list(string)) })) deny = optional(object({ all = optional(bool) values = optional(list(string)) })) enforce = optional(bool) # for boolean policies only. condition = optional(object({ description = optional(string) expression = optional(string) location = optional(string) title = optional(string) }), {}) })), []) }))">map(object({…}))</code> | | <code>{}</code> |
|
|
| [org_policies_data_path](variables.tf#L189) | Path containing org policies in YAML format. | <code>string</code> | | <code>null</code> |
|
|
| [parent](variables.tf#L195) | Parent in folders/folder_id or organizations/org_id format. | <code>string</code> | | <code>null</code> |
|
|
| [tag_bindings](variables.tf#L205) | Tag bindings for this folder, in key => tag value id format. | <code>map(string)</code> | | <code>null</code> |
|
|
|
|
## Outputs
|
|
|
|
| name | description | sensitive |
|
|
|---|---|:---:|
|
|
| [firewall_policies](outputs.tf#L16) | Map of firewall policy resources created in this folder. | |
|
|
| [firewall_policy_id](outputs.tf#L21) | Map of firewall policy ids created in this folder. | |
|
|
| [folder](outputs.tf#L26) | Folder resource. | |
|
|
| [id](outputs.tf#L31) | Fully qualified folder id. | |
|
|
| [name](outputs.tf#L41) | Folder name. | |
|
|
| [sink_writer_identities](outputs.tf#L46) | Writer identities created for each sink. | |
|
|
|
|
<!-- END TFDOC -->
|