Infrastructure Lifecycle and Operations · Topic 1 of 5

Scaling Projects and Managing Environments

Terraform Professional 002: split large projects, reuse modules, and choose between CLI workspaces, separate directories and partial backend configuration.

  • 5 min
In a nutshell
  • Split configurations by ownership, change rate and credentials; do not rely on -target.
  • CLI workspaces separate state only, within one configuration and one backend.
  • terraform.workspace returns the current workspace name.

What it is

Scaling a Terraform project means keeping plans small, reviews readable and mistakes contained as the infrastructure grows. The main tools are modules for reuse and separate configurations for separate ownership.

Managing environments means running the same design as development, staging and production without one touching another's state. The exam tests whether you can pick the right level of isolation for a scenario.

Large root modulesplit by owner and change rateSmaller configurationsShared modulesone designEnvironmentsisolated state

How it works

Splitting a growing project

A large configuration plans slowly and puts everything in one state, so one bad change can reach everything. Terraform's guidance is to split it into smaller configurations that apply independently and share values through data sources.

Natural boundaries are ownership, rate of change and credentials. A network that changes twice a year should not share a state with an application that deploys daily.

Routine use of -target is not a scaling strategy. The docs reserve it for exceptional cases such as recovering from a mistake, because regular use can hide drift.

Reusing modules

module "web" {
  source   = "app.terraform.io/acme/web/aws"
  version  = "~> 2.1"
  for_each = var.regions
  region   = each.value
}

Adding or changing a module source requires terraform init, which installs it. The version argument works for registry modules; a local path such as ./modules/web has no version and uses whatever is on disk. Since Terraform 1.15, source and version can also reference local values and variables declared with const = true.

Choosing an environment strategy

ApproachWhat is separateBest fit
CLI workspacesState only; same configuration and backendNear-identical copies using the same credentials
Directory per environmentRoot module, backend, variables, and possibly credentialsLong-lived environments with different access rules
Partial backend plus var fileState location and variable valuesOne codebase deployed by a pipeline to separate state locations
HCP Terraform workspacesConfiguration, variables, state, run history, settingsTeams that need access controls and run history per environment

The directory approach keeps each root module thin: it holds a backend block, provider settings and calls to shared modules.

CLI workspaces

terraform workspace new staging
terraform workspace select prod
terraform workspace list

Each initialized directory starts with a workspace named default. With local state, the others live under terraform.tfstate.d; with a remote backend, they are stored in that backend.

The current name is saved in .terraform, so two teammates can sit on different workspaces. In automation, TF_WORKSPACE selects one without a command, but it is easy to forget in a local shell and is meant for non-interactive use.

The docs warn against workspaces for system decomposition, or for deployments that need separate credentials and access controls. An HCP Terraform workspace is a different thing: it behaves like a separate working directory with its own settings.

Tracing a workspace value

locals {
  sizes = {
    default = "t3.micro"
    prod    = "m5.large"
  }
  size = lookup(local.sizes, terraform.workspace, "t3.small")
}

Walk through it for each workspace:

  1. In default, the key exists, so local.size is t3.micro.
  2. In prod, the key exists, so local.size is m5.large.
  3. In staging, the key is missing, so lookup returns the fallback t3.small.

Partial backend per environment

Backend blocks cannot use variables, so a pipeline passes the environment's settings at init.

terraform init -reconfigure -backend-config=prod.s3.tfbackend
terraform plan -var-file=prod.tfvars

-reconfigure applies the new settings without moving state. Using -migrate-state here would offer to copy the state of the last environment into the new location, which is the wrong result when you are only switching.

How the exam asks about this

  • "Production needs its own credentials and a restricted team; staging is otherwise identical." Use separate configurations or backends, not CLI workspaces.
  • "One state holds networking and frequently deployed applications, and plans have become slow and risky." Split it into smaller configurations and share values through data sources.
  • "A pipeline reuses one directory and must point at a different state location for each environment." Use partial configuration with -backend-config, and -reconfigure when switching.

What to remember for the exam

  • Split configurations by ownership, change rate and credentials; do not rely on -target.
  • CLI workspaces separate state only, within one configuration and one backend.
  • terraform.workspace returns the current workspace name.
  • Local workspace states live in terraform.tfstate.d; the current selection is kept in .terraform.
  • Run terraform init after adding a module or changing a backend.
  • TF_WORKSPACE selects a workspace for non-interactive runs.
Watch out

Check the current workspace or backend before applying. Running the right plan against the wrong state can propose destroying or recreating real resources, and the configuration itself will look perfectly valid.

Common mistakes

Using workspaces as a security boundary. They share one backend, so they do not provide the separate credentials and access controls that production usually needs. Use separate backends or configurations.

Copying code between environment directories. Copies drift apart over time. Keep the design in a shared module and let each environment supply only its own values and backend.

Migrating state when you meant to switch. -migrate-state copies state to the new backend location. When a shared directory moves between environments, -reconfigure is the option that leaves state where it is.

Check yourself

  • When are CLI workspaces a poor choice for environments?

    When environments need separate credentials or access controls, or when the system should be decomposed. They only give separate state within one configuration and backend.

  • A lookup uses terraform.workspace with a fallback of t3.small, and the map has no staging key. What does staging get?

    It gets t3.small, because lookup returns the default when the key is missing from the map.

  • Why use -reconfigure when a pipeline switches backend settings between environments?

    It applies the new backend settings without migrating state, so the previous environment's state is not copied to the new location.

Topic 1 of 5 in Infrastructure Lifecycle and Operations

Test yourself on Infrastructure Lifecycle and Operations

The full HashiCorp Terraform Infrastructure Engineer Professional question bank has 600 questions, with timed practice exams and an explanation for every answer.

This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.