terraform-google-modules/terraform-example-foundation

Purpose and execution model

This is a fork-and-customize Terraform blueprint for building a secure Google Cloud enterprise foundation. It is not an application: independent Terraform root projects must be applied in dependency order, first manually for bootstrap and then through CI/CD. The primary entry points are the numbered stage roots, especially 0-bootstrap/main.tf, 1-org/envs/shared/, and per-environment main.tf roots.

0. Bootstrap: state, identities, and deployment platform

0-bootstrap/ establishes the prerequisite deployment boundary in an existing GCP organization: seed/state and CI/CD projects, Terraform service accounts, IAM, and the selected execution integration (Cloud Build by default; GitHub, GitLab, local, and Terraform Cloud examples exist).

• 0-bootstrap/main.tf

• 0-bootstrap/build_cb.tf

• 0-bootstrap/sa.tf

It produces the credentials, remote state location, and pipeline resources consumed by later stages.

1. Organization baseline

The shared organization root creates top-level folders, foundational projects, organization IAM/policies, service controls, logging, SCC notification, and network-project scaffolding. It is the boundary between organization governance and environment-specific resources.

• 1-org/envs/shared/projects.tf

• 1-org/envs/shared/org_policy.tf

• 1-org/envs/shared/log_sinks.tf

Reusable implementations cover centralized logging, CAI monitoring, network setup, and service controls in 1-org/modules/centralized-logging/main.tf, 1-org/modules/cai-monitoring/main.tf, and 1-org/modules/service_control/main.tf.

2. Environment baselines

Development, nonproduction, and production are separate Terraform states and roots. Each creates its environment folder plus shared KMS and Secret Manager resources, consuming prior-stage organization outputs through remote-state configuration.

• 2-environments/envs/development/main.tf

• 2-environments/envs/nonproduction/main.tf

• 2-environments/modules/env_baseline/kms.tf

3. Network architecture alternatives

Choose one mutually alternative stage-3 topology: conventional Shared VPC (3-networks-svpc/) or hub-and-spoke (3-networks-hub-and-spoke/). Each has shared plus per-environment roots, remote-state inputs, and outputs for downstream service projects.

Shared VPC modules establish VPCs, DNS, firewall, NAT, Private Service Connect, and private service access:

• 3-networks-svpc/modules/shared_vpc/main.tf

• 3-networks-svpc/modules/shared_vpc/firewall.tf

• 3-networks-hub-and-spoke/modules/shared_vpc/private_service_connect.tf

Hub-and-spoke additionally models hubs, transitivity, HA VPN, and Dedicated/Partner Interconnect:

• 3-networks-hub-and-spoke/envs/shared/net-hubs.tf

• 3-networks-hub-and-spoke/modules/transitivity/main.tf

• 3-networks-hub-and-spoke/modules/vpn-ha/main.tf

4. Business-unit service projects and pipeline delegation

Stage 4 creates business-unit folders and service projects per environment, attaching eligible projects to the selected Shared VPC. It also creates infrastructure-pipeline projects, separating platform-foundation deployment from application-infrastructure deployment.

• 4-projects/modules/base_env/business_unit_folder.tf

• 4-projects/modules/single_project/main.tf

• 4-projects/modules/infra_pipelines/main.tf

The example roots are under 4-projects/business_unit_1/{shared,development,nonproduction,production}/; these are intended to be replicated/customized for actual business units.

5. Application infrastructure workload layer

Stage 5 is the downstream consumer of the foundation: environment roots deploy application-facing infrastructure into the projects created in stage 4. The included example centers on a Compute Engine workload and supports Confidential Space resources.

• 5-app-infra/business_unit_1/development/main.tf

• 5-app-infra/modules/env_base/main.tf

• 5-app-infra/modules/confidential_space/main.tf

CI/CD, policy, and runtime boundaries

Terraform runs through Cloud Build, GitHub Actions, GitLab CI, or Terraform Cloud patterns; scripts wrap plan/apply and authentication. Cloud Build definitions encode plan/apply workflows, while protected environment branches constrain deployment scope.

• build/cloudbuild-tf-plan.yaml

• build/cloudbuild-tf-apply.yaml

• build/tf-wrapper.sh

Plans are policy-validated with gcloud terraform-tools against OPA/Rego policy-library templates and constraints:

• policy-library/lib/constraints.rego

• policy-library/policies/templates/gcp_iam_allowed_bindings.yaml

• policy-library/policies/constraints/iam_deny_public.yaml

A Go-based deployment helper orchestrates validation, vet, apply, and destroy stages and integrates with GCP, GitHub, and GitLab:

• helpers/foundation-deployer/main.go

• helpers/foundation-deployer/stages/executor.go

• helpers/foundation-deployer/gcp/gcp.go