diff --git a/modules/folder/README.md b/modules/folder/README.md index f9229f951f..a4b8d804a7 100644 --- a/modules/folder/README.md +++ b/modules/folder/README.md @@ -2,6 +2,17 @@ This module allows the creation and management of folders, including support for IAM bindings, organization policies, and hierarchical firewall rules. +## Features + +- [IAM](#iam) +- [Organization Policies](#organization-policies) + - [Factory](#organization-policy-factory) +- [Hierarchical Firewall Policies](#hierarchical-firewall-policies) + - [Directly Defined](#directly-defined-firewall-policies) + - [Factory](#firewall-policy-factory) +- [Log Sinks](#log-sinks) +- [Tags](#tags) + ## Basic example with IAM bindings ```hcl @@ -31,6 +42,15 @@ module "folder" { # tftest modules=1 resources=9 inventory=iam.yaml ``` +## IAM + +There are two 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 + +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. @@ -88,76 +108,11 @@ module "folder" { # tftest modules=1 resources=8 inventory=org-policies.yaml ``` -### Organization policy factory +### Organization Policy Factory See the [organization policy factory in the project module](../project#organization-policy-factory). -## Logging 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 -``` - -## Hierarchical firewall policies +## Hierarchical Firewall Policies Hierarchical firewall policies can be managed in two ways: @@ -166,7 +121,7 @@ Hierarchical firewall policies can be managed in two ways: 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 +### Directly Defined Firewall Policies ```hcl module "folder1" { @@ -216,7 +171,7 @@ module "folder2" { # tftest modules=2 resources=7 inventory=hfw.yaml ``` -### Firewall policy factory +### 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`). @@ -281,6 +236,71 @@ allow-iap-ssh: 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 +``` + ## 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. diff --git a/modules/organization/README.md b/modules/organization/README.md index 6286f3f3f8..9ae8b299bb 100644 --- a/modules/organization/README.md +++ b/modules/organization/README.md @@ -10,6 +10,20 @@ This module allows managing several organization properties: To manage organization policies, the `orgpolicy.googleapis.com` service should be enabled in the quota project. +## Features + +- [IAM](#iam) +- [Organization Policies](#organization-policies) + - [Factory](#organization-policy-factory) + - [Custom Constraints](#organization-policy-custom-constraints) + - [Custom Constraints Factory](#organization-policy-custom-constraints-factory) +- [Hierarchical Firewall Policies](#hierarchical-firewall-policies) + - [Directly Defined](#directly-defined-firewall-policies) + - [Factory](#firewall-policy-factory) +- [Log Sinks](#log-sinks) +- [Custom Roles](#custom-roles) +- [Tags](#tags) + ## Example ```hcl @@ -110,11 +124,13 @@ If you set audit policies via the `iam_audit_config_authoritative` variable, be Some care must also 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 policy factory +## Organization Policies + +### Organization Policy Factory See the [organization policy factory in the project module](../project#organization-policy-factory). -### Org policy custom constraints +### Organization Policy Custom Constraints Refer to the [Creating and managing custom constraints](https://cloud.google.com/resource-manager/docs/organization-policy/creating-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. @@ -145,7 +161,7 @@ module "org" { # tftest modules=1 resources=2 inventory=custom-constraints.yaml ``` -### Org policy custom constraints factory +### 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. @@ -201,7 +217,7 @@ custom.dataprocNoMoreThan10Workers: description: Cluster cannot have more than 10 workers, including primary and secondary workers. ``` -## Hierarchical firewall policies +## Hierarchical Firewall Policies Hierarchical firewall policies can be managed in two ways: @@ -210,7 +226,7 @@ Hierarchical firewall policies can be managed in two ways: 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 +### Directly Defined Firewall Policies ```hcl module "org" { @@ -251,7 +267,7 @@ module "org" { # tftest modules=1 resources=4 inventory=hfw.yaml ``` -### Firewall policy factory +### 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`). @@ -306,7 +322,7 @@ allow-iap-ssh: logging: false ``` -## Logging Sinks +## Log Sinks ```hcl module "gcs" { diff --git a/modules/project/README.md b/modules/project/README.md index 56b7d5a5b3..6fb3d42f4e 100644 --- a/modules/project/README.md +++ b/modules/project/README.md @@ -2,7 +2,24 @@ This module implements the creation and management of one GCP project including IAM, organization policies, Shared VPC host or service attachment, service API activation, and tag attachment. It also offers a convenient way to refer to managed service identities (aka robot service accounts) for APIs. -# Basic Project Creation +## Features + +- [Basic Project Creation](#basic-project-creation) +- [IAM](#iam) + - [Authoritative](#authoritative-iam) + - [Additive](#additive-iam) + - [Additive By Member](#additive-iam-by-member) + - [Service Identities and Authoritative IAM](#service-identities-and-authoritative-iam) + - [Using Shortcodes for Service Identities](#using-shortcodes-for-service-identities-in-additive-iam) + - [Service Identities and Manual IAM Grants](#service-identities-requiring-manual-iam-grants) +- [Shared VPC](#shared-vpc) +- [Organization Policies](#organization-policies) + - [Factory](#organization-policy-factory) +- [Log Sinks](#log-sinks) +- [Cloud KMS Encryption Keys](#cloud-kms-encryption-keys) +- [Tags](#tags) + +## Basic Project Creation ```hcl module "project" { @@ -19,7 +36,7 @@ module "project" { # tftest modules=1 resources=3 inventory=basic.yaml ``` -## IAM Examples +## IAM IAM is managed via several variables that implement different levels of control: @@ -101,7 +118,7 @@ module "project" { # tftest modules=1 resources=5 inventory=iam-additive.yaml ``` -### Additive IAM by members +### Additive IAM by Member ```hcl module "project" { @@ -116,7 +133,7 @@ module "project" { # tftest modules=1 resources=4 inventory=iam-additive-members.yaml ``` -### Service Identities and authoritative IAM +### Service Identities and Authoritative IAM As mentioned above, there are cases where authoritative management of specific IAM roles results in removal of default bindings from service identities. One example is outlined below, with a simple workaround leveraging the `service_accounts` output to identify the service identity. A full list of service identities and their roles can be found [here](https://cloud.google.com/iam/docs/service-agents). @@ -138,7 +155,8 @@ module "project" { # tftest modules=1 resources=2 ``` -### Using shortcodes for Service Identities in additive IAM +### Using Shortcodes for Service Identities in Additive Iam + Most Service Identities contains project number in their e-mail address and this prevents additive IAM to work, as these values are not known at moment of execution of `terraform plan` (its not an issue for authoritative IAM). To refer current project Service Identities you may use shortcodes for Service Identities similarly as for `service_identity_iam` when configuring Shared VPC. ```hcl @@ -160,8 +178,7 @@ module "project" { # tftest modules=1 resources=6 ``` - -### Service identities requiring manual IAM grants +### Service Identities Requiring Manual Iam Grants The module will create service identities at project creation instead of creating of them at the time of first use. This allows granting these service identities roles in other projects, something which is usually necessary in a Shared VPC context. @@ -194,7 +211,6 @@ This table lists all affected services and roles that you need to grant to servi | pubsub.googleapis.com | pubsub | roles/pubsub.serviceAgent | | sqladmin.googleapis.com | sqladmin | roles/cloudsql.serviceAgent | - ## Shared VPC The module allows managing Shared VPC status for both hosts and service projects, and includes a simple way of assigning Shared VPC roles to service identities. @@ -231,7 +247,7 @@ module "service-project" { # tftest modules=2 resources=8 inventory=shared-vpc.yaml ``` -## Organization policies +## Organization Policies To manage organization policies, the `orgpolicy.googleapis.com` service should be enabled in the quota project. @@ -290,7 +306,7 @@ module "project" { # tftest modules=1 resources=8 inventory=org-policies.yaml ``` -### Organization policy factory +### Organization Policy Factory Organization policies can be loaded from a directory containing YAML files where each file defines one or more constraints. The structure of the YAML files is exactly the same as the `org_policies` variable. @@ -351,8 +367,7 @@ iam.allowedPolicyMemberDomains: - C0yyyyyyy ``` - -## Logging Sinks +## Log Sinks ```hcl module "gcs" { @@ -418,7 +433,7 @@ module "project-host" { # tftest modules=5 resources=14 inventory=logging.yaml ``` -## Cloud KMS encryption keys +## Cloud Kms Encryption Keys The module offers a simple, centralized way to assign `roles/cloudkms.cryptoKeyEncrypterDecrypter` to service identities.