Terraform Project Structure for GCP: Environments, Modules, and Best Practices

What is Terraform project structure?

Terraform project structure is how you organise the files and folders that define your infrastructure. At its simplest, you could put every resource in a single file in a single folder. That works for a learning exercise. It does not work for a real project.

The problem with keeping everything in one place is that Terraform manages all your resources as a single unit. A plan for one small change forces Terraform to process your entire infrastructure. A mistake like running the wrong command or destroying the wrong resource can affect everything at once. You cannot safely give a junior engineer access to dev without also giving them access to prod.

The solution is to split infrastructure into separate directories by environment. Each directory has its own Terraform state. What happens in dev stays in dev. Shared patterns like a Cloud Run service definition, a VPC setup, or a service account configuration live in modules you call from each environment. This is the folder structure most teams converge on when they outgrow a single file.

If you are new to Terraform itself, start with Terraform for Google Cloud before reading this page. If you want the broader picture of why teams adopt IaC at all, see Infrastructure as Code on GCP.

Why Terraform project structure matters

The way you structure a Terraform project determines what kinds of mistakes are possible.

With separate directories per environment, a destroy in dev destroys dev resources only. Plans are faster and scoped to one environment. Pull requests clearly show which environment will be affected. IAM access can be scoped to specific environment directories in CI/CD. You can apply to dev, confirm the result, and only then apply to staging and production.

Structure also matters for teams using secure CI/CD pipelines. A well-structured project maps naturally to a safe pipeline: one job runs terraform plan on pull request, another runs terraform apply only after merge, and each environment is deployed independently.

Standard Terraform folder layout for GCP

Here is the layout most GCP teams end up using. Every directory under environments/ is a root module, meaning a directory you run terraform apply from. Shared patterns live in modules/ and are called from each environment root.

terraform/
  environments/
    dev/
      main.tf          # Module calls and resources for dev
      variables.tf     # Variable declarations
      outputs.tf       # Exported values (useful for CI/CD or other modules)
      versions.tf      # Provider and Terraform version constraints
      terraform.tfvars # Non-sensitive variable values for dev
    staging/
      main.tf
      variables.tf
      outputs.tf
      versions.tf
      terraform.tfvars
    prod/
      main.tf
      variables.tf
      outputs.tf
      versions.tf
      terraform.tfvars

  modules/
    cloud-run-service/
      main.tf          # The Cloud Run resource definition
      variables.tf     # Inputs the module accepts
      outputs.tf       # Values the module exposes
    vpc-network/
      main.tf
      variables.tf
      outputs.tf
    service-account/
      main.tf
      variables.tf
      outputs.tf

Each environment directory is completely self-contained. It has its own state file, its own variable values, and its own provider configuration. The environments share nothing except the module code, which is versioned in the same repository.

How it works in practice

Here is the flow a team typically follows when making an infrastructure change:

1. Make the change in a branch. Edit a module or an environment’s main.tf. If the change is to a module, all environments that call that module will pick up the change on their next apply.
2. Run terraform plan against dev. Navigate into environments/dev/ and run terraform plan. Check the output carefully. The plan only affects dev state and dev GCP resources.
3. Open a pull request. CI/CD runs terraform plan automatically and posts the output as a comment. Reviewers can see exactly what will change before approving.
4. Merge and apply to dev first. After the PR merges, the pipeline applies to dev. If GitHub Actions or Cloud Build is driving this, the apply job runs from environments/dev/.
5. Promote to staging, then prod. Run the same plan and apply sequence in environments/staging/, confirm the result, then repeat for environments/prod/. Each environment is a separate apply with its own state.

Each environment points to its own GCP project. For most teams, this means three separate GCP projects: my-app-dev, my-app-staging, and my-app-prod. Keeping environments in separate GCP projects gives you hard IAM boundaries, separate billing, and separate audit logs. See Dev vs Staging vs Production for more on how environment separation maps to GCP project isolation.

Root modules vs reusable modules

A root module is the directory you run terraform apply from. It is the entry point. Each environment directory is a root module.

A reusable module is a directory of Terraform files you call from a root module using a module block. It encapsulates a repeatable pattern (a Cloud Run service, a VPC, a set of IAM bindings) and accepts inputs via variables.

# environments/prod/main.tf
module "api_service" {
  source = "../../modules/cloud-run-service"

  project_id    = "my-app-prod"
  region        = "europe-west2"
  service_name  = "api-service"
  image         = "europe-west2-docker.pkg.dev/my-app-prod/api/api:v1.2.0"
  min_instances = 2
  max_instances = 20
}

# environments/dev/main.tf
module "api_service" {
  source = "../../modules/cloud-run-service"

  project_id    = "my-app-dev"
  region        = "europe-west2"
  service_name  = "api-service"
  image         = "europe-west2-docker.pkg.dev/my-app-dev/api/api:latest"
  min_instances = 0
  max_instances = 5
}

The module’s variables.tf declares what inputs it accepts. The root module provides the values. When you fix a misconfiguration in the module (adding a missing Cloud Run environment variable, correcting a concurrency setting), all environments pick up the fix after their next apply.

Common GCP patterns that work well as modules: Cloud Run service definitions, VPC networks with subnets and firewall rules, GCS buckets with lifecycle policies, and service accounts with IAM bindings. For IAM specifically, see Managing IAM with Terraform.

Variables, tfvars files, and secrets

Variables are how environment differences flow into modules. Declare them in variables.tf:

# variables.tf
variable "project_id" {
  type        = string
  description = "GCP project ID for this environment"
}

variable "min_instances" {
  type        = number
  description = "Minimum Cloud Run instances"
  default     = 0
}

Supply non-sensitive values in terraform.tfvars:

# environments/prod/terraform.tfvars
project_id    = "my-app-prod"
region        = "europe-west2"
min_instances = 2

This is the right approach for values like project IDs, region names, instance counts, and service names. These are configuration, not secrets.

When this structure is worth adopting

The environment-per-directory structure is worth the setup cost when:

• You have or expect to have multiple environments (dev, staging, and prod at minimum)
• More than one person will apply Terraform changes
• You want to enforce a change process: apply to dev before applying to prod
• You need to give different people different levels of access to different environments
• You have shared infrastructure patterns across environments (a VPC layout, a Cloud Run template, a set of IAM roles)

Simpler structures are still fine for:

• A solo learning project with a single environment
• A short-lived prototype you will tear down in days
• A one-off resource that does not map to any ongoing service

Terraform workspaces vs separate directories

This comes up often enough to deserve a clear explanation.

Terraform workspaces let you maintain multiple state files from a single configuration directory. You run terraform workspace new staging to create a staging state, and terraform workspace select staging to switch into it before running plan or apply.

The limitation: a single configuration must handle all environment differences through conditional expressions.

# This logic accumulates fast and becomes hard to review
min_instances = terraform.workspace == "prod" ? 2 : 0
machine_type  = terraform.workspace == "prod" ? "n2-standard-4" : "e2-micro"
deletion_protection = terraform.workspace == "prod" ? true : false

Comparison: workspaces vs separate directories

For dev, staging, and prod: use separate directories. For short-lived feature environments where the configuration is genuinely identical, workspaces are a reasonable choice.

Module sources and version pinning

For local modules within your repo, use a relative path as the source:

module "api_service" {
  source = "../../modules/cloud-run-service"
  # ...
}

For modules from the Terraform Registry (including Google’s official modules), always pin to a version:

module "gcs_bucket" {
  source  = "terraform-google-modules/cloud-storage/google"
  version = "~> 6.0"

  project_id = var.project_id
  names      = ["my-app-prod-assets"]
  location   = "EU"
}

Without a version constraint, terraform init can download a breaking major version on any future run. The ~> constraint allows patch and minor updates within the major version but blocks major upgrades. The same principle applies to provider versions in versions.tf. Always pin the Google provider to a major version like ~> 5.0.

Recommended approach for most GCP teams

Start with this layout on day one if you know you will have multiple environments:

• Three separate GCP projects: dev, staging, prod
• Three matching Terraform environment directories, each with its own state file stored in GCS. See Terraform State Management for how to configure remote state.
• A modules/ directory for shared patterns. Add modules as repetition appears, not before.
• Non-sensitive variable values in terraform.tfvars, secrets via TF_VAR_ or Secret Manager
• A CI/CD pipeline that plans on pull request and applies after merge, with environment promotion controlled by pipeline stages. GitHub Actions for GCP shows one way to wire this up.
• Provider and module versions pinned in versions.tf

This structure is not the only correct answer. Some teams add a shared/ root module for organisation-level resources. Some teams split modules into a separate repository once the codebase grows large. The key decisions (separate state per environment, shared modules for reuse, secrets out of version control) apply regardless of the exact layout you choose.

For teams adopting Policy as Code, this structure maps cleanly to automated policy enforcement: policies can be applied per-environment directory and validated in CI/CD before any apply runs.