RFC: terraform-on-aws — Terraform analysis, optimization, and Provider migration plugin

[Sagargupta16]

Is this related to an existing feature request or issue?

No. This complements deploy-on-aws (which generates IaC) by reviewing and optimizing existing Terraform code.

Summary

This RFC proposes a terraform-on-aws plugin that analyzes existing Terraform configurations targeting AWS and provides actionable recommendations across four skills: deprecated resource detection, Provider 6.x migration, security hardening, and cost optimization.

The plugin addresses a common pain point: teams running Terraform against AWS accumulate technical debt as the provider evolves - deprecated arguments, outdated patterns, missing security controls, and cost inefficiencies. Today, engineers manually cross-reference changelogs, upgrade guides, and best-practice docs. This plugin automates that analysis.

Use case

Target users: Cloud engineers, platform teams, and DevOps consultants managing Terraform-based AWS infrastructure.

Key use cases:

• Provider upgrade preparation: Scan a codebase for deprecated resources/arguments before upgrading from Provider 5.x to 6.x (e.g., hash_key/range_key → key_schema, network_interface → primary_network_interface, DynamoDB state locking → S3 native locking)
• Security review: Detect missing encryption, overly permissive IAM policies, public S3 buckets, missing VPC flow logs, and other security gaps in Terraform code
• Cost estimation: Estimate monthly costs for Terraform-defined resources using the AWS Pricing API before terraform apply
• Best-practice alignment: Check configurations against AWS Well-Architected Framework recommendations

Before (without the plugin):

User:  I need to upgrade our Terraform AWS provider from 5.x to 6.x.
       We have 200+ .tf files across 15 modules.

Agent: I can help. Let me read through the files...
       [Reads files one by one, misses deprecations, gives inconsistent advice]

After (with terraform-on-aws):

User:  Analyze our Terraform code for provider 6.x compatibility.

Agent: Scanning 200+ .tf files across 15 modules...

       Found 23 deprecated patterns:
       - 8x hash_key/range_key → key_schema (DynamoDB)
       - 4x network_interface → primary_network_interface (EC2)
       - 3x object_lock_configuration → aws_s3_bucket_object_lock_configuration
       - 2x dynamodb_table in backend → use_lockfile (S3 native locking)
       - 6x other deprecated arguments

       Each finding includes:
       - File path and line number
       - Current code → suggested replacement
       - Link to Terraform provider upgrade guide
       - Risk level (breaking vs warning)

       Shall I generate a migration plan or auto-fix the safe changes?

Proposal

Plugin structure

plugins/terraform-on-aws/
├── .claude-plugin/
│   └── plugin.json
├── .mcp.json
└── skills/
    ├── analyze/
    │   ├── SKILL.md
    │   └── references/
    │       ├── deprecated-resources-6x.md    # Provider 6.x deprecation map
    │       ├── security-checks.md            # Security best practices
    │       ├── cost-patterns.md              # Cost estimation patterns
    │       └── well-architected-mapping.md   # WAF alignment checks
    └── migrate/
        ├── SKILL.md
        └── references/
            ├── migration-patterns.md         # Safe auto-fix patterns
            └── breaking-changes-6x.md        # Changes requiring manual review

Skills

Skill 1: analyze

Purpose: Scan Terraform configurations and produce a structured report covering deprecations, security gaps, cost estimates, and best-practice alignment.

Trigger intents: "analyze my Terraform", "review this Terraform code", "check for deprecated resources", "Terraform security audit", "estimate Terraform costs"

Workflow:

1. Discover - Find all .tf files, detect provider versions, identify modules
2. Deprecation scan - Check resources and arguments against Provider 6.x deprecation map
3. Security scan - Check for missing encryption, public access, overly permissive IAM
4. Cost estimate - Query AWS Pricing API for defined resources
5. Report - Structured findings with file:line references, severity, and fix suggestions

Skill 2: migrate

Purpose: Auto-fix safe deprecation patterns and generate a migration plan for breaking changes.

Trigger intents: "migrate to provider 6", "fix deprecated Terraform", "upgrade Terraform provider", "auto-fix deprecations"

Workflow:

1. Run analyze - Get full deprecation report
2. Classify - Separate safe auto-fixes from breaking changes requiring review
3. Apply safe fixes - With user confirmation, apply non-breaking replacements
4. Generate plan - For breaking changes, produce a step-by-step migration guide
5. Validate - Run terraform validate after changes

MCP server dependencies

Server	Type	Purpose	Required?
awslabs.aws-iac-mcp-server	stdio	Terraform/CDK resource schema validation	Yes
awslabs.aws-pricing-mcp-server	stdio	Cost estimation for defined resources	For cost analysis
awslabs.aws-documentation-mcp-server	http	AWS service docs and best practices	For WAF alignment

Defaults

Setting	Default	Rationale
Provider version target	6.x (latest)	Most common migration target
Auto-fix scope	Non-breaking only	Safe by default
Security severity threshold	MEDIUM and above	Reduce noise
Cost estimation	On-demand pricing	Conservative baseline
Output format	Markdown report	Readable in terminal and GitHub

Out of scope

• Generating new Terraform code - that's deploy-on-aws's job
• Running terraform plan/apply - the plugin analyzes code, not state
• Non-AWS providers - scoped to hashicorp/aws and hashicorp/awscc only
• Terragrunt/CDKTF - Terraform HCL only in v1

Dependencies and integrations

Complements deploy-on-aws (generates IaC) and the proposed codebase-documentor (#79, documents code). This plugin occupies the "review and optimize existing IaC" niche.