GCP To AWS

Generate Phase: Documentation Generation

Loaded by generate.md LAST, after all other artifact generation sub-files complete.

Execute ALL steps in order. Do not skip or optimize.

Overview

Produce comprehensive migration documentation from all generated artifacts. This runs LAST because it references all previously generated plans and artifacts.

Outputs:

• MIGRATION_GUIDE.md — Step-by-step migration guide organized by phase

• README.md — Quick start, artifact catalog, and architecture overview

• STARTUP_PROGRAMS.md — AWS startup program eligibility and credit guidance (AI track only)

Prerequisites

At least one generation JSON must exist in $MIGRATION_DIR/:

• generation-infra.json (infrastructure migration plan)

• generation-ai.json (AI migration plan)

• generation-billing.json (billing-only migration plan)

Scan for all generated artifacts:

• terraform/ directory (Terraform configurations)

• scripts/ directory (migration scripts)

• ai-migration/ directory (AI provider adapter and test harness)

If no generation JSON exists: STOP. Output: "No migration plans found. Stage 1 of Generate phase did not complete."

Output Structure

$MIGRATION_DIR/
├── MIGRATION_GUIDE.md     # Detailed step-by-step migration guide
└── README.md              # Quick reference and artifact catalog

Step 1: Generate MIGRATION_GUIDE.md

Build a phase-based migration guide that adapts sections based on which tracks ran.

Document Structure

The MIGRATION_GUIDE.md follows this structure:

• Title: # GCP to AWS Migration Guide

• Subtitle: > Generated by GCP to AWS Migration Advisor

• Table of Contents (auto-generated from sections)

• Section 1: Prerequisites (always included)

Prerequisites Section Content

Pre-migration: root user security

• Enable root MFA (ACCT.05). Operators must complete root MFA setup before first console sign-in. The plugin does not manage MFA devices.

• Restrict use of the root user (ACCT.02). Store root credentials in a password manager; use only for account recovery or the small handful of tasks that require root. Do not use for daily work.

• Remove any root access keys. Root access keys should not exist; if any are present, delete them before any migration work.

• Plan for day-to-day access via IAM Identity Center (ACCT.03, ACCT.04, ACCT.13). Creating IAM Identity Center users, group-based permission sets, and short-lived credentials is out of scope for this plan and is covered by the landing-zone spec.

Include these checklists:

• AWS Account Setup: account created, IAM user, AWS CLI, Terraform >= 1.5.0

• GCP Access: project access, gcloud CLI, service account with export permissions

• Tools Required: terraform, aws-cli, gcloud, docker, jq

• If AI track ran: add python >= 3.9, boto3

Conditional Sections

IF infrastructure track ran (generation-infra.json exists)

Generate the following sections:

Section 2: Infrastructure Setup — Deploy AWS Infrastructure subsection with numbered steps:

1. Review Terraform configurations in terraform/ (main.tf, variables.tf, domain .tf files)

2. Initialize and plan: cd terraform/ && terraform init && terraform plan -out=migration.tfplan

3. Review the plan output carefully before applying

4. Apply: terraform apply migration.tfplan

Post-Infrastructure Tasks checklist: verify resources, check security groups, validate IAM roles.

Section 3: Data Migration — Include ONLY if scripts/02-migrate-data.sh, scripts/03-migrate-containers.sh, or scripts/04-migrate-secrets.sh exist. If NONE of these scripts were generated, skip Section 3 entirely.

Include only subsections for scripts that were generated:

Database Migration subsection (only if scripts/02-migrate-data.sh exists) with numbered steps:

1. Run prerequisites check: ./scripts/01-validate-prerequisites.sh

2. Execute data migration (dry run first): ./scripts/02-migrate-data.sh then ./scripts/02-migrate-data.sh --execute

3. Validate data integrity: ./scripts/05-validate-migration.sh

Container Image Migration (only if scripts/03-migrate-containers.sh exists): ./scripts/03-migrate-containers.sh (dry run, then --execute)

Secrets Migration (only if scripts/04-migrate-secrets.sh exists): ./scripts/04-migrate-secrets.sh (dry run, then --execute)

Section 4: Service Migration — Per-cluster migration steps from generation-infra.json, organized by creation_order depth.

Human Expertise Advisory (BigQuery / deferred analytics) — If any service has human_expertise_required: true for BigQuery or aws_service is Deferred — specialist engagement, include a prominent callout in Section 4 next to that service:

Specialist engagement required (BigQuery): This plugin does not choose an AWS analytics or warehouse target (no Athena/Redshift/Glue recommendation). Engage your AWS account team and/or a data analytics migration partner before data warehouse, lake, or SQL analytics design. BigQuery work involves query patterns, data movement, ETL/ELT, and BI integration that must be assessed by specialists.

IF AI track ran (generation-ai.json exists)

Generate the following section:

Section 5: AI Migration with subsections:

• Setup Bedrock Access: run ./setup_bedrock.sh, enable model access in AWS Console

• Deploy Provider Adapter: review adapter file, update TODO markers, deploy with application

• Run A/B Comparison: python ai-migration/test_comparison.py --quick, review results, verify quality >= 90%

• Gradual Rollout: shadow mode, 10% traffic, scale to 100%, disable Vertex AI after 48 hours stable

IF billing-only track ran (generation-billing.json exists)

Generate the following section:

Section 2: Billing-Only Limitations — Include blockquote warning that the plan was generated from billing data only. Before Proceeding subsection recommending IaC discovery or manual audit. Using the Skeleton Terraform subsection with steps to find and resolve TODO markers.

Common Sections (always included)

AWS Credits callout (only when generation-ai.json exists):

💡 Before incurring costs: Check STARTUP_PROGRAMS.md for AWS Activate credits that apply to Bedrock and infrastructure costs. Credits do not apply retroactively — apply before running terraform apply.

Cutover section with subsections:

• Pre-Cutover Checklist (from generation plan)

• Execute Cutover (DNS switch, traffic migration, monitoring)

• Post-Cutover Monitoring (24-48 hour watch, then 30-day monitoring)

Validation and Cleanup section with subsections:

Post-migration: remove unused default VPC (ACCT.09)

Confirm first that no resources depend on the default VPC:

aws ec2 describe-instances --filters "Name=vpc-id,Values=<default-vpc-id>" \
  --region <target-region>

Delete the default VPC (this also deletes default subnets, route tables, and internet gateway associations):

aws ec2 delete-vpc --vpc-id <default-vpc-id> --region <target-region>

If the command fails with dependency errors, investigate the listed resources before retrying. Do not force-delete.

• Validation Steps checklist: services responding, performance thresholds, data integrity, cost tracking

• GCP Teardown checklist (after stability period): archive data, delete resources, disable billing

Troubleshooting section with a Common Issues table:

Rollback Procedure subsection (from generation plan — rollback triggers, steps, and RTO).

Footer

End the document with:

---
Generated by GCP to AWS Migration Advisor

Step 2: Generate README.md

Build a quick-reference README for the migration artifacts.

README Structure

The README.md follows this structure:

• Title: # GCP to AWS Migration Artifacts

• Subtitle: > Generated by GCP to AWS Migration Advisor

Immediately after the subtitle, before any other section, write a conditional Start here callout block. Include only the lines that apply to what was actually generated:

> **Start here**
>
> - **AI migration:** `cd ai-migration && ./setup_bedrock.sh --dry-run`, then re-run with `--execute` when ready
> - **Infrastructure:** `cd terraform && terraform init && terraform plan -out migration.tfplan`, then `terraform apply migration.tfplan`
> - **Both tracks:** complete AI setup first, then run Terraform

Conditional rules:

• Omit the AI line entirely if ai-migration/ was not generated

• Omit the Infra line entirely if terraform/ was not generated

• Omit the "Both" line if only one track ran

• If neither directory exists (billing-only run), omit the Start here block entirely

Next steps

Numbered steps:

1. If AI track ran: cd ai-migration && ./setup_bedrock.sh (dry run), then --execute when ready

2. If infra track ran: cd terraform && terraform init && terraform plan, then terraform apply migration.tfplan

3. Run migration scripts: ./scripts/01-validate-prerequisites.sh

4. If AI track ran: Set up AI: cd ai-migration/ && ./setup_bedrock.sh

5. If AI track ran: Review AWS credits: STARTUP_PROGRAMS.md — apply before incurring costs

6. Review the full Migration Guide: MIGRATION_GUIDE.md

Artifact Catalog

Table with columns: Artifact, Description, Status. List all generated files/directories.

Subsections:

• Migration Plans (Stage 1): list generation-*.json files

• Infrastructure (Stage 2): list .tf files, terraform/README.md (when infra Terraform was generated), and migration scripts if they exist

• AI Migration (Stage 2): list adapter, test harness, setup script if they exist

• Documentation: MIGRATION_GUIDE.md and README.md

Architecture Overview

• Source (GCP): list GCP services from design artifacts

• Target (AWS): list AWS services from design artifacts with region

• Migration Approach: summary from generation plans (phased/fast-track/conservative)

Cost Summary

Security baseline costs

Scenario A — Tier 1 alone (no compliance declared in Q2):

Per-unit pricing verified against the AWS Pricing API for us-east-1 on 2026-05-04; accuracy ±25%.

To skip the baseline, delete terraform/baseline.tf before running terraform apply.

Scenario B — Tier 1 + compliance-conditional (SOC 2 / PCI / HIPAA / FedRAMP declared in Q2):

Per-unit pricing verified against the AWS Pricing API for us-east-1 on 2026-05-04; accuracy ±25%.

Tier 1 subtotal (as in Scenario A above): $3–30/mo after trial.

Additional compliance-conditional resources:

Compliance notes:

• Security Hub does NOT provide a HIPAA-specific standard. FSBP covers many overlapping controls; for full HIPAA attestation, engage a qualified HIPAA auditor and review the AWS HIPAA Eligible Services Reference.

• FedRAMP compliance uses NIST 800-53 at the agency level, but this mapping is not directly subscribable in Security Hub — engage your AWS account team for FedRAMP attestation.

To skip the compliance-conditional section only, delete the block between ########## Compliance-Conditional ########## and ########## End Compliance-Conditional ########## in terraform/baseline.tf before terraform apply. To skip the baseline entirely, delete terraform/baseline.tf.

Table from estimation artifacts with: Current GCP Monthly, Projected AWS Monthly (use Balanced tier for the primary AWS column when estimation-infra.json exists), Timeline. Only include a "GCP data transfer egress (est.)" column when estimation-infra.json exists and migration_cost_considerations.billing_data_available is true. Do not add columns or rows for human labor, professional services, or other people-time migration costs. If billing data is unavailable, add a note below the table: "GCP data transfer egress estimates require billing data. Provide a billing export and re-run discovery to see vendor egress projections."

How to read cost tiers (required when infra estimates include Premium / Balanced / Optimized):

• The three AWS monthly totals are scenarios for the same architecture, ordered high → mid → low estimate.

• Premium — Highest resilience / highest monthly estimate in this model

• Balanced — Default scenario; compare GCP to this first

• Optimized — Lower monthly estimate; reservations / Spot / storage trade-offs assumed

• Terraform: The terraform/ directory (when present) implements one stack, aligned with the Balanced scenario. Premium and Optimized are not separate generated folders — see terraform/README.md and the migration_summary output in outputs.tf.

Include a compact three-tier row or table if the executive report does, matching figures from estimation-infra.json.

Key Decisions

Bullet list from design and generation artifacts: Compute, Database, Storage, and AI/ML (if applicable) with GCP service, AWS service, and rationale. For each GCP→AWS mapping, add how it was chosen using design-refs/fast-path.md → User-facing vocabulary: Standard pairing, Tailored to your setup, or Estimated from billing only (from the design artifact’s confidence field). For any service with human_expertise_required: true, append: "(Specialist guidance recommended — contact your AWS account team)".

TODO Items

Include a command to find all TODO markers:

grep -rn "TODO" terraform/ scripts/ ai-migration/ 2>/dev/null

Footer

End with: Generated by GCP to AWS Migration Advisor

Populate from artifacts

• Artifact catalog: List all files actually generated (check for directory/file existence)

• Architecture overview: Extract from aws-design.json, aws-design-ai.json, or aws-design-billing.json

• Cost summary: Extract from estimation-infra.json, estimation-ai.json, or estimation-billing.json; include How to read cost tiers when three infra tiers exist; state Balanced as primary vs GCP and Terraform alignment per terraform/README.md when present

• Key decisions: Extract from design artifact rationale fields and map confidence to user-facing labels per design-refs/fast-path.md → User-facing vocabulary

• Timeline: Extract from generation-*.json migration_plan.total_weeks

Step 3: Self-Check

After generating documentation, verify:

1. All file references are valid: Every file path mentioned in MIGRATION_GUIDE.md exists in the artifact directory

2. Commands are syntactically correct: All bash commands use correct syntax

3. No unresolved placeholders: All [placeholder] values are replaced with actual data from artifacts

4. Conditional sections match: Only sections for tracks that actually ran are included

5. TODO count is accurate: Count matches actual TODO markers in generated artifacts

6. Cost figures match: Values in README.md match estimation artifacts

7. Timeline matches: Week counts match generation plan artifacts

8. Rollback instructions match: Rollback steps match generation plan

Phase Completion

Report the list of generated files to the parent orchestrator. Do NOT update .phase-status.json — the parent generate.md handles phase completion.

Before reporting completion, enforce artifact output gate:

• MIGRATION_GUIDE.md exists.

• README.md exists.

• Conditional sections in docs match tracks that actually ran (infra/ai/billing).

• Referenced artifact paths in docs exist.

If this gate fails: STOP and output: "generate-artifacts-docs did not produce complete documentation artifacts."

Output:

Generated documentation:
- MIGRATION_GUIDE.md ([N] sections, covering [tracks that ran])
- README.md (artifact catalog, architecture overview, cost summary)

Sections included:
- [List which conditional sections were generated based on tracks that ran]