Skip to content

Latest commit

 

History

History
123 lines (94 loc) · 8 KB

README.md

File metadata and controls

123 lines (94 loc) · 8 KB
Raw

terraform-google-bootstrap

The purpose of this module is to help bootstrap a GCP organization, creating all the required GCP resources & permissions to start using the Cloud Foundation Toolkit (CFT). For users who want to use Cloud Build & Cloud Source Repos for foundations code, there is also a submodule to help bootstrap all the required resources to do this.

Usage

Basic usage of this module is as follows:

module "bootstrap" {
  source  = "terraform-google-modules/bootstrap/google"
  version = "~> 7.2"

  org_id               = "<ORGANIZATION_ID>"
  billing_account      = "<BILLING_ACCOUNT_ID>"
  group_org_admins     = "[email protected]"
  group_billing_admins = "[email protected]"
  default_region       = "australia-southeast1"
}

Functional examples are included in the examples directory.

Features

The Organization Bootstrap module will take the following actions:

  1. Create a new GCP seed project using project_prefix. Use project_id if you need to use custom project ID.
  2. Enable APIs in the seed project using activate_apis
  3. Create a new service account for terraform in seed project
  4. Create GCS bucket for Terraform state and grant access to service account
  5. Grant IAM permissions required for CFT modules & Organization setup
    1. Overwrite organization wide project creator and billing account creator roles
    2. Grant Organization permissions to service account using sa_org_iam_permissions
    3. Grant access to billing account for service account
    4. Grant Organization permissions to group_org_admins using org_admins_org_iam_permissions
    5. Grant billing permissions to group_billing_admins
    6. (optional) Permissions required for service account impersonation using sa_enable_impersonation

For the cloudbuild submodule, see the README cloudbuild.

Inputs

Name Description Type Default Required
activate_apis List of APIs to enable in the seed project. list(string) 
[
  "serviceusage.googleapis.com",
  "servicenetworking.googleapis.com",
  "compute.googleapis.com",
  "logging.googleapis.com",
  "bigquery.googleapis.com",
  "cloudresourcemanager.googleapis.com",
  "cloudbilling.googleapis.com",
  "iam.googleapis.com",
  "admin.googleapis.com",
  "appengine.googleapis.com",
  "storage-api.googleapis.com",
  "monitoring.googleapis.com"
]
 no
billing_account The ID of the billing account to associate projects with. string n/a yes
create_terraform_sa If the Terraform service account should be created. bool true no
default_region Default region to create resources where applicable. string "us-central1" no
encrypt_gcs_bucket_tfstate Encrypt bucket used for storing terraform state files in seed project. bool false no
folder_id The ID of a folder to host this project string "" no
force_destroy If supplied, the state bucket will be deleted even while containing objects. bool false no
grant_billing_user Grant roles/billing.user role to CFT service account bool true no
group_billing_admins Google Group for GCP Billing Administrators string n/a yes
group_org_admins Google Group for GCP Organization Administrators string n/a yes
key_protection_level The protection level to use when creating a version based on this template. Default value: "SOFTWARE" Possible values: ["SOFTWARE", "HSM"] string "SOFTWARE" no
key_rotation_period The rotation period of the key. string null no
kms_prevent_destroy Set the prevent_destroy lifecycle attribute on keys. bool true no
org_admins_org_iam_permissions List of permissions granted to the group supplied in group_org_admins variable across the GCP organization. list(string) 
[
  "roles/billing.user",
  "roles/resourcemanager.organizationAdmin"
]
 no
org_id GCP Organization ID string n/a yes
org_project_creators Additional list of members to have project creator role accross the organization. Prefix of group: user: or serviceAccount: is required. list(string) [] no
parent_folder GCP parent folder ID in the form folders/{id} string "" no
project_id Custom project ID to use for project created. If not supplied, the default id is {project_prefix}-seed-{random suffix}. string "" no
project_labels Labels to apply to the project. map(string) {} no
project_prefix Name prefix to use for projects created. string "cft" no
random_suffix Appends a 4 character random suffix to project ID and GCS bucket name. bool true no
sa_enable_impersonation Allow org_admins group to impersonate service account & enable APIs required. bool false no
sa_org_iam_permissions List of permissions granted to Terraform service account across the GCP organization. list(string) 
[
  "roles/billing.user",
  "roles/compute.networkAdmin",
  "roles/compute.xpnAdmin",
  "roles/iam.securityAdmin",
  "roles/iam.serviceAccountAdmin",
  "roles/logging.configWriter",
  "roles/orgpolicy.policyAdmin",
  "roles/resourcemanager.folderAdmin",
  "roles/resourcemanager.organizationViewer"
]
 no
state_bucket_name Custom state bucket name. If not supplied, the default name is {project_prefix}-tfstate-{random suffix}. string "" no
storage_bucket_labels Labels to apply to the storage bucket. map(string) {} no
tf_service_account_id ID of service account for terraform in seed project string "org-terraform" no
tf_service_account_name Display name of service account for terraform in seed project string "CFT Organization Terraform Account" no

Outputs

Name Description
gcs_bucket_tfstate Bucket used for storing terraform state for foundations pipelines in seed project.
seed_project_id Project where service accounts and core APIs will be enabled.
terraform_sa_email Email for privileged service account for Terraform.
terraform_sa_name Fully qualified name for privileged service account for Terraform.

Requirements

Software

Permissions

  • roles/resourcemanager.organizationAdmin on GCP Organization
  • roles/orgpolicy.policyAdmin on GCP Organization
  • roles/billing.admin on supplied billing account
  • Account running terraform should be a member of group provided in group_org_admins variable, otherwise they will loose roles/resourcemanager.projectCreator access. Additional members can be added by using the org_project_creators variable.

Credentials

For users interested in using service account impersonation which this module helps enable with sa_enable_impersonation, please see this blog post which explains how it works.

APIs

A project with the following APIs enabled must be used to host the resources of this module:

  • Google Cloud Resource Manager API: cloudresourcemanager.googleapis.com
  • Google Cloud Billing API: cloudbilling.googleapis.com
  • Google Cloud IAM API: iam.googleapis.com
  • Google Cloud Storage API storage-api.googleapis.com
  • Google Cloud Service Usage API: serviceusage.googleapis.com

This API can be enabled in the default project created during establishing an organization.

Contributing

Refer to the contribution guidelines for information on contributing to this module.