README.md

Overview

TF Cloud Build Workspace blueprint creates an opinionated workflow for actuating Terraform on Cloud Build. A set of Cloud Build triggers manage plan and apply operations on a root configuration stored in a VCS repo. Cloud Build triggers use a per workspace Service Account which can be configured with minimal permissions required by a given Terraform configuration. Optionally dedicated GCS buckets for state and log storage are also created.

Github Requirements for Cloud Build Connection

When using a Cloud Build 2nd generation repository, a Cloud Build connection to your repository provider will be needed. For Github connections you will need:

• Install Cloud Build App on Github.
• Create Personal Access Token on Github with repo and read:user (or if app is installed in org use read:org).

For more information on this topic refer to the "Connect with Github Documentation"

Usage

Basic usage of this module is as follows:

module "tf-net-workspace" {
  source  = "terraform-google-modules/bootstrap/google//modules/tf_cloudbuild_workspace"
  version = "~> 11.0"

  project_id          = var.project_id
  tf_repo_uri         = "https://github.com/org/tf-config-repo"
  cloudbuild_sa_roles = { var.project_id = ["roles/compute.networkAdmin"] }
}

Functional examples are included in the examples directory.

Resources created

This module creates:

• Two Cloud Build triggers with an inline build configuration for planning and applying Terraform configuration. Optionally custom in repo build configs can be specified.
• Optional custom Service Account and roles for that SA used by Cloud Build triggers.
• GCS buckets for storing Terraform state, logs, and plans.

Notes

• When a custom Service Account is provided via cloudbuild_sa and diff_sa_project is true (i.e SA is in a different project) follow these instructions to confirm iam.disableCrossProjectServiceAccountUsage org policy is not enforced in the SA project.
• If a custom build config is specified via cloudbuild_plan/apply_filename, a log bucket must be specified in the build config. For ease of use, we populate _LOG_BUCKET_NAME as a substitution and can be used like logsBucket: 'gs://$_LOG_BUCKET_NAME'.

Inputs

Name	Description	Type	Default	Required
artifacts_bucket_name	Custom bucket name for Cloud Build artifacts.	string	""	no
buckets_force_destroy	When deleting the bucket for storing CloudBuild logs/TF state, this boolean option will delete all contained objects. If false, Terraform will fail to delete buckets which contain objects.	bool	false	no
cloudbuild_apply_filename	Optional Cloud Build YAML definition used for terraform apply. Defaults to using inline definition.	string	null	no
cloudbuild_env_vars	Optional list of environment variables to be used in builds. List of strings of form KEY=VALUE expected.	list(string)	[]	no
cloudbuild_ignored_files	Optional list. Changes only affecting ignored files will not invoke a build.	list(string)	[]	no
cloudbuild_included_files	Optional list. Changes affecting at least one of these files will invoke a build.	list(string)	[]	no
cloudbuild_plan_filename	Optional Cloud Build YAML definition used for terraform plan. Defaults to using inline definition.	string	null	no
cloudbuild_sa	Custom SA id of form projects/{{project}}/serviceAccounts/{{email}} to be used by the CloudBuild trigger. Defaults to being created if empty.	string	""	no
cloudbuild_sa_roles	Optional to assign to custom CloudBuild SA. Map of project name or any static key to object with project_id and list of roles.	map(object({ project_id = string roles = list(string) }))	{}	no
create_cloudbuild_sa	Create a Service Account for use in Cloud Build. If false cloudbuild_sa has to be specified.	bool	true	no
create_cloudbuild_sa_name	Custom name to be used in the creation of the Cloud Build service account if create_cloudbuild_sa is true. Defaults to generated name if empty	string	""	no
create_state_bucket	Create a GCS bucket for storing state. If false state_bucket_self_link has to be specified.	bool	true	no
create_state_bucket_name	Custom bucket name for storing TF state. Used if create_state_bucket is true. Defaults to generated name if empty.	string	""	no
diff_sa_project	Set to true if cloudbuild_sa is in a different project for setting up https://cloud.google.com/build/docs/securing-builds/configure-user-specified-service-accounts#cross-project_set_up.	bool	false	no
enable_worker_pool	Set to true to use a private worker pool in the Cloud Build Trigger.	bool	false	no
location	Location for build logs/state bucket	string	"us-central1"	no
log_bucket_name	Custom bucket name for Cloud Build logs.	string	""	no
prefix	Prefix of the state/log buckets and triggers planning/applying config. If unset computes a prefix from tf_repo_uri and tf_repo_dir variables.	string	""	no
project_id	GCP project for Cloud Build triggers, state and log buckets.	string	n/a	yes
state_bucket_self_link	Custom GCS bucket for storing TF state. Defaults to being created if empty.	string	""	no
substitutions	Map of substitutions to use in builds.	map(string)	{}	no
tf_apply_branches	List of git branches configured to run terraform apply Cloud Build trigger. All other branches will run plan by default.	list(string)	[ "main" ]	no
tf_cloudbuilder	Name of the Cloud Builder image used for running build steps.	string	"hashicorp/terraform:1.3.10"	no
tf_repo_dir	The directory inside the repo where the Terrafrom root config is located. If empty defaults to repo root.	string	""	no
tf_repo_type	Type of repo. When the repo type is CLOUDBUILD_V2_REPOSITORY, it will use the generic Cloudbuild 2nd gen Repository API.	string	"CLOUD_SOURCE_REPOSITORIES"	no
tf_repo_uri	The URI of the repo where Terraform configs are stored. If using Cloud Build Repositories (2nd Gen) this is the repository ID where the Dockerfile is stored. Repository ID Format is 'projects/{{project}}/locations/{{location}}/connections/{{parent_connection}}/repositories/{{name}}'.	string	""	no
trigger_location	Location of for Cloud Build triggers created in the workspace. If using private pools should be the same location as the pool.	string	n/a	yes
worker_pool_id	Custom private worker pool ID. Format: 'projects/PROJECT_ID/locations/REGION/workerPools/PRIVATE_POOL_ID'.	string	""	no

Outputs

Name	Description
artifacts_bucket	Bucket for storing TF plans
cloudbuild_apply_trigger_id	Trigger used for running TF apply
cloudbuild_plan_trigger_id	Trigger used for running TF plan
cloudbuild_sa	SA used by Cloud Build triggers
logs_bucket	Bucket for storing TF logs
state_bucket	Bucket for storing TF state

Requirements

Software

• Terraform >= 1.3
• [terraform-provider-google] plugin >= 3.50.x

Permissions

• roles/cloudbuild.builds.editor
• roles/storage.admin
• roles/iam.serviceAccountCreator

APIs

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

"iam.googleapis.com",
"compute.googleapis.com",
"cloudbuild.googleapis.com",

Contributing

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