[DRAFT] RFC: GCP-to-AWS Migration Plugin

[icarthick]

Is this related to an existing feature request or issue?

New Feature Request

Summary

The GCP-to-AWS Migration Plugin analyzes GCP infrastructure from multiple sources and produces detailed migration plans for AWS. It supports three complementary discovery modes:

• IaC Mode: Analyzes Terraform files for high-confidence resource extraction
• Billing Mode: Parses GCP billing exports to infer infrastructure when code unavailable
• Code Mode: Scans application code to identify architectural patterns (AI/ML, auth, caching, messaging)

The plugin guides users through five sequential phases (Discover → Clarify → Design → Estimate → Execute), producing structured JSON outputs at each stage for programmatic access and iteration.

Use case

Target Audience:

• AWS customers planning or executing GCP-to-AWS migrations
• Cloud architects evaluating AWS equivalents for GCP services
• Teams needing detailed cost projections before migration commits
• Organizations with mixed GCP/AWS infrastructure seeking consolidation

Motivation & Problem:
GCP-to-AWS migrations are complex because they require:

1. Deep technical knowledge — Understanding both GCP and AWS service ecosystems and their architectural differences
2. Manual analysis — Extracting infrastructure details, understanding dependencies, and grouping related resources requires significant effort
3. Multiple tools — Orchestrating different tools for inventory, mapping, and cost estimation
4. Validation & iteration — Reviewing migration decisions across teams, managing feedback loops

Business Impact:

• Accelerates migration timelines from months to weeks
• Reduces migration risks through structured analysis and confidence tracking
• Enables informed decision-making with detailed cost projections upfront
• Provides reusable, documented migration assets (IaC + runbooks)

Proposal

Holistic Migration Analysis Approach

The plugin goes beyond simple resource translation. It:

• Multi-source discovery — Synthesizes insights from infrastructure code (Terraform), billing data, and application code patterns
• Understands deployed infrastructure — Extracts complete inventory with configuration, dependencies, and relationships
• Identifies application patterns — Recognizes how applications use services (AI/ML, auth, caching, messaging) to recommend appropriate AWS equivalents
• Creates logical clusters — Groups related resources into migration units based on data dependencies, network membership, and operational boundaries
• Produces cluster-level recommendations — Generates migration strategy per cluster, considering interdependencies and architectural coherence
• Tracks decision confidence — Distinguishes between deterministic mappings and inferred recommendations

This ensures migrations are architecturally sound rather than a collection of individually-translated resources.

Core Features

1. Discover Phase (Three Complementary Modes)

   Mode A: IaC Discovery (discover-iac.md)

   • Extracts all GCP resources from Terraform files (50+ resource types supported)
   • Classifies resources as primary or secondary with role annotations
   • Groups resources into migration clusters based on dependencies
   • Generates typed dependency edges (data_dependency, network_membership, iam_binding)

   Mode B: Billing Discovery (discover-billing.md)

   • Parses GCP billing exports (Cloud Console CSV or BigQuery JSON)
   • Infers infrastructure from SKU descriptions and billing labels
   • Generates synthetic inventory with confidence levels

   Mode C: Application Code Discovery (discover-code.md)

   • Scans application code for architectural patterns:
     • AI/ML model usage (recommend Claude on Bedrock, Nova)
     • Authentication patterns (Supabase, Firebase → recommend supabase)
     • Can run independently or synthesize findings with IaC/Billing modes

2. Clarify Phase (Interactive)

   • Captures migration strategy and preferences
   • Questions cover: target region, compute model, database tier, pricing commitment, availability
   • Applies sensible defaults if unanswered

3. Design Phase (Service Mapping)

   • Maps each GCP resource to AWS equivalents using a combination of well-known service mappings and multi-criterion evaluation
   • Incorporates user preferences from Clarify phase
   • Tracks confidence levels (deterministic/inferred) for each mapping decision

4. Estimate Phase (API or LLM Mode)

   • API Mode: Live AWS Pricing API for ±5-10% accuracy
   • LLM Mode: Embedded rate tables for ±15-25% accuracy
   • Side-by-side GCP vs AWS cost comparison (if billing data available)
   • Per-resource, per-cluster cost breakdown

5. Execute Phase (Asset Generation)

   • Generates Infrastructure-as-Code (Terraform, CloudFormation, CDK)
   • Produces migration runbook with step-by-step execution timeline
   • Creates operational documentation and runbooks
   • Validates prerequisites and environment readiness

Supported GCP Resources

Compute: Cloud Run, GKE, Compute Engine, Cloud Functions
Database: Cloud SQL, Cloud Spanner, Firestore, Bigtable
Storage: Cloud Storage (GCS)
Networking: VPC, Cloud NAT, Firewall, Cloud LB, Cloud DNS, VPC Connector, VPC Service Controls
Messaging: Pub/Sub
Platform: Cloud KMS, Cloud IAM, Cloud Monitoring, Cloud Logging, Project Services
Caching: Memorystore Redis, Memorystore Memcached

Plugin Architecture

The plugin follows awslabs/agent-plugins marketplace standards with a modular design:

High-Level Structure:

• Single plugin entry point under skills/
• Phase-specific instruction files (discover, clarify, design, estimate, execute)
• Reference materials organized by category (discovery rules, design mappings)
• Integration with AWS MCP servers (Pricing, Knowledge, IAC)

Example Skills Layout:

gcp-to-aws-migration/
├── .claude-plugin/plugin.json
├── .mcp.json
└── skills/
    └── gcp-to-aws-migration/
        ├── SKILL.md (orchestrator)
        └── references/
            ├── phases/
            │   ├── discover-iac.md
            │   ├── discover-billing.md
            │   ├── discover-code.md
            │   ├── clarify.md
            │   ├── design.md
            │   ├── estimate.md
            │   └── execute.md
            ├── discover/
            │   └── [discovery reference materials]
            └── design/
                └── [design reference tables & mappings]

Key Differentiators

• Determinism Focus: Strict parsing rules, lookup tables, confidence tracking
• Incremental Execution: Run phases independently, preserve prior outputs for re-iteration
• Structured Outputs: JSON at every stage for programmatic analysis
• Dependency Graph: Automatic extraction of resource relationships and clustering
• Cost Comparison: Side-by-side GCP actual vs AWS projected spending
• Confidence Tracking: All decisions labeled deterministic/inferred for informed decision-making

Out of scope

• Automated Infrastructure Deployment — Plugin generates IaC and runbooks; actual deployment is user's responsibility with their own CI/CD pipelines
• Real-time Monitoring & Drift Detection — Analyzes point-in-time infrastructure snapshots; does not provide continuous monitoring
• Source Code Analysis & App Migration — Focuses on infrastructure; application code analysis and app migration strategies are out of scope
• Data Migration Execution — Identifies data sources and recommends AWS services; actual data transfer/replication tools are out of scope
• Multi-Cloud Strategy — Focused on GCP-to-AWS; multi-cloud or hybrid cloud architectural planning is out of scope
• AWS Account Setup & Prerequisites — Assumes target AWS account exists; does not handle account provisioning or IAM setup
• Compliance & Security Audit — Identifies resources; detailed compliance mapping and security audit are out of scope
• Training & Change Management — Produces documentation; organizational change management and team training are out of scope

Potential challenges

Challenge: Terraform Complexity

• Edge Case: Dynamic blocks, for_each with complex expressions, variable references across modules
• Mitigation: Strict parsing rules with fallback to billing-only mode if Terraform is too complex

Challenge: Billing Data Ambiguity

• Edge Case: SKU descriptions insufficient to infer exact configuration (e.g., HA vs single-zone)
• Mitigation: Confidence levels on all inferred decisions; preference for IaC mode when available; user can override inferred values

Challenge: AWS/GCP Service Evolution

• Edge Case: New services launched, deprecated services, service renames
• Mitigation: Modular reference files allowing community contributions; regular KB updates

Challenge: Multi-Region & Complex Architectures

• Edge Case: Migrations spanning multiple regions, cross-region replication, global load balancing
• Mitigation: Clarify phase captures region preferences; Design phase considers regional constraints

Challenge: Unresolved Areas

• How to handle vendor-specific features with no AWS equivalent (e.g., GCP-specific IAM roles)
• How to manage complex migration sequencing (dependencies between clusters)
• Recommended Solution: Document as limitations in output, provide manual override capability in future versions

Dependencies and Integrations

Required Dependencies:

• AWS Pricing MCP server — For live cost estimates (API mode) during Estimate phase
• AWS Knowledge MCP server — For architecture consultation during Design phase
• AWS IAC MCP server — For IaC best practices during Execute phase

Future Integration Opportunities:

• AWS Well Architected MCP Server

Alternative solutions

**Alternative 1: Manual Migration Planning**
- Approach: Spreadsheets, documentation, manual mapping
- Limitations: Time-consuming, error-prone, lacks structured dependency analysis, no cost automation
- When to use: Very small infrastructure (<20 resources)

**Alternative 2: AWS Migration Services (AWS MGN, DMS)**
- Approach: AWS Application Migration Service, Database Migration Service
- Limitations: Focused on replication, not on architectural re-planning; doesn't provide AWS equivalent recommendations
- When to use: Infrastructure lift-and-shift without architectural changes; database replication

**Alternative 3: Third-Party Migration Platforms (CloudEndure, Cloudamize, Movere)**
- Approach: Discovery tools with cloud recommendations
- Limitations: Proprietary vendors, limited to their supported use cases, may not cover GCP→AWS specifically
- When to use: When integrated with existing enterprise migration programs

**Why This Plugin is Different:**
- **Holistic analysis** — Understands dependencies and creates logical clusters, not just individual resources
- **Two entry modes** — Works with IaC or billing exports (covers both known and unknown infrastructure)
- **Confidence tracking** — Distinguishes deterministic from inferred decisions
- **Structured outputs** — JSON at every stage for programmatic integration
- **Iterative & reversible** — Each phase can be run independently, decisions can be revised

[theagenticguy]

I want to stress-test the convention of a discrete X to AWS migration plugin. Should we consider one migration plugin which has multiple migration paths because a plugin can have multiple skills/agents? why or why not?

[icarthick]

My two cents: We should start with this specific skill gcp-to-aws-migration. Solicit feedback, learn/understand and then create abstractions when we know more.

[theagenticguy]

My two cents: We should start with this specific skill gcp-to-aws-migration. Solicit feedback, learn/understand and then create abstractions when we know more.

yep agree, we don't need a big bang for all skills in the beginning. just the folder/plugin organization convention. e.g. plugins/migration/skills/gcp-to-aws. What do you think? Considering the hierarchy of plugin marketplace - 1:M -> plugin - 1:M -> skills

[icarthick]

My two cents: We should start with this specific skill gcp-to-aws-migration. Solicit feedback, learn/understand and then create abstractions when we know more.

yep agree, we don't need a big bang for all skills in the beginning. just the folder/plugin organization convention. e.g. plugins/migration/skills/gcp-to-aws. What do you think? Considering the hierarchy of plugin marketplace - 1:M -> plugin - 1:M -> skills

Agreed. This makes sense

[krokoko]

Thank you ! Some questions:

• Have you considered splitting the discovery modes into separate skills (discover-iac, discover-billing, discover-code) that feed into a shared migrate skill? This would improve trigger accuracy, since an agent seeing Terraform files would trigger discover-iac more reliably than a monolithic skill trying to detect which mode is appropriate.
• If not,and kept as one skill, what determines which discovery mode runs? Does the agent auto-detect, or does the user specify? What happens when both Terraform AND billing exports are present?
• How will the 50+ GCP resource mappings be organized? A single mapping table file would grossly exceed limits. Will there be per-service-category files (compute-mappings.md, database-mappings.md, etc.)?
• What is the progressive disclosure strategy? Which files load at skill trigger time vs. on-demand? The deploy-on-aws SKILL.md is only 64 lines and defers everything to reference files.
• What trigger phrases should activate this skill? Should the skill also trigger on partial intents like "compare GCP and AWS costs" or "what's the AWS equivalent of Cloud Run"? Or are those out of scope?
• What is the default IaC output format? Since the user's source is Terraform, should the default output also be Terraform (matching their existing toolchain) rather than CDK?
• What should the agent do when a GCP resource has no known AWS equivalent? Silently skip? Warn the user? Block the migration plan?
• The Design, Estimate, and Execute phases overlap significantly with deploy-on-aws, so could the migration plugin's output feed into deploy-on-aws for the Execute phase rather than duplicating IaC generation logic? Or is the migration context (GCP source, dependency clusters) too different?

[icarthick]

• Have you considered splitting the discovery modes into separate skills (discover-iac, discover-billing, discover-code) that feed into a shared migrate skill? This would improve trigger accuracy, since an agent seeing Terraform files would trigger discover-iac more reliably than a monolithic skill trying to detect which mode is appropriate.

Yes, that is how i intend to write the skill. I omitted that part for keeping the RFC at a high level. In general, the principle that we are going to follow is create concise md files that get loaded only when necessary so as to avoid context bloat. When we develop this, we will probably start discover (for iac only) and then add the others incrementally

• If not,and kept as one skill, what determines which discovery mode runs? Does the agent auto-detect, or does the user specify? What happens when both Terraform AND billing exports are present?

Agent discover skill will have instructions to do a cursory scan of the repository to understand what files are present. Using this it will determine what discover modes to present to the user

• How will the 50+ GCP resource mappings be organized? A single mapping table file would grossly exceed limits. Will there be per-service-category files (compute-mappings.md, database-mappings.md, etc.)?

Yes, we intend to organize it by archetypes (compute, storage, messaging, network)

• What is the progressive disclosure strategy? Which files load at skill trigger time vs. on-demand? The deploy-on-aws SKILL.md is only 64 lines and defers everything to reference files.

Files are loaded when needed, depending on the context. The skills in this plugin are going to be a few hundred lines line, so we have to be conscious when we load what

• What trigger phrases should activate this skill? Should the skill also trigger on partial intents like "compare GCP and AWS costs" or "what's the AWS equivalent of Cloud Run"? Or are those out of scope?

Yes something similar. Other phrases include "Help me migrate to AWS" "What does an equivalent AWS architecture would look like" "Help me understand the cost of the infrastructure" "Help me analyzing the GCP resources that are deployed"

• What is the default IaC output format? Since the user's source is Terraform, should the default output also be Terraform (matching their existing toolchain) rather than CDK?

We are only targeting terraform (and other md files for summaries) for the immediate release. We may later add support for other IAC formats like pulumi, cfn. CDK is not on our roadmap

• What should the agent do when a GCP resource has no known AWS equivalent? Silently skip? Warn the user? Block the migration plan?

We intend to have two different kinds of mapping. One a static mapping list which are well known, if we failed to find one, we are going to instruct the LLM to find a mapping. We intend to design an evaluation rubric that will help the LLM pick the right candidate

• The Design, Estimate, and Execute phases overlap significantly with deploy-on-aws, so could the migration plugin's output feed into deploy-on-aws for the Execute phase rather than duplicating IaC generation logic? Or is the migration context (GCP source, dependency clusters) too different?

This is a good idea. I lean towards keeping the execute phase within this plugin for the immediate release, but would be happy to see how to integrate with deploy-on-aws (and/or re-use)