# Multi-Environment Terraform Directories vs Workspaces > Source-anchored research for Multi-Environment Terraform Directories vs Workspaces. Run status: COMPLETED. Parent: [MongoDB Atlas Infrastructure as Code](https://llms-explorer.com/tree/mongodb-atlas-infrastructure-as-code/) · 7 facets · 15 facts · page: https://llms-explorer.com/tree/multi-environment-terraform-directories-vs-workspaces/ ## Definitions - For Atlas infrastructure, a defensible design is one environment root and state boundary per application/environment project, reusing modules. This is a synthesis: MongoDB recommends separate production projects per application/environment, while Google documents environment roots with shared modules. (medium confidence) — [source](https://www.mongodb.com/docs/atlas/architecture/current/hierarchy.md) ## Structure and components - Environment directories have maintenance costs. Terragrunt reduces repeated backend configuration through inherited settings and generated backend files, but adds another tool and configuration layer; its directory approach still requires more environment files than CLI workspaces. (low confidence) — [source](https://www.gruntwork.io/blog/how-to-manage-multiple-environments-with-terraform-using-terragrunt) ## How it works - MongoDB recommends separate Atlas projects for application/environment pairs, particularly in production, because project-level settings and permissions define important isolation boundaries. Applying that guidance to Terraform suggests mapping separately controlled deployments to the relevant Atlas projects; directory names or CLI workspace names alone do not enforce those Atlas boundaries. The mapping is an architectural inference, not a MongoDB-mandated repository layout. (medium confidence) — [source](https://www.mongodb.com/docs/atlas/architecture/current/hierarchy.md) ## How-to and procedures - Avoid treating workspace switches as system decomposition: components requiring separate configurations and backends should be separated explicitly. Google additionally warns that extensive terraform.workspace conditionals can make configuration harder to read. (high confidence) — [source](https://developer.hashicorp.com/terraform/cli/workspaces) ## Problems, failure modes and limitations - A Terraform 1.3.9 issue reported that setting TF_WORKSPACE without a cloud workspace mapping still produced "Missing workspace mapping strategy". Treat this as a historical integration report, not proof of a current defect or general CLI workspace failure. (low confidence) — [source](https://github.com/hashicorp/terraform/issues/33636) ## Comparisons and alternatives - HCP Terraform workspaces differ from CLI workspaces: they contain configuration, variables, and state and can have individual access controls. HashiCorp recommends one HCP workspace per infrastructure component per environment. (high confidence) — [source](https://developer.hashicorp.com/terraform/cli/workspaces) - HCP Terraform workspaces differ from CLI workspaces: each has its own configuration, variables, state and run history, and workspace permissions can delegate access to teams. (high confidence) — [source](https://developer.hashicorp.com/terraform/cli/workspaces) - A directory-per-environment pattern can keep root configurations small: declare each environment's backend and instantiate shared modules with environment-specific inputs instead of duplicating resource definitions. Google Cloud explicitly recommends this layout and using only the default CLI workspace in each environment directory. (high confidence) — [source](https://docs.cloud.google.com/docs/terraform/best-practices/root-modules?hl=en) - CLI workspaces remain useful for temporary feature-branch environments using the same configuration and backend. They reuse a working copy and plugin/module caches, reducing overhead compared with maintaining separate working directories. (low confidence) — [source](https://developer.hashicorp.com/terraform/cli/workspaces) ## Facts and statements - Terraform CLI workspaces keep separate state instances within one working directory while reusing its configuration and backend; selecting a workspace changes which state most Terraform commands operate on. (high confidence) — [source](https://developer.hashicorp.com/terraform/cli/workspaces) - For production environments requiring separate credentials and access controls, use separate root configurations and backend access boundaries. Separate folders alone do not enforce permission isolation. (high confidence) — [source](https://developer.hashicorp.com/terraform/cli/workspaces) - Environment directories can avoid wholesale configuration duplication: place reusable infrastructure in child modules and instantiate them from dev, qa, and prod roots, each declaring its own backend location and inputs. (high confidence) — [source](https://docs.cloud.google.com/docs/terraform/best-practices/root-modules?hl=en) - CLI workspaces remain useful for temporary parallel copies and tests of substantially identical infrastructure. Rejecting every use of workspaces overstates the isolation guidance. (high confidence) — [source](https://developer.hashicorp.com/terraform/cli/workspaces) - Terraform CLI workspaces separate state within one working directory and backend; they do not by themselves provide different backend credentials or access-control boundaries between environments. (high confidence) — [source](https://developer.hashicorp.com/terraform/cli/workspaces) - Directory-based deployments can pin different module releases in development, staging and production, allowing promotion after testing. Gruntwork demonstrates this with separate Terragrunt configurations using Git source refs; changing a shared local module path alone does not provide independent version pinning. (low confidence) — [source](https://www.gruntwork.io/blog/how-to-manage-multiple-environments-with-terraform-using-terragrunt)