Skip to main content

What are you looking for?

Explore our services and discover how we can help you achieve your goals

Client Workspace

Terraform state, modules and environments: a structure that survives team growth

A Terraform setup survives team growth when state is split by owner, change rate and credentials, each environment has its own root configuration and state, and code is shared only through versioned modules. Netbase structures infrastructure code this way so that one apply cannot touch everything and drift shows up in a plan, not an incident.

Book a solution review See the related solution

By Netbase Commerce and Platform Engineering Desk · Reviewed by David (CEO) · Updated · 10 min read

star

This guide is for CTOs, heads of engineering and platform leads whose infrastructure code has grown past one maintainer. It sits beside Netbase's cloud platform engineering service and covers one job inside it: choosing a repository layout, a state split and an environment model before the second and third team start applying changes.

In this guide

Why does a Terraform setup break when the team grows?

A Terraform setup breaks when more people change it than its structure was designed for. One state file, one set of credentials and copied environment folders work for one maintainer; with five, every apply risks someone else's resources, every lock blocks a colleague, and environments quietly stop matching.

Terraform records what it manages in state, and every apply compares the configuration with that record. The larger a single state is, the more resources one plan touches and the more people need write access to it. HashiCorp's tutorial on refactoring a monolithic configuration shows how a resource shared by production and development lets a change meant for development reach production.

Drift has two forms that need different fixes. Configuration drift means two environments are defined by code that has diverged. Infrastructure drift means the real resources no longer match state, usually after a change made in a cloud console. A good layout reduces the first; a scheduled plan detects the second.

Which repository layout fits your team?

Layout Blast radius and drift risk Access control Fits
Single root, one state Everything; drift grows because nobody runs a full plan One set of credentials for all One maintainer, one environment
Workspaces in one directory One environment; low drift, same code everywhere Weak: all workspaces share one backend Near-identical environments, one team, same credentials
Directory per environment, shared modules One environment; medium drift, root files can diverge Strong: separate backend and credentials per environment Most teams with staging and production
Layered stacks per owner and environment One layer of one environment; low drift with versioned modules Strong: per layer and per environment Several teams with separate owners

The HashiCorp tutorial names the trade-off directly: separate directories limit the scope of each apply, but the duplicated root code runs the risk of creating drift between environments over time. Its workspaces documentation adds that workspaces in one working directory share a backend, so they are not a suitable isolation mechanism when deployments need different credentials or access controls; the recommended alternative is re-usable modules instantiated by a separate configuration per deployment.

Google Cloud's best practices for root modules describe the same shape: a modules directory with the service configuration, an environments directory with one root configuration per environment, only the default workspace, and no more than 100 resources (ideally a few dozen) in a single state.

Decision rule: when production needs credentials that developers do not hold, use separate root configurations per environment. Add layers inside each environment when a second team owns part of the estate.

How should you split state?

Split state where three things differ: who owns the resources, how often they change and which credentials may change them. Do not split by resource type alone, because a split that cuts through one owner's change forces two applies in a fixed order for every release.

Ask four questions before each split:

  • Owner: does one team approve every change to these resources?
  • Change rate: do they change weekly with the application or yearly with the network?
  • Credentials: should the people who apply them be the same people who apply production data stores?
  • Dependencies: what does the next layer need from this one, and can it be published as a small set of outputs?

Pass values between layers deliberately. The terraform_remote_state documentation warns that a reader needs access to the entire state snapshot, which often includes sensitive information, and suggests publishing the data a consumer needs to a separate location instead.

Every state that more than one person writes needs a remote backend with locking. State locking blocks a second writer while an operation runs, and HashiCorp asks for great care with force-unlock, because unlocking a lock someone else holds can lead to multiple writers.

How do modules stay reusable without becoming a maze?

A module earns its place when it describes a concept of your architecture, such as "a service with its database and alarms", not a single resource. HashiCorp's module development guidance advises against thin wrappers around one resource type, recommends moderation, and suggests keeping the module tree relatively flat and composing modules rather than nesting them deeply.

Version shared modules and pin each environment to a version. Promotion then means changing one version number in staging, planning, applying and repeating in production, so the difference between environments is visible in a reviewable diff rather than hidden in copied files.

The drift-cause checklist

  • Copying an environment folder to create the next one

    What happens
    Root files diverge with every hot fix
    Countermeasure
    Thin root configurations that only call versioned modules
  • Modules referenced without a version

    What happens
    An environment picks up changes nobody promoted
    Countermeasure
    Pin a module version per environment
  • Fixes made in the cloud console

    What happens
    Real resources no longer match state
    Countermeasure
    Scheduled drift plans; console write access only for emergencies, then codified
  • Applies from laptops

    What happens
    No record of who applied which plan
    Countermeasure
    Plan and apply only in the pipeline, with the saved plan reviewed
  • Forced unlocks

    What happens
    Two writers corrupt state
    Countermeasure
    Investigate the holder first; log every unlock
  • Wide remote state reads

    What happens
    Consumers depend on internals and see secrets
    Countermeasure
    Publish small, named outputs for other layers
  • Long-lived feature workspaces

    What happens
    Forgotten resources and costs
    Countermeasure
    An end date and an owner per temporary environment
  • Resources created outside Terraform and never imported

    What happens
    Partial ownership; plans miss them
    Countermeasure
    Import or tag as unmanaged; review the inventory each quarter

Moving to a layout that scales

  1. Inventory

    List every state, its backend, who can apply it and which resources it holds.

  2. Choose the target layout

    Use the layout matrix and the state-split questions; write the decision down with its owner.

  3. Extract modules first

    Move shared definitions into modules with versions while the old layout still runs.

  4. Move state in small steps

    Move one layer of one environment at a time and confirm that the plan shows no changes before the next move.

  5. Close the side doors

    Move applies into the pipeline, separate production credentials and restrict console write access.

  6. Schedule drift detection

    Run a plan on a schedule; the plan command returns exit code 2 when changes are present, which a pipeline can turn into an alert.

When should you not restructure?

Do not split a working setup with one maintainer and one environment; the extra roots add cost without reducing risk. Do not restructure in the same quarter as a tool change or a cloud migration, because two moving parts make a failed plan hard to explain. Do not introduce layers before a second team exists to own them.

Restructure when a second team needs to apply changes, when production needs credentials others must not hold, or when a plan regularly shows changes nobody made in code.

Where AI fits in infrastructure code

AI helps with the reading, not with the apply. An assistant can summarise a large plan output, flag resources that appear in the console inventory but not in state, and draft a module's documentation from its variables. Netbase works with the major commercial and open-source AI tools and models, chosen per project.

Engineers still design the layout, review every plan themselves and approve every apply by name; no model holds production credentials or runs an apply.

What delivery record exists, and what does not

Netbase works as offshore development partner on a multi-tenant cloud ERP delivered as SaaS to small and mid-sized businesses for a US client that is not named, and names AWS, Google Cloud, DigitalOcean and Cloudflare as the cloud providers it uses. No cloud partner tier or certification is claimed.

Delivery runs in a six-step lifecycle with weekly reviews and KPI dashboards, and most Netbase projects are delivered on fixed-price contracts. No published Netbase record describes a Terraform restructuring in detail, and no duration, team size or result figure is claimed here.

Alternatives: other ways to keep environments consistent

Alternative Fits when Selection criterion
Workspaces only Environments are near-identical and share credentials Nobody needs to be kept out of production state
A wrapper tool that generates root configurations Many environments or regions repeat the same layers The team accepts one more tool in every pipeline
A managed Terraform platform Several teams need policy, run history and access control Data-residency and vendor rules allow a hosted service
Keep one root and add review discipline One small team, one environment Plans stay short enough to read in full

Teams that want to see where infrastructure practice stands overall can score it with the DevOps maturity assessment scorecard. A restructure before a move pairs with the cloud migration cutover plan, and Netbase's DevOps and platform engineering and cloud migration and modernization services cover the pipeline and the move.

What are the limits of this guide?

  • It gives decision rules, not a fixed template; the right split depends on the owners and credentials in your estate.
  • Terraform features and backend options change; check the current HashiCorp documentation before moving state.
  • It does not compare Terraform with other infrastructure-as-code tools.

Plan the next step with a Netbase consultant

Frequently asked questions

Use workspaces when environments are near-identical and share credentials. Use separate root configurations per environment when production needs its own backend, credentials or access rules, because workspaces in one directory share a backend.

One per combination of owner, change rate and credentials, per environment. A small team often needs one per environment; several teams usually need a network, data and application layer in each environment.

Run a plan on a schedule in the pipeline and alert when it reports changes. A plan run with the detailed exit code option returns code 2 when changes are present.

Yes, when state is moved rather than resources destroyed. Move one layer at a time and confirm that the plan shows no changes before the next move.

Next step

If you want a second pair of eyes on your Terraform layout before the next team joins, book a solution review with Netbase.

AI-ready cloud platform engineering for SaaS and commerce workloads AI-ready cloud platform engineering for SaaS and commerce workloads

Netbase provides cloud platform engineering for SaaS and commerce teams that need a secure, repeatable home for their software and its AI features, on AWS, Google Cloud, DigitalOcean or Cloudflare. We design the architecture, write the environments as code, connect managed and AI services and hand over a platform your team can run, built the way we run ours.

Learn More
line
AI-assisted cloud migration with a cut-over plan and a way back AI-assisted cloud migration with a cut-over plan and a way back

Netbase provides cloud migration services for companies running business applications on ageing servers or hosting to move them to AWS, Google Cloud, DigitalOcean or Cloudflare without losing data or control. AI speeds up the code and dependency assessment; every migration still has an inventory, a rehearsed cut-over, cost controls from day one and a tested rollback point.

Learn More
line
AI-assisted DevOps and platform engineering for routine releases AI-assisted DevOps and platform engineering for routine releases

Netbase provides DevOps and platform engineering for SaaS and commerce teams to make releases routine instead of risky. We set up CI/CD pipelines, repeatable environments and observability on AWS, Google Cloud, DigitalOcean or Cloudflare, with AI assistance for tests, reviews and incident triage, so every change ships the same way and problems surface before customers notice.

Learn More
line
SaaS product accelerator: launch an AI-ready SaaS on proven Netbase modules SaaS product accelerator: launch an AI-ready SaaS on proven Netbase modules

A SaaS product accelerator is a set of reusable Netbase modules for accounts, billing, roles and integrations that helps founders and product teams launch subscription software faster, with room for in-product AI from the first release. Reusing these modules can shorten development time, and the approach is proven on Printcart, Netbase's own web-to-print SaaS.

Learn More
line

Work with Netbase remotely

Every Netbase engagement is delivered remotely, so clients in any country and any industry can work with us; Netbase has worked with clients in 80 countries. Contracts and invoices are issued by Netbase JSC, and payment is made by bank transfer to Netbase JSC's company account or PayPal Business. Talk to the CEO, Huy Nguyen (David), on WhatsApp or by email.

Contact Netbase

Discuss a project

Netbase JSC helps organizations design, build, modernize, and operate digital products and AI-enabled business systems.
Project enquiries

project@netbasejsc.com

WhatsApp

+84 937 869 689

Office address

91 Nguyen Chi Thanh, Dong Da, Hanoi, Vietnam

Get in touch

Tell us what you want to build, modernize, or operate.

Tell us what you want to build, modernize, or operate.

Contact Netbase