Terraform - Learning Module

Loading content...

0/273

Terraform Workflow: Professional Infrastructure Operations

From Local Development to Production Pipeline

Running terraform apply from your laptop works fine for learning—but it's a recipe for disaster in production. Consider the failure modes:

No visibility: Who ran what changes and when? No one knows.
No review: A typo could delete your production database before anyone sees the plan.
No consistency: Different teammates might have different Terraform versions installed.
No auditability: When something goes wrong, you can't trace what changed.
No rollback: If an apply fails halfway through, recovering is manual and error-prone.

Professional Terraform usage requires a workflow—a defined process that takes infrastructure changes from initial proposal through review, approval, and controlled deployment. This workflow typically involves version control (Git), pull requests for code review, CI/CD pipelines for execution, and operational practices for safety.

This page covers the complete professional Terraform workflow used by mature engineering organizations.

What You Will Learn

By the end of this page, you will understand the Git-based Terraform workflow, CI/CD integration patterns for GitHub Actions and GitLab CI, code review best practices for infrastructure changes, environment promotion strategies, and operational safety practices for production infrastructure.

Git-Based Terraform Workflow

The foundation of professional Terraform usage is version control. All Terraform configuration should live in Git repositories with proper branching strategies, pull request workflows, and commit history.

The typical workflow follows this pattern:

terraform-git-workflow
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
┌─────────────────────────────────────────────────────────────────────────────┐
│                     GIT-BASED TERRAFORM WORKFLOW                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   1. CREATE BRANCH                                                          │
│   ─────────────────                                                         │
│   $ git checkout main                                                       │
│   $ git pull origin main                                                    │
│   $ git checkout -b feature/add-redis-cluster                               │
│                                                                             │
│   2. MAKE CHANGES                                                           │
│   ─────────────────                                                         │
│   • Edit .tf files for desired infrastructure changes                       │
│   • Run terraform fmt to format code                                        │
│   • Run terraform validate to check syntax                                  │
│   • Run terraform plan to preview changes locally                           │
│                                                                             │
│   3. COMMIT AND PUSH                                                        │
│   ─────────────────                                                         │
│   $ git add .                                                               │
│   $ git commit -m "Add Redis ElastiCache cluster for session caching"      │
│   $ git push origin feature/add-redis-cluster                               │
│                                                                             │
│   4. CREATE PULL REQUEST                                                    │
│   ─────────────────                                                         │
│   • Open PR in GitHub/GitLab                                                │
│   • CI automatically runs: fmt check, validate, plan                        │
│   • Plan output is posted as PR comment                                     │
│   • Reviewers examine both code AND plan output                             │
│                                                                             │
│   5. CODE REVIEW                                                            │
│   ─────────────────                                                         │
│   • Reviewer checks configuration for correctness                           │
│   • Reviewer examines plan for unintended changes                           │
│   • Address feedback, push additional commits                               │
│   • Reviewer approves PR                                                    │
│                                                                             │
│   6. MERGE AND APPLY                                                        │
│   ─────────────────                                                         │
│   • Merge PR to main branch                                                 │
│   • CI/CD pipeline triggers terraform apply                                 │
│   • Plan re-generated and applied (with optional manual approval)           │
│   • State updated, infrastructure changes complete                          │
│                                                                             │
│   7. VERIFY                                                                 │
│   ─────────────────                                                         │
│   • Verify infrastructure via monitoring/tests                              │
│   • Update documentation if needed                                          │
│   • Close related tickets                                                   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

repository-structure
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
# RECOMMENDED REPOSITORY STRUCTURE FOR MULTI-ENVIRONMENT TERRAFORM
 
infrastructure/
├── .github/
│   └── workflows/
│       ├── terraform-plan.yml      # Run on PR
│       └── terraform-apply.yml     # Run on merge to main
│
├── modules/                        # Shared modules
│   ├── vpc/
│   ├── eks/
│   ├── rds/
│   └── redis/
│
├── environments/                   # Environment-specific configurations
│   ├── development/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   └── backend.tf             # Dev state backend config
│   │
│   ├── staging/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   │   ├── providers.tf
│   │   └── backend.tf             # Staging state backend config
│   │
│   └── production/
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       ├── providers.tf
│       └── backend.tf             # Prod state backend config
│
├── scripts/                        # Helper scripts
│   ├── plan.sh
│   └── apply.sh
│
├── .terraform-version              # Pin Terraform version (for tfenv)
├── .gitignore
└── README.md
 
# ALTERNATIVE: TERRAGRUNT STRUCTURE (For DRY Configuration)
 
infrastructure/
├── terragrunt.hcl                  # Root config with common settings
├── modules/                        # Same as above
│
└── live/
    ├── development/
    │   ├── region.hcl              # Regional settings
    │   ├── vpc/
    │   │   └── terragrunt.hcl      # References ../../../modules/vpc
    │   └── eks/
    │       └── terragrunt.hcl
    │
    ├── staging/
    │   └── ...
    │
    └── production/
        └── ...

Separate State Per Environment

Each environment should have its own backend configuration pointing to a separate state file. This prevents any possibility of development changes affecting production state. Use different S3 keys, different DynamoDB tables, and consider different AWS accounts entirely.

CI/CD Pipeline Integration

CI/CD pipelines automate the validation and application of Terraform changes. A well-designed pipeline provides:

Consistency: Same Terraform version and configuration every time
Visibility: Plan outputs visible to all reviewers
Safety: Automated checks before any changes apply
Auditability: Complete record of who approved and when changes were made

.github/workflows/terraform-plan.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
# ==============================================================================
# GITHUB ACTIONS: Terraform Plan on Pull Request
# ==============================================================================
 
name: Terraform Plan
 
on:
  pull_request:
    branches: [main]
    paths:
      - 'environments/**'
      - 'modules/**'
      - '.github/workflows/terraform-*.yml'
 
permissions:
  id-token: write   # Required for OIDC authentication
  contents: read
  pull-requests: write  # To post plan as comment
 
env:
  TF_VERSION: "1.6.0"
  AWS_REGION: "us-west-2"
 
jobs:
  # =============================================================================
  # Format Check (fast, catch obvious issues)
  # =============================================================================
  format:
    name: Format Check
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}
 
      - name: Check Format
        run: terraform fmt -check -recursive -diff
 
  # =============================================================================
  # Validate and Plan for each environment
  # =============================================================================
  plan:
    name: Plan ${{ matrix.environment }}
    runs-on: ubuntu-latest
    needs: format
    strategy:
      fail-fast: false  # Continue other envs if one fails
      matrix:
        environment: [development, staging, production]
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}
 
      # OIDC authentication - no stored credentials!
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsTerraform
          aws-region: ${{ env.AWS_REGION }}
 
      - name: Terraform Init
        working-directory: environments/${{ matrix.environment }}
        run: terraform init -input=false
 
      - name: Terraform Validate
        working-directory: environments/${{ matrix.environment }}
        run: terraform validate
 
      - name: Terraform Plan
        id: plan
        working-directory: environments/${{ matrix.environment }}
        run: |
          terraform plan -input=false -no-color -out=tfplan 2>&1 | tee plan.txt
          echo "plan<<EOF" >> $GITHUB_OUTPUT
          cat plan.txt >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
        continue-on-error: true
 
      # Post plan as PR comment
      - name: Post Plan Comment
        uses: actions/github-script@v7
        with:
          script: |
            const output = `### Terraform Plan - ${{ matrix.environment }}
            
            #### Terraform Format 🖌: \`${{ needs.format.result }}\`
            #### Terraform Init ⚙️: \`Success\`
            #### Terraform Plan 📖: \`${{ steps.plan.outcome }}\`
            
            <details><summary>Show Plan</summary>
            
            \`\`\`terraform
            ${{ steps.plan.outputs.plan }}
            \`\`\`
            
            </details>
            
            *Pushed by: @${{ github.actor }}, Action: \`${{ github.event_name }}\`*`;
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: output
            });
 
      - name: Plan Status
        if: steps.plan.outcome == 'failure'
        run: exit 1
 
      # Store plan for apply job
      - name: Upload Plan
        uses: actions/upload-artifact@v4
        with:
          name: tfplan-${{ matrix.environment }}
          path: environments/${{ matrix.environment }}/tfplan

.github/workflows/terraform-apply.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
# ==============================================================================
# GITHUB ACTIONS: Terraform Apply on Merge to Main
# ==============================================================================
 
name: Terraform Apply
 
on:
  push:
    branches: [main]
    paths:
      - 'environments/**'
      - 'modules/**'
 
permissions:
  id-token: write
  contents: read
 
env:
  TF_VERSION: "1.6.0"
  AWS_REGION: "us-west-2"
 
jobs:
  # =============================================================================
  # Apply changes in order: dev -> staging -> production
  # =============================================================================
  
  apply-development:
    name: Apply Development
    runs-on: ubuntu-latest
    environment: development  # GitHub Environment for protection rules
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}
 
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::111111111111:role/GitHubActionsTerraform
          aws-region: ${{ env.AWS_REGION }}
 
      - name: Terraform Init
        working-directory: environments/development
        run: terraform init -input=false
 
      - name: Terraform Apply
        working-directory: environments/development
        run: terraform apply -input=false -auto-approve
 
  apply-staging:
    name: Apply Staging
    runs-on: ubuntu-latest
    needs: apply-development
    environment: staging  # May have required reviewers
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}
 
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::222222222222:role/GitHubActionsTerraform
          aws-region: ${{ env.AWS_REGION }}
 
      - name: Terraform Init
        working-directory: environments/staging
        run: terraform init -input=false
 
      - name: Terraform Apply
        working-directory: environments/staging
        run: terraform apply -input=false -auto-approve
 
  apply-production:
    name: Apply Production
    runs-on: ubuntu-latest
    needs: apply-staging
    environment: production  # Required reviewers + wait timer
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}
 
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::333333333333:role/GitHubActionsTerraform
          aws-region: ${{ env.AWS_REGION }}
 
      - name: Terraform Init
        working-directory: environments/production
        run: terraform init -input=false
 
      - name: Terraform Plan
        working-directory: environments/production
        run: terraform plan -input=false -no-color
 
      - name: Terraform Apply
        working-directory: environments/production
        run: terraform apply -input=false -auto-approve

Use OIDC, Not Static Credentials

Modern CI/CD should use OpenID Connect (OIDC) for cloud authentication, not stored access keys. OIDC provides short-lived credentials, eliminates secret rotation burden, and reduces blast radius if credentials are exposed. AWS, Azure, and GCP all support OIDC with GitHub Actions, GitLab CI, and other platforms.

Code Review Best Practices for Infrastructure

Infrastructure code review differs from application code review. A bug in application code might cause a feature to malfunction; a bug in infrastructure code might delete your production database or expose your network to the internet.

What to Review:

Infrastructure Code Review Checklist

•Plan Output First — Review the terraform plan output before the code. Does it match what you expected? Any unexpected destroys or replacements?
•Resource Deletions — Any resources being destroyed? Especially in production, verify these are intentional. The -destroy indicator is a red flag requiring explanation.
•Security Group Changes — Opening ports (especially 0.0.0.0/0)? Removing ingress restrictions? These need security team review.
•IAM Policy Changes — New permissions added? Star (*) permissions? Policy that allows cross-account access? These need security team review.
•Encryption Settings — Is encryption enabled for new S3 buckets, RDS instances, EBS volumes? Disabled encryption is a compliance violation.
•Naming Conventions — Do resource names follow organizational standards? Are tags complete (cost center, owner, environment)?
•State Impact — Does this change affect state structure? Renamed resources that might cause recreation?
•Cost Implications — Is this adding expensive resources? Is the instance type appropriate for the environment?
•Hardcoded Values — Are there hardcoded values that should be variables? Magic numbers without explanation?
•Module Versions — Are module versions pinned? Is there a reason for version changes?

dangerous-patterns-to-watch
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
# ==============================================================================
# DANGEROUS PATTERNS TO WATCH FOR IN CODE REVIEW
# ==============================================================================
 
# 🚨 DANGER: Security group open to the world
resource "aws_security_group_rule" "dangerous" {
  type        = "ingress"
  from_port   = 22
  to_port     = 22
  protocol    = "tcp"
  cidr_blocks = ["0.0.0.0/0"]  # <-- SSH open to internet!
  security_group_id = aws_security_group.web.id
}
 
# 🚨 DANGER: Overly permissive IAM policy
resource "aws_iam_policy" "dangerous" {
  name = "admin-everything"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "*"           # <-- Full admin access!
      Resource = "*"
    }]
  })
}
 
# 🚨 DANGER: Public S3 bucket
resource "aws_s3_bucket_public_access_block" "dangerous" {
  bucket = aws_s3_bucket.data.id
  
  block_public_acls       = false  # <-- Allows public ACLs!
  block_public_policy     = false  # <-- Allows public policies!
  ignore_public_acls      = false
  restrict_public_buckets = false
}
 
# 🚨 DANGER: Unencrypted RDS
resource "aws_db_instance" "dangerous" {
  identifier     = "production-db"
  engine         = "postgres"
  instance_class = "db.r5.large"
  
  storage_encrypted = false  # <-- No encryption at rest!
  # kms_key_id      = null   # <-- No KMS key specified
}
 
# 🚨 DANGER: Disabled deletion protection
resource "aws_db_instance" "dangerous" {
  identifier     = "production-db"
  engine         = "postgres"
  instance_class = "db.r5.large"
  
  deletion_protection = false  # <-- Can be accidentally deleted!
}
 
# 🚨 DANGER: Hardcoded secrets
resource "aws_db_instance" "dangerous" {
  identifier     = "production-db"
  engine         = "postgres"
  instance_class = "db.r5.large"
  
  username = "admin"
  password = "supersecretpassword123"  # <-- Secret in code!
}
 
# ✅ SAFE: Use secrets manager or variables
resource "aws_db_instance" "safe" {
  identifier     = "production-db"
  engine         = "postgres"
  instance_class = "db.r5.large"
  
  username                    = var.db_username
  manage_master_user_password = true  # AWS manages password in Secrets Manager
}

Required Reviewers for Production

Configure your CI/CD to require additional approvers for production changes. GitHub Environments, GitLab Protected Environments, and Terraform Cloud all support required reviewers. For high-risk changes (IAM, networking, databases), consider requiring security team approval.

Environment Promotion Strategies

Infrastructure changes should flow through environments just like application changes: development → staging → production. This catches issues before they affect production users.

environment-promotion-patterns
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
┌─────────────────────────────────────────────────────────────────────────────┐
│                    ENVIRONMENT PROMOTION PATTERNS                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   PATTERN 1: SEQUENTIAL PIPELINE (Most Common)                              │
│   ───────────────────────────────────────────                               │
│                                                                             │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐               │
│   │  DEVELOPMENT │────▶│    STAGING   │────▶│  PRODUCTION  │               │
│   │  (auto-apply)│     │ (auto-apply) │     │(manual gate) │               │
│   └──────────────┘     └──────────────┘     └──────────────┘               │
│                                                                             │
│   • Same code flows through all environments                                │
│   • Problems caught early in dev/staging                                    │
│   • Production requires manual approval                                     │
│                                                                             │
│   ─────────────────────────────────────────────────────────────────────────│
│                                                                             │
│   PATTERN 2: PARALLEL WITH DIFFERENT TIMING                                 │
│   ─────────────────────────────────────────                                 │
│                                                                             │
│     PR Created ───▶ Dev Plan + Dev Apply                                    │
│                                                                             │
│     PR Merged ────▶ Staging Plan + Staging Apply                            │
│                         │                                                   │
│                         ▼                                                   │
│                     Wait 24 hours                                           │
│                         │                                                   │
│                         ▼                                                   │
│                     Prod Plan + Prod Apply (with approval)                  │
│                                                                             │
│   ─────────────────────────────────────────────────────────────────────────│
│                                                                             │
│   PATTERN 3: CANARY/RING DEPLOYMENT                                         │
│   ─────────────────────────────────────                                     │
│                                                                             │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐               │
│   │  PRODUCTION  │────▶│  PRODUCTION  │────▶│  PRODUCTION  │               │
│   │   RING 0     │     │    RING 1    │     │    RING 2    │               │
│   │(internal/1%) │     │(early/10%)   │     │(general/90%) │               │
│   └──────────────┘     └──────────────┘     └──────────────┘               │
│                                                                             │
│   • Used for large-scale infrastructure                                     │
│   • Gradual rollout with monitoring between stages                          │
│   • Allow rollback between rings                                            │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

promotion-with-drift-detection
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
# ==============================================================================
# DRIFT DETECTION BEFORE PROMOTION
# ==============================================================================
 
# It's critical to check for drift before promoting changes.
# If production has drifted from its last known state, your carefully-tested
# changes might interact unexpectedly with that drift.
 
name: Drift Detection
 
on:
  schedule:
    - cron: '0 6 * * *'  # Daily at 6 AM
  workflow_dispatch:      # Manual trigger
 
jobs:
  drift-detection:
    name: Detect Drift - ${{ matrix.environment }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        environment: [development, staging, production]
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}
 
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
          aws-region: us-west-2
 
      - name: Terraform Init
        working-directory: environments/${{ matrix.environment }}
        run: terraform init -input=false
 
      - name: Detect Drift
        id: drift
        working-directory: environments/${{ matrix.environment }}
        run: |
          terraform plan -input=false -detailed-exitcode -out=tfplan 2>&1 | tee plan.txt
          echo "exit_code=$?" >> $GITHUB_OUTPUT
        continue-on-error: true
 
      # Exit code 2 = changes detected (drift)
      - name: Alert on Drift
        if: steps.drift.outputs.exit_code == '2'
        uses: slackapi/slack-github-action@v1
        with:
          channel-id: 'C012345'
          slack-message: |
            :warning: *Drift Detected in ${{ matrix.environment }}*
            
            Infrastructure has drifted from Terraform state.
            Review: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

Drift Is a Silent Killer

Drift occurs when infrastructure is modified outside Terraform (console changes, other tools, manual interventions). Regular drift detection prevents surprises. If you find drift, decide: reconcile to Terraform (refresh state) or reconcile to actual (update config). Don't ignore it.

Operational Safety Practices

Production infrastructure changes carry real risk. A misconfigured change can take down your service, expose sensitive data, or cause irreversible data loss. These operational safety practices minimize risk.

Production Safety Checklist

•Never terraform apply without reviewing the plan — Even with CI/CD, ensure plans are reviewed before apply. The -auto-approve flag should be preceded by a plan display.
•Use -target sparingly and with caution — The -target flag applies changes to specific resources only. It can leave state inconsistent. Only use for debugging, never as routine practice.
•Lock production state — Beyond Terraform's built-in locking, consider external controls: only CI/CD can write to production state, humans have read-only access.
•Limit blast radius with smaller configurations — Don't manage your entire company's infrastructure in one Terraform configuration. Split by environment, team, or component.
•Use prevent_destroy for critical resources — Databases, S3 buckets with important data, and other critical resources should have lifecycle { prevent_destroy = true }.
•Implement change windows — Apply production changes during low-traffic periods. Don't deploy on Fridays or before holidays.
•Have a rollback plan — Know how to revert. Can you revert the PR and re-apply? Do you have a previous state backup? Have you tested rollback?
•Monitor after changes — Watch metrics, logs, and alerts after applying changes. Have an on-call engineer available to respond to issues.

operational-commands-reference
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# ==============================================================================
# OPERATIONAL COMMANDS REFERENCE
# ==============================================================================
 
# VIEW CURRENT STATE
terraform state list                     # List all resources
terraform state show aws_instance.web    # Show specific resource
terraform output                         # Show all outputs
terraform providers                      # Show configured providers
 
# PLANNING
terraform plan                           # Standard plan
terraform plan -out=tfplan               # Save plan to file
terraform plan -target=aws_instance.web  # Plan single resource (use carefully!)
terraform plan -refresh=false            # Skip state refresh (faster, but stale)
terraform plan -parallelism=5            # Reduce parallelism (for rate limiting)
 
# APPLYING
terraform apply                          # Apply with interactive approval
terraform apply tfplan                   # Apply saved plan (no re-plan)
terraform apply -auto-approve            # Skip approval (CI/CD only!)
terraform apply -parallelism=5           # Reduce parallelism
 
# STATE OPERATIONS (backup first!)
terraform state pull > backup.tfstate    # Download state to local file
terraform state mv OLD NEW               # Rename resource in state
terraform state rm RESOURCE              # Remove from state (doesn't delete!)
terraform import TYPE.NAME ID            # Import existing resource
 
# REFRESHING
terraform refresh                        # Update state from real resources
terraform apply -refresh-only            # Newer: refresh with plan/apply workflow
 
# DESTROYING (extreme caution!)
terraform destroy                        # Destroy all managed resources
terraform destroy -target=RESOURCE       # Destroy specific resource
terraform plan -destroy                  # Preview destruction without destroying
 
# DEBUGGING
TF_LOG=DEBUG terraform plan              # Very verbose logging
TF_LOG=TRACE terraform apply             # Extremely verbose (includes API calls)
terraform console                        # Interactive expression evaluator
terraform graph | dot -Tpng > graph.png  # Visualize resource graph
 
# VERSION MANAGEMENT
terraform version                        # Show Terraform version
terraform --version                      # Same
terraform providers lock                 # Update .terraform.lock.hcl

The -target Flag Is Not For Routine Use

Using -target regularly indicates a design problem. It's intended for exceptional circumstances like recovering from errors. Regular use leads to state drift, broken dependencies, and configurations that can only be applied in specific orders. If you need -target often, split your configuration.

Terraform Cloud and Enterprise

For organizations seeking a managed solution, Terraform Cloud (SaaS) and Terraform Enterprise (self-hosted) provide a complete workflow platform. These platforms handle state management, execution, policy enforcement, and collaboration without custom CI/CD pipelines.

Terraform Cloud/Enterprise Features
Feature	Description	Benefit
Remote State	Managed state storage with encryption, locking, versioning	No S3/DynamoDB setup required
Remote Execution	Runs execute in Terraform Cloud, not locally	Consistent execution environment, no local dependencies
VCS Integration	Automatic plans on PR, applies on merge	No custom CI/CD pipelines needed
Policy as Code (Sentinel)	Define policies that run before apply	Enforce compliance programmatically
Private Registry	Host internal modules with versioning and discovery	Easy organizational module sharing
SSO/SAML	Enterprise authentication integration	Centralized access management
Audit Logging	Complete record of all operations	Compliance and troubleshooting
Cost Estimation	Estimate infrastructure costs before apply	Budget awareness during development

terraform-cloud-config.tf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# ==============================================================================
# TERRAFORM CLOUD CONFIGURATION
# ==============================================================================
 
terraform {
  cloud {
    organization = "my-company"
    
    workspaces {
      name = "infrastructure-production"
    }
  }
  
  required_version = ">= 1.5.0"
  
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}
 
# With Terraform Cloud:
# - Remote state is automatic (no backend config needed)
# - terraform plan/apply execute in the cloud
# - VCS integration triggers runs automatically
# - Variables and secrets managed in the UI/API

sentinel-policy-example.sentinel
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
# ==============================================================================
# SENTINEL POLICY: Enforce Encryption on All S3 Buckets
# File: policies/s3-encryption.sentinel
# ==============================================================================
 
import "tfplan/v2" as tfplan
 
# Get all S3 bucket resources
s3_buckets = filter tfplan.resource_changes as _, rc {
    rc.type is "aws_s3_bucket" and
    rc.mode is "managed" and
    (rc.change.actions contains "create" or rc.change.actions contains "update")
}
 
# Check that all buckets reference a server-side encryption configuration
# (This checks for the presence of related resources)
main = rule {
    all s3_buckets as _, bucket {
        # Must have encryption configuration resource
        any tfplan.resource_changes as _, rc {
            rc.type is "aws_s3_bucket_server_side_encryption_configuration" and
            rc.change.after.bucket is bucket.change.after.bucket
        }
    }
}
 
# ==============================================================================
# SENTINEL POLICY: Require Tags on All Resources
# File: policies/required-tags.sentinel
# ==============================================================================
 
import "tfplan/v2" as tfplan
 
# Required tags that must exist on all taggable resources
required_tags = ["Environment", "CostCenter", "Owner"]
 
# Taggable resource types
taggable_types = [
    "aws_instance",
    "aws_s3_bucket", 
    "aws_db_instance",
    "aws_vpc",
    "aws_subnet",
]
 
# Get all taggable resources being created or updated
taggable_resources = filter tfplan.resource_changes as _, rc {
    rc.type in taggable_types and
    (rc.change.actions contains "create" or rc.change.actions contains "update")
}
 
# Check that all required tags are present
main = rule {
    all taggable_resources as _, resource {
        all required_tags as tag {
            resource.change.after.tags contains tag
        }
    }
}

When to Use Terraform Cloud

Consider Terraform Cloud when: (1) You don't want to manage state infrastructure (S3, DynamoDB), (2) You need policy enforcement (Sentinel), (3) You want turnkey VCS integration, (4) You lack CI/CD expertise to build custom pipelines. The free tier supports small teams; paid tiers add enterprise features.

Troubleshooting Common Terraform Issues

Even with the best practices, you'll encounter issues. Here are solutions to the most common Terraform problems.

Common Issues and Solutions
Problem	Cause	Solution
State lock error	Previous run crashed or another user is running	Wait for other run; if stuck, `terraform force-unlock LOCK_ID`
Provider not found	terraform init not run, or version mismatch	Run `terraform init -upgrade`
Resource already exists	Resource created outside Terraform	Import: `terraform import ADDR ID`
Cycle error	Circular dependency between resources	Use `depends_on` to break cycle, or restructure
Timeout errors	Resource taking too long to create	Increase timeouts in resource block
Invalid credentials	Expired or missing cloud credentials	Re-authenticate, check environment variables
Plan shows destroy-create	Changed an immutable attribute	Confirm change is intended, or adjust config
Module not found	Wrong source path or version	Check source URL, run `terraform init`
State contains secrets I need	Need to read a value from state	`terraform state show RESOURCE` or `terraform output`

debugging-techniques
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
# ==============================================================================
# DEBUGGING TECHNIQUES
# ==============================================================================
 
# Enable debug logging
$ TF_LOG=DEBUG terraform plan 2>&1 | tee debug.log
 
# Even more verbose (shows API requests)
$ TF_LOG=TRACE terraform apply 2>&1 | tee trace.log
 
# Log to file only
$ TF_LOG=DEBUG TF_LOG_PATH="./terraform.log" terraform plan
 
# Test expressions interactively
$ terraform console
> length(var.subnets)
3
> cidrsubnet("10.0.0.0/16", 8, 1)
"10.0.1.0/24"
> aws_instance.web.public_ip
"52.10.20.30"
 
# Visualize resource graph
$ terraform graph | dot -Tpng -o graph.png
 
# Show providers in use
$ terraform providers
 
# Validate configuration syntax
$ terraform validate
 
# Check formatting
$ terraform fmt -check -diff -recursive
 
# ==============================================================================
# RECOVERING FROM STATE ISSUES
# ==============================================================================
 
# State corrupted or lost?
 
# 1. If you have versioning enabled on state bucket:
#    - Restore previous version of terraform.tfstate from S3/Azure/GCS
 
# 2. If no backup, re-import everything:
$ terraform import aws_vpc.main vpc-12345abc
$ terraform import aws_subnet.public[0] subnet-67890def
# ... for each resource
 
# 3. Use terraform state rm to remove problem resources:
$ terraform state rm aws_instance.problematic
# Then re-import or recreate
 
# State out of sync with reality?
$ terraform apply -refresh-only  # Update state to match reality

Summary: Terraform Workflow

Professional Terraform usage is about process as much as syntax. Let's consolidate the key points:

Key Takeaways

•Git is the foundation — All infrastructure code lives in version control with proper branching and PR workflows.
•CI/CD automates the workflow — Plans run on PR, applies run on merge. Use OIDC for authentication, not static credentials.
•Code review includes plan review — Reviewers must examine terraform plan output, not just the code. Watch for deletions, security changes, and cost implications.
•Promote through environments — Changes flow from development through staging to production, with increasing gates and approvals.
•Detect drift regularly — Schedule drift detection to catch out-of-band changes before they cause problems.
•Safety practices are non-negotiable — prevent_destroy on critical resources, change windows for production, rollback plans, and post-change monitoring.
•Consider Terraform Cloud — For managed state, policy enforcement, and turnkey workflows without custom CI/CD.

Module Complete:

You've now mastered Terraform—from the fundamentals of HCL and providers, through state management and modules, to professional workflows. This knowledge equips you to manage infrastructure as code at any scale, from personal projects to enterprise platforms.

The key to mastery is practice. Start with simple configurations, build reusable modules, establish team workflows, and continuously refine your approach based on operational experience. Infrastructure as Code is a journey, and you now have the map.

Module Complete: Terraform Mastery Achieved

You now understand Terraform comprehensively—fundamentals, providers, resources, state, modules, and professional workflows. This knowledge positions you to design, implement, and operate infrastructure as code for any organization, following the practices used by the world's most sophisticated engineering teams.