Repository files navigation

FAQ |Troubleshooting Guide |Glossary.

This module allows you to create opinionated Google Cloud Platform projects. Itcreates projects and configures aspects like Shared VPC connectivity, IAMaccess, Service Accounts, and API enablement to follow best practices.

To include G Suite integration for creating groups and adding Service Accounts into groups, use thegsuite_enabled module.

This module is meant for use with Terraform 1.3+ and tested using Terraform 1.10+. If you find incompatibilities using Terraform >= 1.3, please open an issue.If you haven'tupgraded and need a Terraform0.12.x-compatible version of this module, the last released versionintended for Terraform 0.12.x is9.2.0.

See thedocs for detailed instructions on upgrading between major releases of the module.

There are multiple examples included in theexamples folder but simple usage is as follows:

module"project-factory" {source="terraform-google-modules/project-factory/google"version="~> 18.2"name="pf-test-1"random_project_id=trueorg_id="1234567890"usage_bucket_name="pf-test-1-usage-report-bucket"usage_bucket_prefix="pf/test/1/integration"billing_account="ABCDEF-ABCDEF-ABCDEF"svpc_host_project_id="shared_vpc_host_name"shared_vpc_subnets=["projects/base-project-196723/regions/us-east1/subnetworks/default","projects/base-project-196723/regions/us-central1/subnetworks/default","projects/base-project-196723/regions/us-central1/subnetworks/subnet-1",  ]}

The Project Factory module will take the following actions:

1. Create a new GCP project using theproject_name.

2. If a shared VPC is specified, attach the new project to thesvpc_host_project_id.

   It will also give the following users network access on the specified subnets:

   • The project's new default service account (see step 4)
   • The Google API service account for the project
   • The project controlling group specified ingroup_name

3. Delete the default compute service account.

4. Create a new default service account for the project.

   1. Give it access to the shared VPC(to be able to launch instances).

5. Attach the billing account (billing_account) to the project.

6. Give the controlling group access to the project, with thegroup_role.

7. Enable the required and specified APIs (activate_apis).

8. Delete the default network.

9. Enable usage report for GCE into central project bucket(target_usage_bucket), if provided.

10. If specified, create the GCS bucketbucket_name and give thefollowing accounts Storage Admin on it:

    1. The controlling group (group_name).
    2. The new default compute service account created for the project.
    3. The Google APIs service account for the project.

The roles granted are specifically:

• New Default Service Account
  • compute.networkUser on host project or specified subnets
  • storage.admin onbucket_name GCS bucket
• group_name is the controlling group
  • compute.networkUser on host project or specific subnets
  • Specifiedgroup_role on project
  • iam.serviceAccountUser on the default Service Account
  • storage.admin onbucket_name GCS bucket
• Google APIs Service Account
  • compute.networkUser on host project or specified subnets
  • storage.admin onbucket_name GCS bucket

A service project's access to shared VPC networks is controlled via theroles/compute.networkUser role and the location to where that role isassigned. If that role is assigned to the shared VPC host project, then theservice project will have access toall shared VPC subnetworks. If that roleis assigned to individual subnetworks, then the service project will haveaccess to only the subnetworks on which that role was assigned. The logic fordetermining that location is as follows:

1. Ifvar.svpc_host_project_id andvar.shared_vpc_subnets are not set then thecompute.networkUser role is not assigned
2. Ifvar.svpc_host_project_id is set but no subnetworks are provided viavar.shared_vpc_subnets then thecompute.networkUser role is assigned at the host project and the service project will have access to all shared VPC subnetworks
3. Ifvar.svpc_host_project_id is set andvar.shared_vpc_subnets contains an array of subnetworks then thecompute.networkUser role is assigned to each subnetwork in the array

list(object({
    api   = string
    roles = list(string)
  }))

[
  "compute.googleapis.com"
]

[
  0.5,
  0.7,
  1
]

list(object({
    service    = string,
    metric     = string,
    dimensions = map(string),
    limit      = string,
    value      = string,
  }))

• gcloud sdk >= 269.0.0
• jq >= 1.6
• Terraform >= 1.3
• terraform-provider-google plugin >= 5.41
• terraform-provider-google-beta plugin >= 5.41
• terraform-provider-gsuite plugin ~> 0.1.x if GSuite functionality is desired

In order to execute this module you must have a Service Account with thefollowing roles:

• roles/resourcemanager.folderViewer on the folder that you want to create theproject in
• roles/resourcemanager.organizationViewer on the organization
• roles/resourcemanager.projectCreator on the organization
• roles/billing.user on the organization
• roles/storage.admin on bucket_project
• If you are using shared VPC:
  • roles/billing.user on the organization
  • roles/compute.xpnAdmin on the organization
  • roles/compute.networkAdmin on the organization
  • roles/browser on the Shared VPC host project
  • roles/resourcemanager.projectIamAdmin on the Shared VPC host project

Ahelper script is included to create the Seed ServiceAccount in theSeed Project,grant the necessary roles to theSeed Service Account,and enable the necessary API's in the Seed Project. Run it as follows:

./helpers/setup-sa.sh -o<organization id> -p<project id> [-b<billing account id>] [-f<folder id>] [-n<service account name>]

In order to execute this script, you must have an account with the following list ofpermissions:

• resourcemanager.organizations.list
• resourcemanager.projects.list
• billing.accounts.list
• iam.serviceAccounts.create
• iam.serviceAccountKeys.create
• resourcemanager.organizations.setIamPolicy
• resourcemanager.projects.setIamPolicy
• serviceusage.services.enable on the project
• servicemanagement.services.bind on following services:
  • cloudresourcemanager.googleapis.com
  • cloudbilling.googleapis.com
  • iam.googleapis.com
  • admin.googleapis.com
  • appengine.googleapis.com
• billing.accounts.getIamPolicy on a billing account.
• billing.accounts.setIamPolicy on a billing account.

The Project Factory module uses theGoogle Terraform providerto authenticate all GCP API calls.To configure credentials, you should configure thegoogle andgoogle-beta providers.

provider"google" {credentials="${file(var.credentials_path)}"}provider"google-beta" {credentials="${file(var.credentials_path)}"}

In order to operate the Project Factory, you must activate the following APIs onthe base project where the Service Account was created:

• Cloud Resource Manager API -cloudresourcemanager.googleapis.comtroubleshooting
• Cloud Billing API -cloudbilling.googleapis.comtroubleshooting
• Identity and Access Management API -iam.googleapis.comtroubleshooting
• Admin SDK -admin.googleapis.comtroubleshooting

• Google App Engine Admin API -appengine.googleapis.comtroubleshooting
  • Please note that if you are deploying an App Engine Flex application, you should not delete the default compute service account(as is default behavior). Please see thetroubleshooting doc for more information.
• Cloud Billing Budget API -billingbudgets.googleapis.com
  • Please note this API is only required if configuring budgets for projects.

Apreconditions checker script isincluded to verify that all preconditions are met before the Project Factoryruns. The script will run automatically if the script dependencies (Python,"google-auth", and "google-api-python-client") are available at runtime. If thedependencies are not met, the precondition checking step will be skipped.

The precondition checker script can be directly invoked before running theproject factory:

./helpers/preconditions/preconditions.py \  --credentials_path"./credentials.json" \  --billing_account 000000-000000-000000 \  --org_id 000000000000 \  --folder_id 000000000000 \  --shared_vpc'shared-vpc-host-ed64'

There is currently a bug with moving a project which was originally created atthe root of the organization into a folder. The bug and workaround is describedhere,but as a general best practice it is easier to create all projects withinfolders to start. Moving projects between different foldersis supported.

Default SAs can be removed by settingdefault_service_account input variable todelete, but there can be certain scenarios where the default SAs are required. Hence some considerations to be aware of:

1. Using App Engine SA.
2. Cloud Scheduler dependency on AppEngine(default SA). Default SA is required to be able to setupCloud scheduler, please refer to thedocument for more upto date information.

With a combination of project-factory's default behavior,disable, and settingconstraints/iam.automaticIamGrantsForDefaultServiceAccounts org constraint will address removing the default editor IAM role on the SAs and limits the SA usage. However, when thedefault_service_account is set todelete please be aware of the default SA dependency for AppEngine/CloudScheduler services. Accounts deleted within 30days can berestored.

The core Project Factory solely deals with GCP APIs and does not integrate G Suite functionality. If you would like certain group-management functionality which was previously included in the Project Factory, see theG Suite module.

Be sure you have the correct Terraform version (1.3+), you can choose thebinary here:

• https://releases.hashicorp.com/terraform/