Terraform Project Multi Environment Setup

A theater rehearses on a practice stage before opening night. Actors fix mistakes in rehearsal where nobody pays for a bad scene. Software teams follow the same habit. They keep a development environment for experiments, a staging environment for final checks, and a production environment for real users. This project shows how one Terraform codebase builds all three with different sizes and settings.

The Goal

Write the infrastructure code once. Feed it different values for each environment. Every environment stays identical in structure and differs only in scale.

Diagram: One Code, Three Environments

                +-------------------+
                |  Shared Terraform |
                |  code (main.tf)   |
                +---------+---------+
                          |
      +-------------------+-------------------+
      |                   |                   |
 dev.tfvars         staging.tfvars       prod.tfvars
 1 server           2 servers            4 servers
 t3.micro           t3.small             t3.large
      |                   |                   |
      v                   v                   v
 +---------+        +----------+        +------------+
 |   Dev   |        | Staging  |        | Production |
 +---------+        +----------+        +------------+

Folder Layout

multi-env/
  main.tf
  variables.tf
  outputs.tf
  backend.tf
  envs/
    dev.tfvars
    staging.tfvars
    prod.tfvars

Step 1: Declare Variables

variable "environment" {
  type = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Use dev, staging, or prod."
  }
}

variable "instance_type" {
  type = string
}

variable "instance_count" {
  type = number
}

variable "enable_backups" {
  type    = bool
  default = false
}

Step 2: Write One Set of Resources

locals {
  name_prefix = "shop-${var.environment}"

  common_tags = {
    Environment = var.environment
    Project     = "shop"
    ManagedBy   = "terraform"
  }
}

resource "aws_instance" "app" {
  count         = var.instance_count
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = var.instance_type

  tags = merge(local.common_tags, {
    Name = "${local.name_prefix}-app-${count.index + 1}"
  })
}

resource "aws_s3_bucket" "backups" {
  count  = var.enable_backups ? 1 : 0
  bucket = "${local.name_prefix}-backups-2026"
  tags   = local.common_tags
}

The conditional count = var.enable_backups ? 1 : 0 creates the backup bucket only when backups are switched on.

Step 3: One Variable File per Environment

envs/dev.tfvars

environment    = "dev"
instance_type  = "t3.micro"
instance_count = 1
enable_backups = false

envs/staging.tfvars

environment    = "staging"
instance_type  = "t3.small"
instance_count = 2
enable_backups = false

envs/prod.tfvars

environment    = "prod"
instance_type  = "t3.large"
instance_count = 4
enable_backups = true

Step 4: Keep Separate State per Environment

Each environment needs its own state file. Sharing one file lets a development change touch production. Pass a different state key through backend settings at init time.

terraform {
  backend "s3" {
    bucket = "shop-terraform-state"
    region = "us-east-1"
  }
}
terraform init -backend-config="key=dev/terraform.tfstate"

Staging uses key=staging/terraform.tfstate and production uses key=prod/terraform.tfstate. Run terraform init -reconfigure with the new key whenever you switch environments in the same folder.

Step 5: Run an Environment

terraform init -reconfigure -backend-config="key=dev/terraform.tfstate"
terraform plan  -var-file=envs/dev.tfvars
terraform apply -var-file=envs/dev.tfvars

Swap the key and the variable file to target staging or production.

Three Common Strategies

StrategyHow It WorksBest For
Variable files with separate state keysOne codebase and one tfvars file per environmentSmall and medium teams
WorkspacesOne backend with named workspacesNear-identical environments
Folders per environmentEach environment has its own folder calling shared modulesLarge teams needing strong isolation

Safety Rules for Production

  • Require code review before any production apply.
  • Run terraform plan and read it fully. Look for destroy lines.
  • Use separate cloud accounts for production and non-production.
  • Give development credentials no access to production.

Clean Up

terraform destroy -var-file=envs/dev.tfvars

Key Points

  • One codebase serves every environment through different input values.
  • A .tfvars file per environment holds size and feature choices.
  • Each environment needs its own state key.
  • Locals build consistent names and tags across environments.
  • A conditional count switches optional resources on or off.
  • Strong isolation and code review protect production.