Generate Artifacts Docs

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

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.

Graviton Migration Notes — Include when any compute resource in aws-design.json has graviton.target_architecture == "arm64" (see references/shared/graviton.md). Add a short subsection in Section 4 listing:

• Which services were migrated to ARM64 (Graviton) and their instance types/runtime platform
• Any conditional-tier services with their caveats[] (for example, “verify native extension X has an arm64 build”)
• The build step: container images must be built for arm64 (docker build --platform linux/arm64)
• A recommendation to validate with a load test post-migration (Graviton physical cores may allow further downsizing — not reflected in the cost estimate)

If cpu_architecture is x86 (user opted out) or no compute targets arm64, skip this subsection.

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 (opens in a new tab) 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:

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

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). A one-line “rollback via DNS” note is NOT sufficient — cutover is the highest-stress, lowest-judgment moment of the migration, and this subsection is the runbook the reader executes at 2am. It MUST contain:

1. Triggers — when to pull it: concrete criteria, not vibes (e.g., “error rate > X% for 10 minutes on the validation checks in 05-validate-migration.sh“, “data validation row counts diverge”, “p99 latency > 2x GCP baseline after 30 minutes”). State who decides if the team is more than one person.
2. Steps — exact commands: the literal DNS change to restore (record, old value, new value, TTL implications given the cutover TTL), what to stop on the AWS side, and how to confirm traffic is back on GCP.
3. The data question — answer it explicitly: rows written to the AWS database after cutover do NOT exist in Cloud SQL. State the chosen posture for this stack: (a) brief write-freeze before rollback + export the delta, (b) accept loss of the post-cutover window (viable for low-write apps — say so if Q12 said steady/low), or (c) reverse sync required (name the tool). Never leave this implicit — a DNS rollback with unresolved writes silently loses customer data.
4. RTO: how long the rollback takes end-to-end, dominated by DNS TTL.

Footer

End the document with:

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:

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 (opens in a new tab) — apply before incurring costs
6. Review the full Migration Guide: MIGRATION_GUIDE.md (opens in a new tab)

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 (opens in a new tab).
• 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.

Combined estimated AWS monthly run rate (required when both estimation-infra.json and estimation-ai.json exist):

Call this a recurring cloud-service run rate, never TCO. State that staffing, operations, support, migration labor, and other ownership costs are excluded.

Note BigQuery/deferred services excluded if applicable. If any GCP source baseline is partial or not comparable, show “Not comparable” rather than a combined GCP total or overall savings percentage.

Security baseline in README: When estimation-infra.json → projected_costs.breakdown.security_baseline exists, include a sub-table with component costs (GuardDuty, CloudTrail S3, etc.) from components — not only static ranges.

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)”.

Fill-In Checklist (replaces the old “TODO Items” grep hint)

Scan every generated artifact (terraform/, scripts/, ai-migration/) for placeholders (TODO, ACCOUNT_ID, <...> tokens, example.com values) and render them as ONE consolidated table — this is the reader’s single “before you can apply” list. One row per value, not per occurrence (the same billing email appearing in four places is one row listing all four locations). Step 2b generates only terraform.tfvars.example (the real terraform.tfvars is gitignored and never generated), so row 0 is always the copy step — every other row that points at terraform.tfvars depends on it having been done first:

Every “Where to get it” cell must contain a concrete command, console path, or artifact reference — never just “your value here”. Include the same table (or a link to it) in MIGRATION_GUIDE.md’s Prerequisites section, and keep the grep one-liner underneath as a verification aid:

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
• Migration shape: Extract from generation-*.json migration_plan.duration_drivers (approach + ordered stages; operational windows like watch periods may be stated as procedure — never staffing estimates or week/hour figures)

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. Fill-in checklist is complete: row 0 is the cp terraform.tfvars.example terraform.tfvars step, every placeholder (TODO, ACCOUNT_ID, <...>, example.com) present in generated artifacts appears in the Fill-in checklist table, and every row’s “Where to get it” cell contains a concrete command, console path, or artifact reference
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 Procedure subsection contains all four contract elements from above — (1) triggers with concrete criteria tied to 05-validate-migration.sh checks, (2) exact DNS/restore commands with TTL implications, (3) an explicit post-cutover-writes data posture (write-freeze + delta / accepted loss / reverse sync by name), and (4) RTO — and those steps match the generation plan. A one-line “rollback via DNS” fails this check.

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: