Provision for Cloud Build service¶

Overview¶

Google Cloud Build is a fully managed continuous integration and continuous delivery (CI/CD) service that executes builds on Google Cloud infrastructure. It automates the process of building, testing, and deploying source code using defined triggers and build configurations.

This document describes the provisioning model, system architecture, workflow, security service accounts, and pricing structure for Cloud Build in a Google Cloud Platform (GCP) environment.

Scope and applicability:

• General-purpose CI/CD service: Supports automated build, test, and deployment workflows for diverse application types

• Multi-platform: Enables building artifacts across multiple operating systems, architectures, runtimes, and deployment targets

• Git-based workflows: Integrates with Git repositories to trigger builds from source code changes

• Google Cloud Platform environments: Designed to operate natively within Google Cloud infrastructure and services

SAD - System Architechture Design¶

The section is structured as follows:

• Provisioned Flow Overview explains the steady-state service model and responsibilities of Cloud Build once provisioning is complete.

• Detail Components defines the concrete resources, identities, and control elements that make up the provisioned service.

• Normal Operation Flow describes the runtime execution path that uses those components to handle build events.

Together, these parts describe the provisioned service boundary and the expected behavior of Cloud Build in production.

Provisioning Logic and Operational Flow¶

Cloud Build is provisioned as an event-driven, fully managed CI/CD service. Once triggers, worker pools, logging backends, and service accounts are configured, the service operates continuously without manual intervention.

This provisioning model provides:

• Continuous readiness for source control events

• Deterministic trigger evaluation

• Isolated build execution via private worker pools

• Secure access using managed service accounts

• Centralized logging and build metadata collection

The provisioning model defines the baseline behavior of Cloud Build and remains consistent across all executions.

The Cloud Build provisioning flow is shown in the following diagram:

flowchart LR

  subgraph code_storage[Code Storage]
    repository[Repository]
  end

  subgraph gcp[Google Cloud Platform]
    subgraph project[Project]
      direction LR

      subgraph cloud_build[Cloud Build]
        direction BT
        trigger[Trigger] --> execution[Execution] --> pool[Private Pool] --> runtime[Runtime Build]
      end

      subgraph log[Log Storage]
        direction LR
        gcs[Cloud Storage]
        clogging[Cloud Logging]
      end

      cloud_build -- logs --> log

      cloud_build -- interactive --> other[Google Platform services]
    end
  end

  code_storage <-- interactive --> cloud_build

Based on the flow above, the components included as follows:

Note: CB denotes Cloud Build throughout this document.

Detail Components¶

[CB-01] Cloud Build API¶

The Cloud Build API serves as the core service endpoint required to provision and operate Cloud Build resources within a given project. All Cloud Build functionality, including triggers, worker pools, and build executions, is scoped to the specified project ($PROJECT_ID) and region ($PROJECT_REGION).

Before using Cloud Build, the Cloud Build API must be enabled for the target project. If the project identifier is unknown, refer to the Troubleshooting section for guidance on identifying the correct project configuration.

Cloud Build endpoint: cloudbuild.googleapis.com

[CB-02] Worker private pool¶

Cloud Build supports two execution models: the default pool and private worker pools. By default, builds run on a shared, Google-managed pool with access to the public internet. Each build executes on an isolated worker and is logically separated from other workloads. While the default pool supports basic customization (such as machine size and disk allocation), it has limitations around network isolation and private resource access.

For workloads requiring greater control, private worker pools are recommended. Private pools provide deeper customization of the build environment, including network placement, machine sizing, and access to private infrastructure.

Private worker pools are hosted in a Google-owned service producer network and are assigned internal IP addresses. To enable builds to access resources within a customer VPC (such as private services, databases, or internal APIs), a VPC Network Peering connection is established between the customer VPC and the service producer network. This allows builds to communicate with private resources without exposing traffic to the public internet.

When a build is triggered and configured to use a private pool, Cloud Build routes the execution request to the designated private worker pool. The build then runs on dedicated workers within the peered service producer network, while logs and metadata are still collected and managed by Cloud Build service.

The following diagram shows how builds are routed to the private pool.

Source: Google Cloud

At the current stage, our private worker pool is configured with the following attributes:

This configuration is provisioned and managed through the infrastructure layer. For additional details, refer to the google-private-pool-overview documentation.

Reference:

• Private pools overview

[CB-03] Service account authorization¶

Cloud Build uses service accounts to authorize access to resources and services. These identities are provisioned automatically and operate within defined IAM boundaries.

If your Cloud Storage bucket and Cloud Build are in the same Google Cloud project and you're using the Cloud Build service account, your Cloud Build service account has the necessary IAM permissions by default. You do not have to grant any additional permissions.

In this scenario, Cloud Build uses the following service accounts:

CloudBuild Service Agent:

• IAM: service-$PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com

Default Cloud Build Service Account:

• IAM: Cloudbuild Service account $PROJECT_NUMBER@cloudbuild.gserviceaccount.com.

For more detail, go with [CloudBuild Log]¹ and [CloudBuild Service Account]²

Reference:

• Configure access for cloud build service account

[CB-04] Log storage¶

This storage bucket to store artifacts from CloudBuild like logs. Following: [CloudBuild Log]¹

For the life cycle of object, follow the table:

Retired condition:

To check the retention of object in a targeted bucket with name of STORAGE_BUCKET_NAME

export STORAGE_BUCKET_NAME=internal-cloud-build
gcloud storage buckets describe gs://$STORAGE_BUCKET_NAME --format="default(per_object_retention)"

Reference:

• Terraform module for Storage Bucket

• Google - Storage Life Cycle

[CB-05] Cloud Logging¶

Cloud Build integrates natively with Cloud Logging to collect, store, and stream build logs and execution metadata. No additional infrastructure is required to enable logging, as log ingestion is handled automatically by the Cloud Build service.

To allow log delivery, the Cloud Build service account must have permission to write log entries to Cloud Logging. This is typically satisfied by granting the service account the roles/logging.logWriter role at the project level. With this permission in place, Cloud Build can emit build logs, status updates, and metadata during execution.

Once configured, all build logs are centrally available in Cloud Logging, where they can be queried, filtered, retained, and exported to downstream systems for monitoring, auditing, or troubleshooting purposes.

[CB-06] Source repository integration¶

The GitHub connection defines the integration between GitHub and Cloud Build for sourcing build input from private repositories. This connection allows Cloud Build to synchronize repository metadata and securely retrieve source code during build execution, enabling both trigger-based and manual builds.

To establish this integration, a designated runner account must be granted access to the target GitHub organization or repositories. The credentials for this account are stored in Google Cloud Secret Manager and can be retrieved from trthuyetbao@gmail.com, ensuring that sensitive access information is not embedded directly in configuration files.

To establish the repository mapping between GitHub and Cloud Build, perform the following steps:

(1) Add the runner account to the repository

In the GitHub organization or administrative repository, add the designated runner account. Retrieve the account credentials from Secret Manager using trthuyetbao@gmail.com.

(2) Grant Administrator permissions

Assign Administrator privileges to the runner account on the relevant repositories. These permissions are required for repository discovery, webhook configuration, and ongoing synchronization with Cloud Build.

(3) Create the Cloud Build GitHub connection

In the Google Cloud Console, navigate to Cloud Build → Repositories and create a new GitHub connection. Authorize Cloud Build to access the selected repositories and complete the repository mapping.

(4) Verify repository availability

After the connection is established, confirm that the mapped repositories are visible in Cloud Build and available for use in trigger-based and manual CI/CD workflows.

Normal Operational Flow¶

The workflow follows the components and sequence below.

(1) A developer interacts with source code in a GitHub repository.

Examples include:

• Creating pull requests

• Pushing commits

• Merging branches

These actions generate webhook events that are sent to Cloud Build. See: GitHub events and payloads

(2) Cloud Build receives the webhook payload and evaluates the event against the configured trigger rules.

(3) When trigger conditions are met, Cloud Build initiates a build execution and assigns it to a private worker pool.

(4) The private worker pool queues the build request and executes the defined build steps in an isolated runtime environment.

(5) During execution:

• Build logs are written to the configured logging and storage services

• Build status and execution metadata are reported back to GitHub

(6) Termination: The build completes with a success or failure status.

For a list of build status values, see Appendix 2: Build status enumeration.

Pricing¶

The CloudBuild is a pay as you go service, with following properties.

Private worker pools use a different pricing model from the default pool. Pricing is based on the selected machine type and build duration. The following table shows example pricing for the Singapore region, along with the estimated cost for 1,000 build minutes:

Implementation¶

# Module: Cloud Build
# ===================
#
# @description
# ------------
# Cloud Build is a service that executes your builds on Google Cloud Platform infrastructure.

# ---------------------------------------------------------------------
# API -----------------------------------------------------------------
# ---------------------------------------------------------------------

resource "google_project_service" "discovery_mesh" {
  for_each = toset([
    "servicenetworking.googleapis.com",
    "iam.googleapis.com",
    "secretmanager.googleapis.com",
    "cloudbuild.googleapis.com",
    "artifactregistry.googleapis.com",
    "container.googleapis.com",
    "monitoring.googleapis.com",
    "logging.googleapis.com",
  ])
  project = var.project_id
  service = each.key

  timeouts {
    create = "30m"
    update = "40m"
  }

  disable_dependent_services = true

  # Do not disable the service on destroy. On destroy, we are going to
  # destroy the project, but we need the APIs available to destroy the
  # underlying resources.
  disable_on_destroy = false
}

# ---------------------------------------------------------------------
# Storage - Internal Services (Cloud Services) ------------------------
# ---------------------------------------------------------------------

resource "google_storage_bucket" "internal_cloud_build" {
  name                        = "internal-cloud-build"
  project                     = var.project_id
  location                    = upper("${var.project_region}")
  storage_class               = "STANDARD"
  uniform_bucket_level_access = true
  force_destroy               = true

  versioning {
    enabled = false
  }

  lifecycle_rule {
    condition {
      age                   = 30
      with_state            = "ANY"
      matches_storage_class = ["STANDARD"]
    }
    action {
      type          = "SetStorageClass"
      storage_class = "NEARLINE"
    }
  }

  lifecycle_rule {
    condition {
      age                   = 60
      with_state            = "ANY"
      matches_storage_class = ["NEARLINE"]
    }
    action {
      type          = "SetStorageClass"
      storage_class = "COLDLINE"
    }
  }

  lifecycle_rule {
    condition {
      age                   = 60
      with_state            = "ANY"
      matches_storage_class = ["COLDLINE"]
    }
    action {
      type          = "SetStorageClass"
      storage_class = "ARCHIVE"
    }
  }

  lifecycle_rule {
    condition {
      no_age                = true
      with_state            = "ANY"
      num_newer_versions = 3
    }
    action {
      type          = "Delete"
    }
  }

  labels = {
    description = "internal-systems-storage-like-logs-artifacts"
  }
}

# ---------------------------------------------------------------------
# Service Agent: CloudBuild -------------------------------------------
# ---------------------------------------------------------------------

resource "google_project_iam_member" "default_service_account_cloudbuild" {
  for_each = toset([
    "roles/cloudbuild.serviceAgent",
  ])
  project = var.project_id
  role    = each.value
  member  = local.service_agent.cloudbuild.identity
}

# ---------------------------------------------------------------------
# Stack: Worker Pool --------------------------------------------------
# ---------------------------------------------------------------------

resource "google_cloudbuild_worker_pool" "private_pool_build_workers" {
  name     = "private-pool-build-workers"
  location = var.project_region
  worker_config {
    disk_size_gb   = 100
    machine_type   = "e2-standard-2"
    no_external_ip = false
  }

  lifecycle {
    prevent_destroy = true
  }

  depends_on = [
    google_project_service.discovery_mesh
  ]
}

# ---------------------------------------------------------------------
# Stack: Connection ---------------------------------------------------
# ---------------------------------------------------------------------

resource "google_cloudbuildv2_connection" "github_connection_thuyetbao" {
  name     = "github-connection-thuyetbao"
  location = var.project_region

  github_config {
    app_installation_id = 77777777
    authorizer_credential {
      oauth_token_secret_version = data.google_secret_manager_secret_version.github_token_secret_version.id
    }
  }

  lifecycle {
    prevent_destroy = true
  }
}

# ---------------------------------------------------------------------
# Stack: Repository ---------------------------------------------------
# ---------------------------------------------------------------------

resource "google_cloudbuildv2_repository" "repository_space" {
  name              = "repository-space"
  project           = var.project_id
  location          = var.project_region
  parent_connection = google_cloudbuildv2_connection.github_connection_thuyetbao.name
  remote_uri        = "https://github.com/thuyetbao/space.git"
  lifecycle {
    prevent_destroy = true
  }
}

Edge Cases and Limitations¶

• Trigger misconfiguration may prevent builds from executing.

• Insufficient IAM permissions can block logging or storage writes.

• Private Pool capacity constraints may delay builds.

• Webhook delivery failures can prevent event ingestion.

• Cross-project resource access requires explicit permission grants.

Troubleshooting¶

[1] Get project number by gcloud command ¶

Use following command

gcloud projects list --filter="$(gcloud config get-value project)" --format="value(PROJECT_NUMBER)";
# 999999999999

[2] Send logs to both Cloud Storage (with streaming) and Cloud Logging¶

For the configuration file:

(a) Set logStreamingOption into STREAM_ON

(b) Dont set the logging key

---
options:
  # logging: null # Use this option to specify if you want to store logs in Cloud Logging or Cloud Storage.
  logStreamingOption: STREAM_ON

Reference:

• GCP - Build config file schema

• GCP - Build store and manage logs

• GCP - Build service account

Reference¶

• Google Cloud Build Documentation https://cloud.google.com/build/docs

• GitHub Webhooks and Events https://docs.github.com/en/webhooks/webhook-events-and-payloads

• Cloud Build Service Accounts https://cloud.google.com/build/docs/securing-builds/set-service-account-permissions

• Provision CloudBuild from Terraform

• Provision Worker Pool from Terraform

• Connect GitHub from CloudBuild 2^nd generation

• Pricing Table. Ref: https://cloud.google.com/build/pricing

Appendix¶

Appendix 1: Record of Changes¶

Table: Record of changes

Appendix 2: Describe "Multi-platform" Means in This Context¶