Chapter 41: Terraform Environments and Jenkins Plan Approval Apply Pipeline

41.1 Environments — dev, stage and prod

By Ravindra Bagale · Last updated: 25 October 2026

Story. An Infosys client once applied a dev change to production because both used the same folder and someone forgot to switch the workspace. The safer layout gives each environment its own folder, its own state key and often its own AWS account, while all of them call the same module. A change is promoted by merging, applying in dev, then stage, then prod with the same module version.

modules/web-server/          # shared code, versioned
envs/
  dev/
    backend.tf    key = "badge-api/dev/terraform.tfstate"
    main.tf       module "web" { source = "../../modules/web-server" ... }
    dev.tfvars    instance_type = "t3.micro"
  stage/
    backend.tf    key = "badge-api/stage/terraform.tfstate"
    stage.tfvars  instance_type = "t3.small"
  prod/
    backend.tf    key = "badge-api/prod/terraform.tfstate"
    prod.tfvars   instance_type = "t3.small"

# envs/prod/main.tf
provider "aws" {
  region = "ap-south-1"
  assume_role {
    role_arn = "arn:aws:iam::<prod-account-id>:role/TerraformDeploy"
  }
}

module "web" {
  source        = "../../modules/web-server"
  name          = "badge-prod-web"
  instance_type = var.instance_type
}

What each line does

• modules/web-server/ — The one copy of the logic every environment uses.
• envs/dev/backend.tf key = ".../dev/..." — Dev state lives under its own key, so a dev apply cannot touch prod state.
• dev.tfvars instance_type = "t3.micro" — Dev is small.
• stage.tfvars / prod.tfvars — Stage mirrors prod sizing so tests are realistic.
• role_arn = "arn:aws:iam::<prod-account-id>:role/TerraformDeploy" — Prod deploys into a separate account through a role; a placeholder id here.
• source = "../../modules/web-server" — Every environment calls the same module.
• instance_type = var.instance_type — The only difference comes from the environment's tfvars.

When it is green.

$ cd envs/dev  && terraform plan -var-file=dev.tfvars
Plan: 3 to add, 0 to change, 0 to destroy.
$ cd ../prod   && terraform plan -var-file=prod.tfvars
Plan: 0 to add, 1 to change, 0 to destroy.

When it is red.

Error: Error acquiring the state lock ... Path: badge-tfstate-.../badge-api/dev/terraform.tfstate
(you are in envs/prod but backend.tf was copied from dev)

Fix. A copied backend.tf still points at dev. Fix the key in envs/prod/backend.tf and run terraform init -reconfigure.

What: every term in plain English

• environment — One full copy of the system for one purpose: dev for building, stage for testing, prod for customers.
• environment folder — envs/dev, envs/stage, envs/prod. Each has its own backend key, tfvars and often its own AWS account.
• module version pinning — Each environment calls the module with a fixed ref or version, so prod changes only when you promote it.
• promotion — Moving the same module version from dev to stage to prod after each one passes.
• tfvars — A file of variable values for one environment, such as dev.tfvars.
• account per environment — Dev and prod in different AWS accounts, so a dev mistake cannot touch prod.
• blast radius — How much can break from one wrong command. Folders and accounts keep it small.

Example 1: Build the folder layout in one minute

When a new service starts at a Wipro client, the first pull request is the folder skeleton. Everyone then knows where dev ends and prod begins.

1. Make the folders.
2. Add an empty main.tf in each.
3. Print the tree.

mkdir -p modules/web-server envs/dev envs/stage envs/prod
for e in dev stage prod; do touch envs/$e/main.tf envs/$e/backend.tf envs/$e/terraform.tfvars; done
touch modules/web-server/main.tf modules/web-server/variables.tf modules/web-server/outputs.tf
tree -L 2

Output

.
├── envs
│   ├── dev
│   ├── prod
│   └── stage
└── modules
    └── web-server

What it shows: The module holds the logic. Each environment folder only says which version and which values.

Example 2: Give each environment its own state key and size

Same module, different values. Dev is small and cheap; prod is bigger and has two copies.

1. Write envs/dev/main.tf and envs/prod/main.tf.
2. Use different backend keys.
3. Plan both.

# envs/dev/main.tf
module "web" {
  source        = "../../modules/web-server"
  env           = "dev"
  instance_type = "t3.micro"
  instance_count = 1
}

# envs/prod/main.tf
module "web" {
  source         = "../../modules/web-server"
  env            = "prod"
  instance_type  = "t3.medium"
  instance_count = 2
}

terraform -chdir=envs/dev init -backend-config="key=badge-api/dev/terraform.tfstate"
terraform -chdir=envs/prod init -backend-config="key=badge-api/prod/terraform.tfstate"
terraform -chdir=envs/dev plan | tail -1
terraform -chdir=envs/prod plan | tail -1

Output

Plan: 3 to add, 0 to change, 0 to destroy.
Plan: 5 to add, 0 to change, 0 to destroy.

What it shows: -chdir runs Terraform in a folder without cd. The two plans read and write two separate state files.

Example 3: Promote a module version from dev to prod

At a Dream11-style company, prod uses a tagged module version. A change goes to dev first; prod moves only when the tag is updated in a reviewed pull request.

1. Tag the module repo v1.3.0.
2. Point dev at v1.3.0 and apply.
3. After testing, point stage and then prod at v1.3.0.

# envs/dev/main.tf
module "web" {
  source = "git::ssh://git@git.example.com/platform/tf-modules.git//web-server?ref=v1.3.0"
  env    = "dev"
}

# envs/prod/main.tf  (still on the old version until promoted)
module "web" {
  source = "git::ssh://git@git.example.com/platform/tf-modules.git//web-server?ref=v1.2.4"
  env    = "prod"
}

grep -h "ref=" envs/*/main.tf

Output

source = "git::ssh://git@git.example.com/platform/tf-modules.git//web-server?ref=v1.3.0"
source = "git::ssh://git@git.example.com/platform/tf-modules.git//web-server?ref=v1.2.4"
source = "git::ssh://git@git.example.com/platform/tf-modules.git//web-server?ref=v1.3.0"

What it shows: One grep shows which environment runs which version. That answers the auditor question "what is in prod?".

Example 4: Stop prod applies from the wrong account

An HDFC vendor added allowed_account_ids so a prod folder refuses to run with dev credentials, and the reverse.

1. Add allowed_account_ids in each provider block.
2. Run prod plan with the dev profile.
3. Read the error.

# envs/prod/providers.tf
provider "aws" {
  region              = "ap-south-1"
  allowed_account_ids = ["210987654321"]   # prod account
}

AWS_PROFILE=badge-dev terraform -chdir=envs/prod plan

Output

Error: AWS account ID not allowed: 123456789012

What it shows: The plan fails before any change. A wrong-profile mistake costs nothing.

Command cheat sheet

Verify: did it work?

1. Separate state keys

   aws s3 ls s3://badge-tfstate-123456789012/badge-api/
   

   Output

   PRE dev/
   PRE prod/
   PRE stage/
   

2. Wrong account refused

   AWS_PROFILE=badge-dev terraform -chdir=envs/prod plan 2>&1 | grep -c "not allowed"
   

   Output

   1
   

When it is red 1

Plan: 0 to add, 4 to change, 0 to destroy.  (in prod, expected none)

Cause. Prod picked up a new module version because the source has no ref, or a local path.

Fix, step by step

1. Pin prod to a tag with ?ref=.
2. Run init -upgrade.
3. Plan again and expect no changes.

When it is red 2

Error: AWS account ID not allowed

Cause. You are using the wrong profile for this folder.

Fix, step by step

1. Check AWS_PROFILE.
2. Log in to the right account.
3. Plan again.

When it is red 3

Error: Duplicate module call  (after copying a folder)

Cause. Two module blocks with the same name in one folder.

Fix, step by step

1. Rename one block or remove the copy.
2. Plan again.

Cleanup

for e in prod stage dev; do terraform -chdir=envs/$e destroy -auto-approve; done

Practice tasks

Homework: try at home

Recap

• One module, one folder per environment.
• Each folder has its own state key, values and often account.
• Pin module versions and promote by pull request.
• allowed_account_ids stops wrong-account applies.
• -chdir makes scripts simple.

FAQ

Why not workspaces for prod?

They share backend and credentials, so one wrong select hits prod.

Is the code duplicated in each folder?

Only the small module call and values. The logic lives in the module.

Do I need three AWS accounts?

Not for learning, but most companies separate at least prod.

How does stage differ from prod?

Same module version, smaller sizes, test data.

Can Terragrunt help?

Yes, it reduces repeated backend and provider code, but plain folders work well too.

Interview questions

1. How do you structure Terraform for dev, stage and prod?

   A shared versioned module and one folder per environment with its own backend key and values.

2. How do you promote changes?

   Bump the module ref in dev, test, then stage, then prod through reviewed pull requests.

3. How do you prevent applying to the wrong account?

   allowed_account_ids in the provider, plus separate roles per account.

4. Folders or workspaces?

   Folders for long-lived environments; workspaces for short-lived copies.

5. Why pin module versions?

   So prod changes only when you decide, not when the module changes.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards