Multi-Environment Terraform Directories vs Workspaces
Parent: MongoDB Atlas Infrastructure as Code · Published reference · snapshot 2026-10-24 · skill mongodb-cohort-4308c7661d27
↓ Facts as markdownall context files
Source-anchored research for Multi-Environment Terraform Directories vs Workspaces. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
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]
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]
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]
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]
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]
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]
- 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]
- 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]
- 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]
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]
- 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]
- 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]
- 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]
- 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]
- 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]
Children
- No children recorded.