Google Cloud Build provides a serverless continuous integration and continuous delivery platform that executes builds based on a yaml configuration. Terraform provides a declarative configuration language and workflow to provision and manage cloud infrastructure. Combining the two closes the loop where the CI/CD pipeline itself is managed as infrastructure as code, allowing Cloud Build triggers, service accounts, and API enablement to be versioned, planned, and applied through Terraform.
The Terraform provider for Google Cloud lets you provision and manage Google Cloud resources, including Cloud Build. Terraform provides plugins called providers that let you interact with cloud providers and other APIs. Terraform has a declarative and configuration-oriented syntax, which you can use to describe the infrastructure that you want to provision in your Google Cloud project. After you author this configuration in one or more Terraform configuration files, you can use the Terraform CLI to apply this configuration to your Cloud Build resources.
Terraform works through a predictable workflow:
- You describe the infrastructure you want to provision in a Terraform configuration file. You don't need to write code describing how to provision the infrastructure. Terraform provisions the infrastructure for you.
- You run the
terraform plancommand, which evaluates your configuration and generates an execution plan. You can review the plan and make changes as needed
The standard three commands familiar to Terraform users are:
terraform init
to initialize, followed by terraform plan
to preview, and terraform apply
to deploy
Manually running these commands is useful for learning Terraform or managing your own personal infrastructure in the Cloud, but in practice you’re going to need to learn how to automate Terraform. Let some robots do it for you.
Core Concepts
How Terraform interacts with Cloud Build
HashiCorp Terraform is an infrastructure-as-code tool that lets you provision and manage cloud infrastructure. Terraform provides plugins called providers that let you interact with cloud providers and other APIs. You can use the Terraform provider for Google Cloud to provision and manage Google Cloud resources, including Cloud Build.
Each resource block describes one or more infrastructure objects, such as virtual networks or compute instances.
The Terraform resources available for Cloud Build are organized by service version.
| Cloud Build service | Terraform Resources | Data sources |
|---|---|---|
| Cloud Build v1 | googlecloudbuildtrigger | |
| Cloud Build v2 | googlecloudbuildv2connectioniampolicy |
Terraform-based guides for Cloud Build
The following table lists Terraform-based how-to guides and tutorials for Cloud Build:
| Guide | Details |
|---|---|
| Connect to a GitHub repository | This guide explains how to connect a GitHub repository to Cloud Build using Terraform. |
| Connect to a GitHub Enterprise host | This guide explains how to connect a GitHub Enterprise host to Cloud Build using Terraform. |
| Connect to a GitHub Enterprise repository | This guide explains how to connect a GitHub Enterprise repository to Cloud Build using Terraform. |
| Connect to a GitLab Enterprise Edition host | This guide explains how to connect a GitLab Enterprise Edition host to Cloud Build using Terraform. |
| Connect to a GitLab Enterprise Edition repository | This guide explains how to connect a GitLab Enterprise Edition repository to Cloud Build using Terraform. |
| Connect to a Bitbucket Data Center host | This guide explains how to connect a Bitbucket Data Center host to Cloud Build using Terraform |
Project Structure and Provider Setup
Managing Cloud Build with Terraform benefits from a modular layout that separates concerns.
.
├── main.tf # Main Terraform configuration file
├── variables.tf # Variable definitions
├── outputs.tf # Output definitions
├── terraform.tfvars # Variable values
└── modules/
└── cloudbuild/
├── main.tf # Cloud Build specific configurations
├── variables.tf # Module variables
├── triggers.tf # Build trigger configurations
└── outputs.tf # Module outputs
Provider Configuration
terraform {
required_providers {
google = {
source = "hashicorp/google"
version = "~> 4.0"
}
}
}
provider "google" {
project = var.project_id
region = var.region
}
Variables
variable "project_id" {
description = "The ID of the GCP project"
type = string
}
variable "region" {
description = "The region to deploy resources to"
type = string
default = "us-central1"
}
variable "github_owner" {
description = "GitHub repository owner"
type = string
}
variable "github_repo" {
description = "GitHub repository name"
type = string
}
Prerequisites for working with Cloud Build and Terraform include:
- Google Cloud SDK installed and configured
- Terraform installed (version 1.0.0 or later)
- A GCP project with billing enabled
Before starting a Cloud Build as code workflow, make sure you have:
- Cloud Build API enabled
- A source repository connected to Cloud Build (GitHub, Bitbucket, or Cloud Source Repositories for existing CSR customers)
- A service account for Terraform with appropriate permissions
- A GCS bucket for Terraform state
Enable the required APIs:
gcloud services enable cloudbuild.googleapis.com \
secretmanager.googleapis.com \
iam.googleapis.com \
--project=my-gcp-project
Cloud Build Triggers as Terraform Resources
Cloud Build is Google Cloud’s serverless CI/CD platform. You give it a yaml configuration with some instructions and it can build, test and deploy your software.
A basic Cloud Build Trigger resource declaration starts with:
resource "google_cloudbuild_trigger" "github_trigger" {
name = "github-trigger"
description = "Build
This resource type is part of Cloud Build v1. Terraform lets you define triggers that fire on source changes, schedule, or manually, and manage them alongside the rest of the infrastructure.
The workflow for a very basic example is to have a directory to work out of (a root Terraform module) with 2 files in it (for now):
cloudbuild.yamlmain.tf
You’ll also need a Google Cloud Project with the Cloud Build API enabled. When you enable the Cloud Build API, your project will generate a default Cloud Build service account that looks like this:
This service account automatically has the Cloud Build Service Account IAM role assigned to it, allowing it to do all the Cloud Build things it needs to be able to do, like manage Google Cloud Storage buckets and access Artifact Registry.
Terraform gets its instructions from .tf files. It will automatically look for a cloudbuild.yaml file and create a Cloud Build job that will execute the provided instructions. You can see the progress as output in your terminal or head over the Cloud Build History page where you’ll see your job’s status and output.
Service Accounts, Permissions and State
Setting Up the Cloud Build Service Account
Cloud Build uses a default service account, but for Terraform operations you should use a custom one with specific permissions:
resource "google_service_account" "terraform_builder" {
account_id = "terraform-builder"
display_name = "Terraform Cloud Build Service Account"
project = var.project_id
}
Grant Terraform the permissions it needs to manage infrastructure
locals {
terraform_roles =
Permissions considerations are critical when automating Terraform with Cloud Build. Cloud Build creates a default service account with those default Cloud Build service account permissions assigned to it. Any additional permissions that this service accounts needs will depend on the cloud resources that you want your Terraform to create. If you’re managing resources across lots of different Google Cloud services, then the Cloud Build service account will inevitably accumulate excessive permissions, resulting in a potential security risk.
Terraform state file management is a known challenge in ephemeral build environments. You’ll notice that the Terraform state file is no where to be found. The state file that would have been generated to your local disk had you ran terraform apply locally only existed temporarily in the container that Cloud Build ran the command from.
This leads to important operational considerations:
- Persistent state storage such as a GCS bucket for Terraform state is required for reliable operations
- Service account permissions must be scoped to the principle of least privilege
- The CI/CD pipeline itself is infrastructure as code, which means changes to triggers, service accounts, and API enablement can be reviewed via
terraform planbefore apply
Google Cloud Build is a natural choice for this when your infrastructure is on GCP, and managing those build triggers with Terraform closes the loop - your CI/CD pipeline itself is infrastructure as code.
Practical Workflow
A complete infrastructure CI/CD workflow with Terraform and Cloud Build involves:
- Authoring Terraform configuration that defines Cloud Build triggers, connections, and service accounts
- Using
terraform planto evaluate the configuration and generate an execution plan - Reviewing the plan and making changes as needed
- Applying the configuration to provision Cloud Build resources
This guide walks through setting up Cloud Build triggers with Terraform for a complete infrastructure CI/CD workflow.
Managing Cloud Build with Terraform lets you set up and manage Google Cloud Build using Terraform with version control, peer review, and automated application.
Conclusion
Using Terraform to manage Google Cloud Build transforms CI/CD configuration from manual console edits into declarative, versioned infrastructure. The Terraform provider for Google Cloud exposes resources such as google_cloudbuild_trigger for Cloud Build v1 and google_cloudbuildv2_connection_iam_policy for Cloud Build v2, enabling triggers and connections to be defined alongside the rest of a GCP project.
A modular project structure with main.tf, variables.tf, outputs.tf, and terraform.tfvars separates configuration from values, while a dedicated modules/cloudbuild directory isolates trigger logic. Provider configuration pins the Google provider to ~> 4.0 and sets project and region from variables, with a sensible default of us-central1.
Prerequisites remain essential: Cloud Build API enabled, source repository connected to Cloud Build, a service account for Terraform with appropriate permissions, and a GCS bucket for Terraform state. Enabling APIs with gcloud services enable for cloudbuild.googleapis.com, secretmanager.googleapis.com, and iam.googleapis.com establishes the foundation.
Service account design distinguishes between the default Cloud Build service account [email protected] created on API enablement and a custom service account such as terraform-builder for Terraform operations. Permission sprawl is a real risk when the Cloud Build service account accumulates access across many Google Cloud services, so scoping roles via locals and explicit IAM bindings is recommended.
State persistence is the key operational gap in a very basic example where the Terraform state file only exists temporarily in the container that Cloud Build runs the command from. Production workflows require persistent remote state and careful handling of secrets and credentials.
Overall, Terraform using Google Cloud Build provides a path to automate Terraform execution with a serverless CI/CD platform, starting from a simple cloudbuild.yaml and main.tf pair and evolving toward a full infrastructure as code CI/CD system where build triggers, service accounts, and API enablement are all managed declaratively.