terraform-example-foundation: A GCP Foundation Blueprint in Terraform

Why terraform-example-foundation Exists

terraform-example-foundation addresses a specific infrastructure problem: establishing a governed Google Cloud landing zone rather than creating isolated projects one at a time. Its README says the structure follows the Google Cloud Enterprise Foundations Blueprint, formerly called the Security Foundations Guide. The intended user is a large enterprise with a dedicated platform team that deploys and maintains the environment, divides responsibilities across teams, and manages infrastructure through version-controlled Infrastructure as Code.

That audience matters because the repository is not designed as a compact installation utility. It contains separate Terraform projects for the organization, environments, networking, projects, and application infrastructure. Each directory is applied separately and in sequence. This staged design lets a platform organization establish permissions and shared services before downstream teams create workloads, although it also means that adopting the blueprint requires coordination across multiple boundaries.

The README positions the code as a starting point with pragmatic defaults that customers are expected to customize. It explicitly says smaller organizations looking for a turnkey solution may prefer Google Cloud Setup. The repository is therefore most useful when its consumers already understand Google Cloud organization structure, IAM boundaries, CI/CD operations, and Terraform state management.

The Staged Bootstrap and Organization Sequence

Stage `0-bootstrap` is the manual entry point. It executes the CFT Bootstrap module against an existing Google Cloud organization and creates the initial projects, permissions, Terraform state storage, service accounts, and Cloud Build resources needed by later stages. According to the README, the resulting structure contains `prj-b-seed` and `prj-b-cicd` under `fldr-bootstrap`.

The split has an operational purpose. `prj-b-seed` holds the Terraform state bucket and custom service accounts that create or modify infrastructure. `prj-b-cicd` holds the deployment tooling, including Cloud Source Repository, Artifact Registry, and a Cloud Build pipeline. The README describes distinct service accounts for each stage so IAM permissions can follow the same separation as the projects.

Stage `1-org` builds the organizational layer. The README lists `fldr-common` for shared resources such as Security Command Center notifications, Cloud Key Management Service, organization-level secrets, logging, and billing export. It lists `fldr-network` for DNS Hub, Interconnect, network hub, and shared VPC projects associated with development, nonproduction, and production.

This is not a single root module that creates everything in one apply. The repository explicitly requires the directories to be layered in order. Cloud Build triggers can run `terraform plan` for non-environment branches and `terraform apply` after changes are merged into `development`, `nonproduction`, or `production` branches when the Cloud Build submodule is used.

Shared Logging, Billing, and Security Services

The organization stage establishes services that later stages can depend on. The `prj-c-logging` project is intended to receive organization-wide sinks, including admin activity audit logs from projects in the organization and from the billing account. The README states that collected logs go into a logging bucket with a linked BigQuery dataset for queries, investigation, and reporting. It also documents optional log export to Pub/Sub or Cloud Storage, including optional object versioning through `log_export_storage_versioning`.

The design has a documented retention boundary. The README says the captured audit log types in BigQuery are retained for 30 days. That makes the BigQuery dataset an investigation and reporting layer, not a complete long-term archive. Organizations that require longer retention need to examine the documented export paths and their own storage policies.

The `prj-c-scc` project hosts Security Command Center notification resources at the organization level. The repository also includes `prj-c-kms`, `prj-c-secrets`, and `prj-c-billing-export` in the common folder.

Billing data is the clearest incomplete edge. The README says a BigQuery dataset and permissions are created, but billing export must be configured manually because the project states that automation is not straightforward. Customers adopting the example must therefore distinguish infrastructure created by Terraform from a remaining Google Cloud setup task.

Network and Downstream Terraform Layers

After organization resources are in place, the repository provides two network-oriented paths. The top-level entries include `3-networks-hub-and-spoke/` and `3-networks-svpc/`. The organization README also describes network projects for DNS, Interconnect, a network hub, and shared VPC projects for development, nonproduction, and production. The exact configuration and dependencies belong to the individual stage directories, but the repository structure makes clear that networking is a separate deployment layer rather than an incidental resource inside the application project.

Later stages are `4-projects/` and `5-app-infra/`. Their directory names indicate the intended sequence from the organization foundation to projects and then application infrastructure. This separation is useful for teams that need different ownership boundaries or approval controls, but it also means the adopting organization must decide how commits, plans, applies, and approvals move between stages.

The README does not document a single command that deploys the entire foundation. That omission is consistent with the stated model. The first stage is manual, later stages use a preferred CI/CD tool, and each Terraform project is applied separately. The code is therefore closer to a reference architecture maintained in Git than a package consumed through Terraform registry style remote module references.

First Setup, Validation, and the Intended Forking Model

The project does not provide a conventional install command such as `terraform init` followed by a single deployment of the repository root. Its intended usage is to fork the repository, customize it, and maintain the resulting code in the customer's own version-control system. The README also says that the modules within this repository are not intended for use as remote references.

The repository includes a Makefile with a `docker_test_lint` target. It runs lint tests inside the `cft/developer-tools:1.23` container, mounts the current repository at `/workspace`, sets `ENABLE_PARALLEL=0`, and disables TFLint for that target. The target is intended for repository validation rather than production deployment. The README does not document the prerequisite Docker setup, so the exact local preparation remains a customer responsibility.

A first real use begins by creating a controlled copy of the repository, reviewing stage documentation, and adapting the organization, project, network, and environment inputs before applying anything. Stage `0-bootstrap` must be executed first. The bootstrap README contains the usage instructions for that stage.

The documented first functional result is not an application. It is the `prj-b-seed` and `prj-b-cicd` structure, followed by the organization and network layers. Teams should not treat the presence of the repository or a successful Terraform validation as permission to apply unchanged code to production.

Maintenance, Upgrade Boundaries, and Operational Trade-offs

The repository is not archived, and the last push was on 2026-10-14. Recent releases include `v7.0.0` on 2026-10-09, `v6.0.0` on 2026-09-09, and `v5.0.0` on 2026-07-24. That activity does not imply that customers can upgrade safely in place. The README expressly says in-place upgrades from a foundation deployed with an earlier version may not be feasible, even for minor changes.

The reason is specific. Repository maintainers cannot see what resources customers have deployed above the foundation or how they changed it. Their support commitment covers code validity against known-good versions, Terraform validation and lint checks, and integration tests for changes proposed to this repository. It does not promise compatibility with arbitrary customer overlays.

This makes upgrade cost an architectural concern rather than just a dependency update. A customer must compare the current customized code with a new release, identify stage ordering changes, recreate or migrate required resources, and validate downstream workloads. The repository's separate stages increase operational clarity, but they also increase the number of state boundaries and deployment approvals to manage.

The code is licensed under Apache-2.0. The license permits use and modification under its terms, but customers still need to review license notices, dependencies, and organizational policy separately. The repository is a reference implementation, not a guarantee that every default matches an enterprise's security, residency, retention, or support model.

When the Blueprint Is the Wrong Choice

The clearest wrong-tool case is a small organization seeking a turnkey Google Cloud setup. The README points those users toward Google Cloud Setup because this repository assumes engineering skills, a platform team, and the need for separation of duties across multiple teams. Its staged structure and custom service accounts are useful controls when many teams share an organization, but those controls also require ownership.

Another unsuitable case is an organization that wants to consume a stable Terraform module from a remote source. The README explicitly says the modules in this repository are not intended for remote references. The expected delivery model is fork, modify, and maintain the code yourself. A team unwilling to own a customized foundation copy will incur ongoing maintenance work even if its first deployment succeeds.

The repository is also not a substitute for every operational decision. Billing export requires manual configuration. Some documentation choices have limits, such as 30-day retention for audit log types in BigQuery. The example does not claim that its defaults satisfy every compliance regime, and it does not document rollback. The architecture is best treated as a starting point for review, not an out-of-the-box answer to governance requirements.

Editorial conclusion

Large enterprises with a platform team, version-controlled delivery process, and responsibility for separating duties should use this repository as a forkable blueprint. Smaller organizations seeking a turnkey setup should examine Google Cloud Setup instead. Before adoption, verify the staged ordering, Cloud Build assumptions, billing export work, customization effort, and the lack of guaranteed in-place upgrades from earlier foundation versions.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. terraform-google-modules/terraform-example-foundation on GitHub