Terraform Google Project Factory: Automated Opinionated GCP Project Provisioning

The Terraform Google Project Factory is a system for automated provisioning and management of opinionated Google Cloud Platform projects. It implements infrastructure-as-code best practices to standardize project creation while supporting enterprise requirements such as Shared VPC integration, budget controls, quota management, and security configurations.

The module is designed 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't upgraded and need a Terraform 0.12.x-compatible version of this module, the last released version intended for Terraform 0.12.x is 9.2.0. See the docs for detailed instructions on upgrading between major releases of the module.

This module allows you to create opinionated Google Cloud Platform projects. It creates projects and configures aspects like Shared VPC connectivity, IAM access, Service Accounts, and API enablement to follow best practices. To include G Suite integration for creating groups and adding Service Accounts into groups, use the gsuite_enabled module.

Architecture and Component Model

The project factory follows a layered architecture with clear separation between orchestration, core engine functionality, and specialized services.

The system is organized around several key components that handle different aspects of project provisioning.

Component	File Location	Primary Responsibility
Main Module	main.tf28-76	Orchestrates all sub-modules and manages variable passing
Core Project Factory	modules/coreprojectfactory/main.tf73-89	Handles fundamental project creation via google_project resource
Project Services	modules/coreprojectfactory/main.tf105-113	Manages API activation through project_services module
Shared VPC Access	main.tf81-95	Configures network permissions and service account access
Budget Management	main.tf100-116	Creates and configures billing budgets
Quota Manager	main.tf121-126	Handles service quota overrides

The project factory follows a structured data flow from user configuration through core engine processing to GCP resource creation. The project factory implements several enterprise-grade features for standardized project provisioning:

random_id and random_string resources
delete, deprivilege, disable, or keep behaviors
compute.networkUser role at project level

Core Provisioning Workflow

The Project Factory module will take the following actions:

Create a new GCP project using the project_name

The module creates an opinionated Google Cloud project by using Shared VPC, IAM, and Google Cloud APIs. Core functionality includes opinionated project creation, Shared VPC connectivity, IAM access configuration, Service Account provisioning, and API enablement.

Simple usage is as follows:

hcl module "project-factory" { source = "terraform-google-modules/project-factory/google" version = "~> 18.3" name = "pf-test-1" random_project_id = true org_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", ] }

Configuration parameters control project identity, billing linkage, network sharing, and usage reporting. The random_project_id flag allows automatic generation of a unique project ID when a deterministic ID is not provided. The org_id ties the new project to an organization resource for hierarchical policy enforcement.

Shared VPC integration is expressed through svpc_host_project_id and a list of shared_vpc_subnets. Each subnet reference uses the full project/region/subnetwork resource identifier. This enables the new project to consume network resources from a host project without creating duplicate VPCs.

Billing linkage is established via billing_account. The usage_bucket_name and usage_bucket_prefix configure a Cloud Storage bucket for audit and usage report exports, supporting cost attribution and compliance workflows.

Enterprise Features and Opinionated Defaults

The project factory implements infrastructure-as-code best practices to standardize project creation while supporting enterprise requirements such as Shared VPC integration, budget controls, quota management, and security configurations.

Budget Management is handled as a dedicated component within the main module. It creates and configures billing budgets with configurable thresholds, notification channels, and spend alerts. This ensures cost governance is applied at project birth rather than as an afterthought.

Quota Manager handles service quota overrides. Enterprise deployments often require pre-provisioning of higher API or resource quotas. The module integrates with the Service Usage Consumer and Quota Admin APIs to request quota increases during project creation.

Shared VPC Access configures network permissions and service account access. The module applies the compute.networkUser role at project level and grants specific IAM bindings to service accounts used by the Shared VPC host. Support for Cloud Run Direct VPC egress was added to enable secure private connectivity for serverless workloads.

Service Accounts are provisioned with opinionated defaults. The coreprojectfactor enables setting a description for the default service account. This improves discoverability and auditability in large organizations where multiple service accounts are created automatically.

API enablement is centralized through the Project Services sub-module. It manages API activation through the project_services module, allowing declarative specification of required Google Cloud APIs for a given workload profile.

Release Management and Versioning

Version 18.1.0 was released on 2025-08-29. The release notes document the following changes:

Add per module requirements to project-factory
coreprojectfactor: enable setting a description for the default service account
deps: Update Terraform Google Provider to v7
sharedvpcaccess: Add support for Cloud Run Direct VPC egress

The Terraform Google Provider update to v7 is a major dependency shift that aligns the module with current Google Cloud API capabilities and provider resource models. Users upgrading from earlier versions should validate provider compatibility and review breaking changes in the provider changelog.

The per module requirements addition improves dependency isolation and allows consumers to pin sub-module versions independently. The default service account description feature enhances documentation and operational hygiene.

Development Guide and Toolchain

This page provides an overview of developer workflows, tools, and processes for working with the Terraform Google Project Factory codebase. It covers the essential setup procedures, development workflows, testing processes, and troubleshooting approaches needed to contribute effectively to the project.

For detailed information about the testing infrastructure and validation systems, see Testing Framework. For specific CI/CD pipeline configurations, see CI/CD Workflows. For comprehensive helper script documentation, see Setup and Helper Scripts.

The Project Factory development environment is built around a standardized Docker-based toolchain that ensures consistency across different development machines. The workflow integrates multiple validation layers including linting, unit testing, integration testing, and compliance validation.

The development environment relies on several key tools and scripts that automate common tasks and ensure code quality standards. helpers/setup-sa.sh is used to create the Seed Service Account with appropriate permissions.

The development cycle follows a structured approach that emphasizes validation at each step. The project uses a multi-layered testing approach that validates both the Terraform code quality and the actual infrastructure deployment.

Common development tasks include running terraform fmt and terraform validate, executing unit tests against mocked Google APIs, and running integration tests against a live test organization. Linting enforces consistent formatting and naming conventions across modules.

Ecosystem Context

The Terraform Google Modules organization maintains multiple opinionated modules for Google Cloud. Pinned repositories include:

terraform-google-kubernetes-engine Public
Configures opinionated GKE clusters
terraform-google-service-accounts Public
Creates one or more service accounts and grants them basic roles
terraform-google-project-factory Public
Creates an opinionated Google Cloud project by using Shared VPC, IAM, and Google Cloud APIs
terraform-google-github-actions-runners Public
Creates self-hosted GitHub Actions Runners on Google Cloud

The project-factory module sits at the foundation of the organization’s module stack. It is typically consumed first to establish a project identity, billing, and network context before other modules such as kubernetes-engine or service-accounts are applied.

Configuration Patterns and Best Practices

When integrating the module, separate configuration for creation and for destruction. The module supports delete, deprivilege, disable, or keep behaviors for project lifecycle management. Using keep is common in production to prevent accidental deletion of projects with financial or compliance data.

Enable Shared VPC only when the organization mandates centralized network control. The shared_vpc_subnets list should be maintained in version control alongside the module invocation to provide auditability of network dependencies.

Use random_project_id for non-production environments to avoid naming collisions. For production, supply a deterministic project ID that conforms to GCP naming rules and organizational naming standards.

Always pin the module version with ~> to receive compatible patch updates while avoiding unexpected major changes. Review the release notes for each minor version, particularly when Terraform Google Provider major versions are updated.

Conclusion

The Terraform Google Project Factory provides a comprehensive, opinionated approach to GCP project provisioning that embeds enterprise governance into infrastructure code. By centralizing project creation, Shared VPC connectivity, IAM, service accounts, API enablement, budget controls, and quota management, the module reduces toil and enforces consistency across large fleets of projects.

Its layered architecture with distinct components for orchestration, core project creation, service activation, network access, budgeting, and quota management enables both simplicity for basic use cases and deep customization for enterprise requirements. The Docker-based development toolchain, multi-layered testing, and active release cadence support reliable contributions and safe upgrades.

For organizations standardizing on Terraform for Google Cloud, the project factory remains the recommended entry point for building compliant, observable, and cost-controlled projects at scale.