# terraform-google-modules/terraform-example-foundation architecture

> Architecture diagram of the GitHub repository terraform-google-modules/terraform-example-foundation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/terraform-google-modules/terraform-example-foundation
- Repository: https://github.com/terraform-google-modules/terraform-example-foundation

## Overview

#### 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`

Main entry points: [`1-org/envs/shared/projects.tf`](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/1-org/envs/shared/projects.tf) (Stage 1 organization baseline), [`2-environments/envs/development/main.tf`](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/2-environments/envs/development/main.tf) (Stage 2 environment baselines), [`4-projects/modules/single_project/main.tf`](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/4-projects/modules/single_project/main.tf) (Stage 4 service projects), [`0-bootstrap/main.tf`](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/0-bootstrap/main.tf) (Stage 0 bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_foundation["Foundation stages"]
  node_bootstrap["Stage 0 bootstrap<br/>Terraform root<br/>[main.tf]"]
  node_cloudbuild_bootstrap["Cloud Build integration<br/>Bootstrap integration<br/>[build_cb.tf]"]
  node_terraform_identities["Terraform service accounts<br/>IAM identities<br/>[sa.tf]"]
  node_org_baseline["Stage 1 organization baseline<br/>Terraform root<br/>[projects.tf]"]
  node_org_policies["Organization policies<br/>Governance<br/>[org_policy.tf]"]
  node_central_logging["Centralized logging<br/>Reusable module<br/>[main.tf]"]
  node_service_controls["Service controls<br/>Reusable module<br/>[main.tf]"]
  node_environment_baselines["Stage 2 environment baselines<br/>Terraform roots<br/>[main.tf]"]
  node_env_kms_secrets["KMS and Secret Manager<br/>Environment module<br/>[kms.tf]"]
  node_service_projects["Stage 4 service projects<br/>Terraform module<br/>[main.tf]"]
  node_infra_pipelines["Infrastructure pipeline projects<br/>Terraform module<br/>[main.tf]"]
  node_app_infrastructure["Stage 5 application infrastructure<br/>Terraform root<br/>[main.tf]"]
  node_confidential_space["Confidential Space<br/>Workload module<br/>[main.tf]"]
end

subgraph group_network["Stage 3 network choices"]
  node_shared_vpc["Shared VPC topology<br/>Alternative network root<br/>[main.tf]"]
  node_svpc_services["VPC network services<br/>Network module<br/>[firewall.tf]"]
  node_hub_spoke["Hub-and-spoke topology<br/>Alternative network root<br/>[net-hubs.tf]"]
  node_network_transitivity["Transitivity and connectivity<br/>Network modules<br/>[main.tf]"]
end

subgraph group_delivery["Delivery and policy"]
  node_cloudbuild_workflows["Cloud Build plan/apply<br/>CI workflows"]
  node_policy_validation["OPA policy validation<br/>Policy-as-code<br/>[constraints.rego]"]
  node_deployer{{"Foundation deployer<br/>Go deployment helper<br/>[main.go]"}}
end

node_bootstrap -->|"provisions"| node_cloudbuild_bootstrap
node_bootstrap -->|"creates"| node_terraform_identities
node_bootstrap -->|"state and credentials"| node_org_baseline
node_terraform_identities -->|"authenticates"| node_cloudbuild_workflows
node_org_baseline -->|"applies"| node_org_policies
node_org_baseline -->|"configures"| node_central_logging
node_org_baseline -->|"configures"| node_service_controls
node_org_baseline -->|"remote-state inputs"| node_environment_baselines
node_environment_baselines -->|"creates"| node_env_kms_secrets
node_environment_baselines -.->|"select topology"| node_shared_vpc
node_environment_baselines -.->|"select topology"| node_hub_spoke
node_shared_vpc -->|"includes"| node_svpc_services
node_hub_spoke -->|"includes"| node_network_transitivity
node_shared_vpc -->|"VPC attachment outputs"| node_service_projects
node_hub_spoke -->|"network outputs"| node_service_projects
node_service_projects -->|"separates deployment"| node_infra_pipelines
node_service_projects -->|"target projects"| node_app_infrastructure
node_app_infrastructure -.->|"optionally deploys"| node_confidential_space
node_cloudbuild_workflows -->|"validates plans"| node_policy_validation
node_policy_validation -.->|"gates Terraform changes"| node_org_baseline
node_deployer -->|"orchestrates execution"| node_cloudbuild_workflows

click node_bootstrap "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/0-bootstrap/main.tf"
click node_cloudbuild_bootstrap "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/0-bootstrap/build_cb.tf"
click node_terraform_identities "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/0-bootstrap/sa.tf"
click node_org_baseline "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/1-org/envs/shared/projects.tf"
click node_org_policies "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/1-org/envs/shared/org_policy.tf"
click node_central_logging "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/1-org/modules/centralized-logging/main.tf"
click node_service_controls "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/1-org/modules/service_control/main.tf"
click node_environment_baselines "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/2-environments/envs/development/main.tf"
click node_env_kms_secrets "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/2-environments/modules/env_baseline/kms.tf"
click node_shared_vpc "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/3-networks-svpc/modules/shared_vpc/main.tf"
click node_svpc_services "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/3-networks-svpc/modules/shared_vpc/firewall.tf"
click node_hub_spoke "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/3-networks-hub-and-spoke/envs/shared/net-hubs.tf"
click node_network_transitivity "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/3-networks-hub-and-spoke/modules/transitivity/main.tf"
click node_service_projects "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/4-projects/modules/single_project/main.tf"
click node_infra_pipelines "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/4-projects/modules/infra_pipelines/main.tf"
click node_app_infrastructure "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/5-app-infra/business_unit_1/development/main.tf"
click node_confidential_space "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/5-app-infra/modules/confidential_space/main.tf"
click node_cloudbuild_workflows "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/build/cloudbuild-tf-plan.yaml"
click node_policy_validation "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/policy-library/lib/constraints.rego"
click node_deployer "https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/helpers/foundation-deployer/main.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootstrap,node_cloudbuild_bootstrap,node_terraform_identities,node_org_baseline,node_org_policies,node_central_logging,node_service_controls,node_environment_baselines,node_env_kms_secrets,node_service_projects,node_infra_pipelines,node_app_infrastructure,node_confidential_space toneBlue
class node_shared_vpc,node_svpc_services,node_hub_spoke,node_network_transitivity toneAmber
class node_cloudbuild_workflows,node_policy_validation,node_deployer toneMint
```

## Components

### Foundation stages

Terraform roots applied in dependency order.

- [Stage 0 bootstrap](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/0-bootstrap/main.tf): Terraform root · Creates state, identities, and deployment platform. · `0-bootstrap/main.tf`
- [Cloud Build integration](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/0-bootstrap/build_cb.tf): Bootstrap integration · Default CI/CD execution integration. · `0-bootstrap/build_cb.tf`
- [Terraform service accounts](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/0-bootstrap/sa.tf): IAM identities · Deployment identities for later stages. · `0-bootstrap/sa.tf`
- [Stage 1 organization baseline](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/1-org/envs/shared/projects.tf): Terraform root · Organization governance and foundational projects. · `1-org/envs/shared/projects.tf`
- [Organization policies](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/1-org/envs/shared/org_policy.tf): Governance · `1-org/envs/shared/org_policy.tf`
- [Centralized logging](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/1-org/modules/centralized-logging/main.tf): Reusable module · `1-org/modules/centralized-logging/main.tf`
- [Service controls](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/1-org/modules/service_control/main.tf): Reusable module · `1-org/modules/service_control/main.tf`
- [Stage 2 environment baselines](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/2-environments/envs/development/main.tf): Terraform roots · Separate development, nonproduction, and production states. · `2-environments/envs/development/main.tf`
- [KMS and Secret Manager](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/2-environments/modules/env_baseline/kms.tf): Environment module · `2-environments/modules/env_baseline/kms.tf`
- [Stage 4 service projects](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/4-projects/modules/single_project/main.tf): Terraform module · Business-unit folders and environment service projects. · `4-projects/modules/single_project/main.tf`
- [Infrastructure pipeline projects](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/4-projects/modules/infra_pipelines/main.tf): Terraform module · Delegated application-infrastructure deployment projects. · `4-projects/modules/infra_pipelines/main.tf`
- [Stage 5 application infrastructure](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/5-app-infra/business_unit_1/development/main.tf): Terraform root · Application-facing infrastructure in service projects. · `5-app-infra/business_unit_1/development/main.tf`
- [Confidential Space](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/5-app-infra/modules/confidential_space/main.tf): Workload module · `5-app-infra/modules/confidential_space/main.tf`

### Stage 3 network choices

Select one topology.

- [Shared VPC topology](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/3-networks-svpc/modules/shared_vpc/main.tf): Alternative network root · Conventional Shared VPC option. · `3-networks-svpc/modules/shared_vpc/main.tf`
- [VPC network services](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/3-networks-svpc/modules/shared_vpc/firewall.tf): Network module · Firewall, DNS, NAT, PSC, and private service access. · `3-networks-svpc/modules/shared_vpc/firewall.tf`
- [Hub-and-spoke topology](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/3-networks-hub-and-spoke/envs/shared/net-hubs.tf): Alternative network root · Hub-and-spoke network option. · `3-networks-hub-and-spoke/envs/shared/net-hubs.tf`
- [Transitivity and connectivity](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/3-networks-hub-and-spoke/modules/transitivity/main.tf): Network modules · Transitivity, HA VPN, and interconnect capabilities. · `3-networks-hub-and-spoke/modules/transitivity/main.tf`

### Delivery and policy

Execution, validation, and deployment controls.

- [Cloud Build plan/apply](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/build/cloudbuild-tf-plan.yaml): CI workflows · Plan and apply workflow definitions. · `build/cloudbuild-tf-plan.yaml`
- [OPA policy validation](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/policy-library/lib/constraints.rego): Policy-as-code · Validates Terraform plans against Rego constraints. · `policy-library/lib/constraints.rego`
- [Foundation deployer](https://github.com/terraform-google-modules/terraform-example-foundation/blob/main/helpers/foundation-deployer/main.go): Go deployment helper · Orchestrates validation, vet, apply, and destroy. · `helpers/foundation-deployer/main.go`

## Connections

- Stage 0 bootstrap → Cloud Build integration: provisions
- Stage 0 bootstrap → Terraform service accounts: creates
- Stage 0 bootstrap → Stage 1 organization baseline: state and credentials
- Terraform service accounts → Cloud Build plan/apply: authenticates
- Stage 1 organization baseline → Organization policies: applies
- Stage 1 organization baseline → Centralized logging: configures
- Stage 1 organization baseline → Service controls: configures
- Stage 1 organization baseline → Stage 2 environment baselines: remote-state inputs
- Stage 2 environment baselines → KMS and Secret Manager: creates
- Stage 2 environment baselines → Shared VPC topology: select topology
- Stage 2 environment baselines → Hub-and-spoke topology: select topology
- Shared VPC topology → VPC network services: includes
- Hub-and-spoke topology → Transitivity and connectivity: includes
- Shared VPC topology → Stage 4 service projects: VPC attachment outputs
- Hub-and-spoke topology → Stage 4 service projects: network outputs
- Stage 4 service projects → Infrastructure pipeline projects: separates deployment
- Stage 4 service projects → Stage 5 application infrastructure: target projects
- Stage 5 application infrastructure → Confidential Space: optionally deploys
- Cloud Build plan/apply → OPA policy validation: validates plans
- OPA policy validation → Stage 1 organization baseline: gates Terraform changes
- Foundation deployer → Cloud Build plan/apply: orchestrates execution