How terraform-google-modules/terraform-google-project-factory works
Project Type and Purpose
• This is an open-source Terraform module (“Google Cloud Project Factory”) that codifies best practices for provisioning Google Cloud Platform (GCP) projects.
• It exposes reusable submodules (e.g., app_engine, budget, shared_vpc_access) and helper scripts to automate project creation, API enablement, IAM roles, billing, Shared VPC attachments, service accounts, budgets, and optional G Suite integration.
File Structure Analysis
• Top-level directories:
• modules/ – each subdirectory is a self-contained Terraform submodule implementing one aspect of project configuration
• examples/ – full sample configurations consuming the module in different scenarios (App Engine, budgets, Shared VPC, etc.)
• helpers/ – shell, Python, and Terraform-wrapping scripts for precondition checks, service account setup, version migration, release automation
• test/ – fixture Terraform configs, Go and Ruby/Inspec integration tests, precondition test scripts
• docs/ – user documentation, FAQs, upgrade guides, troubleshooting
• build/, .github/workflows – CI/CD pipelines for linting, testing, and release automation
• main.tf, variables.tf, outputs.tf, versions.tf – the entry point Terraform configuration that ties submodules together
• Configuration files:
• .pre-commit-config.yaml, Makefile – local linting and build commands
• build/*.cloudbuild.yaml – Cloud Build definitions
• .github/workflows/*.yaml – GitHub Actions for CI and stale-branch pruning
README Insights
• Articulates the module’s purpose: create a new GCP project, configure network/IAM/APIs, optionally create buckets and budgets, integrate with Shared VPC and G Suite.
• Lists required APIs, Terraform versions, provider plugins, usage examples, inputs/outputs, dependencies, and helper-script usage.
a. Main Components
1. Core Terraform Module (main.tf + submodules)
2. Submodules (modules/app_engine, modules/budget, modules/shared_vpc_access, etc.)
3. Examples (examples/*) demonstrating module consumption
4. Helpers (scripts under helpers/)
5. CI/CD Pipelines (.github/workflows + build/)
6. Test Harness (test/fixtures, test/integration)
7. Documentation (docs/)
8. External Systems: Terraform CLI, Google Cloud APIs (Resource Manager, Billing, IAM, etc.), GitHub
b. Relationships & Interactions
• The Terraform CLI invokes main.tf, which calls into multiple submodules.
• Submodules communicate with Google Cloud APIs via the google and google-beta providers.
• Examples/ directories import the root module as a remote module and drive real-world configurations.
• Helpers (e.g., preconditions.py, setup-sa.sh) validate environment and bootstrap service accounts.
• The CI/CD pipelines trigger:
• Linting (terraform fmt, terraform validate, shellcheck, pre-commit)
• Unit tests (terraform-docs generation)
• Integration tests (Kitchen + InSpec, Go tests)
• Release automation (release-please, renovate)
• Test fixtures feed Terraform configs into the test harness; integration tests assert real or emulated behavior against GCP.
c. Architectural Patterns & Principles
• Modular design: each Terraform concern is isolated in its own submodule
• Infrastructure as Code: declarative definitions, versioned modules, automated testing
• Separation of concerns: provisioning logic (modules), examples, docs, scripts, and CI kept in dedicated directories
• CI pipeline as code: Cloud Build and GitHub Actions definitions versioned alongside code
• Extensibility: clients can override variables, extend via examples or custom modules
d. Key Technologies & Frameworks
• Terraform (core language)
• Terraform providers: google, google-beta, terraform-provider-gsuite
• CI/CD: GitHub Actions, Google Cloud Build
• Testing: InSpec (Ruby), Kitchen-Terraform, Go (test files), pre-commit hooks
• Scripting: Bash, Python (preconditions, migrations), Makefile
• Documentation: Markdown under docs/