terraform-google-bootstrap

April 22, 2026 · View on GitHub

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 = "~> 12.0"

  org_id               = "<ORGANIZATION_ID>"
  billing_account      = "<BILLING_ACCOUNT_ID>"
  group_org_admins     = "gcp-organization-admins@example.com"
  group_billing_admins = "gcp-billing-admins@example.com"
  default_region       = "australia-southeast1"
}

Functional examples are included in the examples directory.

Features

The Organization Bootstrap module will take the following actions:

Create a new GCP seed project using project_prefix. Use project_id if you need to use custom project ID.
Enable APIs in the seed project using activate_apis
Create a new service account for terraform in seed project
Create GCS bucket for Terraform state and grant access to service account
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_auto_create_network	Create the default network for the project created.	`bool`	`false`	no
project_deletion_policy	The deletion policy for the project created.	`string`	`"PREVENT"`	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

gcloud sdk >= 206.0.0
Terraform >= 1.3
[terraform-provider-google] plugin 3.50.x

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.