Generate Docs

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

Step 0: Detect Data Store Presence

Scan aws-design.json.services[] to determine which compute and data store types exist in the design:

Also extract:

• deferred_addons[] — entries from aws-design.json.deferred[]
• all_services[] — full list of designed services for README generation
• target_region — from preferences.json.global.target_region (default: us-east-1)
• heroku_apps[] — list of unique app names from design services
• beanstalk_web_apps[] — unique app names from Elastic Beanstalk web services, plus each name sanitized by replacing - with _
• migration_approach — from preferences.json.global.migration_approach ("full_cutover" or "interim_cutover_data_first")
• migration_method — from preferences.json.data.migration_method ("pg_dump_restore", "dms", "bucardo", "wal_g")
• containerization_status — from preferences.json.operational.containerization_status ("containerized", "buildpack_only", "partial")
• target_exit_date — from preferences.json.global.target_exit_date (ISO date or null)

Step 1: Generate MIGRATION_GUIDE.md

Write the migration guide to $MIGRATION_DIR/MIGRATION_GUIDE.md using the template below.

Critical rules:

• Include a data migration procedure section ONLY for data store types where the corresponding flag is true.
• OMIT the entire section (heading and content) for data store types NOT present in the design.
• Include deferred add-ons as manual migration items if any exist.
• Use connection parameter placeholders (never real credentials).

Template: MIGRATION_GUIDE.md

Verify all resources are created successfully:

Record the output values — they are needed for data migration and application deployment.

Phase 2: Data Migration

{{IF has_postgres}}

PostgreSQL Migration (Heroku Postgres → RDS/Aurora)

Strategy: Use pg_dump / pg_restore for a full database migration with minimal downtime.

Pre-Migration Steps

1. Enable maintenance mode on Heroku to prevent writes during migration:

   bashCopy

   heroku maintenance:on -a {{app_name}}

2. Verify source database size and estimate transfer time:

   bashCopy

   heroku pg:info -a {{app_name}}

Execute Migration

Run the database migration script:

Or execute manually:

Post-Migration Verification

Compare row counts between source and target to confirm data integrity.

{{IF migration_approach == “interim_cutover_data_first”}}

Interim Database Exposure (TLS Prerequisite, Then a Scoped Allowlist)

During the interim period your Heroku app connects to the AWS database. Work through the steps below in the order given — Step 1 is a prerequisite gate that must pass before any network path is opened in Step 2. The database stays private by default; Step 2 is about picking the narrowest path that works for your Heroku runtime.

⚠️ Never open port 5432 to 0.0.0.0/0. TLS protects the traffic, not the listener — a world-reachable database port is still exposed to internet-wide port scanning, credential stuffing, and protocol-level exploitation, and Heroku’s “dynamic dyno IPs” are not a reason to accept it. Every path below ends in a bounded, enumerated allowlist.

Step 1 (prerequisite) — Enforce TLS and prove it is in effect

Complete every part of Step 1 and pass its verification gate before touching Step 2.

1. Require TLS on the database. The generated Terraform already sets rds.force_ssl = 1 for this database, so terraform apply puts it in place — there is no console step and no way to skip it. Where the parameter lives, and whether it needs a reboot, depends on the engine:

   • RDS for PostgreSQL — set in the instance-level aws_db_parameter_group. The parameter is static, so reboot the instance once so it takes effect:

     bashCopy

     aws rds reboot-db-instance --db-instance-identifier <db_identifier>

   • Aurora PostgreSQL — set in the cluster-level aws_rds_cluster_parameter_group (a cluster parameter, so an instance-level group cannot carry it). The parameter is dynamic here, so no reboot is needed and reboot-db-instance does not apply to a cluster. terraform apply is sufficient.

   Defaults differ by engine, which is why the generated Terraform always sets this explicitly rather than relying on them. RDS for PostgreSQL: rds.force_ssl defaults to 1 (on) on major version 15 and later; on 14 and earlier the default is 0 (off). Aurora PostgreSQL: the default is 0 (off) on version 16 and older, and 1 (on) only from version 17 — so on the Aurora version this guide pins, TLS is not enforced by default.

   Either way, do not treat this as done because the code exists — step 4 below is the gate that proves it.

2. Ship the RDS CA bundle with your Heroku app so the client can verify the server certificate:

   bashCopy

   curl -o config/rds-ca-bundle.pem https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem
   git add config/rds-ca-bundle.pem && git commit -m "Add RDS CA bundle" && git push heroku main

3. Point DATABASE_URL at AWS with full certificate verification (verify-full, not require — require encrypts but does not authenticate the server):

   bashCopy

   heroku config:set DATABASE_URL="postgres://{{TARGET_DB_USER}}:{{TARGET_DB_PASSWORD}}@{{TARGET_DB_HOST}}:{{TARGET_DB_PORT}}/{{TARGET_DB_NAME}}?sslmode=verify-full&sslrootcert=config/rds-ca-bundle.pem" -a {{app_name}}

4. Verification gate. From a host that can already reach the database (for example the workstation or bastion you ran pg_restore from), confirm enforcement is real rather than assumed:

   bashCopy

   # (a) pg_hba rules must be hostssl, not host
   psql "$ADMIN_DATABASE_URL" -c "SELECT type, database, auth_method FROM pg_hba_file_rules;"
   
   # (b) a plaintext connection must be REJECTED
   psql "postgres://{{TARGET_DB_USER}}@{{TARGET_DB_HOST}}:{{TARGET_DB_PORT}}/{{TARGET_DB_NAME}}?sslmode=disable"
   # Expected: FATAL: no pg_hba.conf entry for host "...", user "...", database "...", SSL off

   If (a) shows host instead of hostssl, or (b) succeeds, stop here — rds.force_ssl is not in effect (most often a missed reboot or a parameter group that was never attached). Do not open any network path until both checks pass.

Step 2 — Choose the narrowest connectivity path

Determine your runtime first: heroku spaces:info --space <space_name> succeeds only if the app runs in a Private Space; otherwise the app is on the Common Runtime. Then take the first path that applies.

Path A — Private Space peered to your AWS VPC (preferred: no public exposure at all). Available on Cedar-generation Private Spaces. Private Space Peering establishes a private network connection between your dynos and an AWS VPC you control that does not traverse the public internet, so the database stays Not publicly accessible in private subnets.

Requirements and consequences:

• Your VPC must use an RFC 1918 CIDR that does not overlap the Private Space CIDRs (default 10.0.0.0/16, 10.1.0.0/16, 172.17.0.0/16); check with heroku spaces:peering:info before requesting.
• Add a route for the Space CIDR to the route tables of the subnets holding the database.
• Allowlist: the Space’s dyno CIDRs from heroku spaces:peering:info (e.g. 10.0.128.0/20, 10.0.144.0/20) — private ranges, a handful of entries.
• VPC peering is not available for Fir-generation Private Spaces. If your space is Fir, use Path B.

Path B — Private Space stable outbound IPs (no peering available). Every Private Space, Cedar or Fir, egresses through a NAT gateway from “a small, stable list of IP addresses dedicated to the space.” List them and allowlist those /32s:

Allowlist: each outbound IP as a /32 (typically 4 addresses).

Path C — Common Runtime plus a static-egress add-on. Common Runtime dynos have no controllable egress address — Heroku states you cannot control the originating IP address of outbound dyno requests, so there is no set of dyno IPs to allowlist. Do not compensate by widening the allowlist. Instead route the database connection through a SOCKS5 proxy add-on that owns static IPs, then allowlist the proxy:

• QuotaGuard Static — heroku addons:create quotaguardstatic. Provides a load-balanced pair of static IPs and a SOCKS5 tunnel (QGTunnel) that carries arbitrary TCP, PostgreSQL included, without application code changes.
• Fixie Socks — heroku addons:create fixie-socks. A standard SOCKS V5 proxy giving static outbound IPs for database and other TCP traffic; fixie-wrench forwards a local port for runtimes with no native SOCKS5 support.

Read the add-on’s own dashboard for its current IP list — the addresses are per-plan and can change when you change plans.

Allowlist: the proxy’s static IPs as /32s (typically 2).

Paths B and C send traffic over the public internet, so they additionally require the database to be publicly accessible and its DB subnet group to sit in subnets with an internet gateway route. The generated Terraform places the database in private subnets, so a Path B/C interim period means moving the DB subnet group as well — one more reason to prefer Path A and to keep the interim period short.

There is no fourth path. If you cannot enumerate a bounded allowlist by any of the routes above, the data-first interim approach is not viable for your setup: switch to full_cutover and migrate the database and application in one window instead.

Step 3 — Apply the allowlist in Terraform, never by hand in the console

Make every interim change in the generated Terraform and commit it, not through the RDS or EC2 console:

• A console edit is invisible to code review, so nobody sees that a database port was opened.
• A console edit is silently reverted by the next terraform apply, so the exposure exists only in the running account and never in Git — you cannot audit when it opened or whether it closed.

In terraform/terraform.tfvars, set the interim variables the generator emits, then plan and apply:

Both variables default to closed ([] and false). interim_heroku_ingress_cidrs = [] emits no ingress rule at all, and the variable rejects 0.0.0.0/0.

Step 4 — Close the interim path at cutover

Once the application runs on AWS and no longer connects from Heroku:

1. Reset both variables to their defaults (interim_heroku_ingress_cidrs = [], interim_db_public_access = false), then terraform apply. Confirm the plan removes the ingress rule.
2. Delete the interim variables and the gated ingress block from the Terraform, and remove the static-egress add-on if you provisioned one for Path C.
3. Tear down the peering connection if you used Path A: heroku spaces:peerings:destroy <pcx_id> --space <space_name>.
4. Confirm the application reaches the database over private VPC networking only, and that the database reports Not publicly accessible. {{ENDIF}}

{{IF migration_method == “dms”}}

Alternative: AWS DMS Bulk Migration

For databases over ~10GB, AWS DMS can provide a faster migration with less downtime:

⚠️ Important limitation: AWS DMS cannot perform continuous replication (CDC) with Heroku Postgres. Heroku does not grant the REPLICATION role required for logical replication slots. DMS is for one-time bulk data migration with a final cutover window only.

DMS Setup Steps:

1. Create a DMS replication instance (publicly accessible, same VPC as target RDS)
2. Create source endpoint pointing to Heroku Postgres (SSL mode: require)
3. Create target endpoint pointing to your AWS RDS/Aurora instance
4. Copy schema first: pg_dump --schema-only from Heroku → pg_restore to target
5. Create migration task with:
   • Migration type: “Migrate existing data” (NOT “Replicate data changes”)
   • Target table prep mode: “Do nothing” (schema already copied)
   • LOB mode: “Full LOB mode”
6. Enable pre-migration assessment and review results
7. Start the migration task
8. After completion, perform final cutover using the Heroku CLI sequence below {{ENDIF}}

{{IF migration_method == “bucardo”}}

Alternative: Bucardo (Near-Zero Downtime)

For near-zero downtime migration using trigger-based replication:

Requirements:

• Dedicated EC2 instance (Ubuntu 20.04+) to run Bucardo
• PostgreSQL client matching source version
• Ability to create triggers on Heroku database
• Primary keys on all source tables

Setup overview: Bucardo performs an initial full copy, then switches to delta-push mode for continuous replication until cutover. See the detailed Bucardo setup procedure in your migration reference documentation.

Note: Bucardo does not support LOB migration. Stored functions/procedures must be migrated separately via pg_dump --schema-only. {{ENDIF}}

{{IF migration_method == “wal_g”}}

Alternative: WAL-G (Minimal Downtime for Large Databases)

For large databases requiring minimal downtime via WAL-based replication:

Requirements:

• Dedicated EC2 instance for WAL-G processing
• S3 bucket for WAL archive storage
• Network access between Heroku Postgres and your AWS infrastructure

Setup overview: WAL-G captures write-ahead logs from the source database and replays them on the target, allowing continuous catch-up with minimal final cutover window. See the detailed WAL-G setup procedure in your migration reference documentation. {{ENDIF}}

Heroku CLI Cutover Sequence

Regardless of migration method, the final cutover follows this sequence:

After full application migration to AWS (no longer on Heroku):

{{ENDIF}} {{IF has_redis}}

Redis Migration (Heroku Redis → ElastiCache)

Strategy: Export Redis data using DUMP/RESTORE or redis-cli --rdb depending on dataset size.

Pre-Migration Steps

1. Check current Redis memory usage and key count:

   bashCopy

   heroku redis:info -a {{app_name}}

2. Determine migration approach:

   • Small dataset (< 1 GB): Use key-by-key DUMP/RESTORE
   • Large dataset (≥ 1 GB): Use RDB snapshot transfer

Execute Migration (Small Dataset)

Or execute manually using redis-cli:

Execute Migration (Large Dataset)

Post-Migration Verification

{{ENDIF}} {{IF has_kafka}}

Kafka Migration (Heroku Kafka → Amazon MSK)

Strategy: Use MirrorMaker 2 or topic recreation with producer replay for migration.

Pre-Migration Steps

1. Document current topic configuration:

   bashCopy

   heroku kafka:topics -a {{app_name}}

2. Record consumer group offsets for replay:

   bashCopy

   heroku kafka:consumer-groups -a {{app_name}}

Execute Migration

Option A: Topic Recreation (recommended for most cases)

1. Create topics on MSK matching source configuration:

   bashCopy

   # For each topic, create with matching partitions and replication
   aws kafka create-topic \
     --cluster-arn {{MSK_CLUSTER_ARN}} \
     --topic-name {{TOPIC_NAME}} \
     --partitions {{PARTITION_COUNT}} \
     --replication-factor {{REPLICATION_FACTOR}}

2. Configure producers to write to MSK endpoint.

3. Replay historical data if needed using consumer offset reset.

Option B: MirrorMaker 2 (for zero-downtime with large backlogs)

Post-Migration Verification

{{ENDIF}}

Phase 3: Application Deployment

{{IF has_beanstalk}}

Deploy to Elastic Beanstalk

The generated EB path deploys a source bundle containing your Dockerfile. GitHub Actions is the default deploy mechanism; CodePipeline is available only when selected during Clarify.

{{IF eb_deploy_method == “github_actions”}}

GitHub Actions Deploy (Default)

The generated .github/workflows/deploy-eb.yml workflow uses GitHub OIDC role assumption, packages the source bundle, creates an Elastic Beanstalk application version, and updates each generated EB environment.

Before first run, create or provide a GitHub OIDC IAM role with permissions to call elasticbeanstalk create-storage-location, elasticbeanstalk create-application-version, elasticbeanstalk update-environment, and upload the source bundle to the EB storage bucket. Store the role ARN as the repository secret AWS_ROLE_ARN.

{{ENDIF}} {{IF eb_deploy_method == “codepipeline”}}

CodePipeline Deploy

The generated terraform/pipeline.tf creates an AWS-managed CodePipeline path from GitHub to Elastic Beanstalk. Complete the one-time GitHub connection authorization in the AWS console before expecting push-triggered deployments to run.

{{ENDIF}} {{IF eb_deploy_method == “manual”}}

Manual EB CLI Deploy

No automated deploy artifact was generated. Package and deploy manually:

{{ENDIF}}

EB Config Var Migration

Export all Heroku config vars and import sensitive values to AWS Secrets Manager or SSM Parameter Store. Reference secrets in EB via the environmentsecrets namespace configured in beanstalk.tf; set non-sensitive config directly as EB environment properties.

{{ENDIF}} {{IF has_fargate}}

Build and Push Container Image

Deploy to Fargate

The Terraform configuration creates ECS services automatically. After pushing the image, force a new deployment:

Fargate Config Var Migration

Export all Heroku config vars and import to AWS Secrets Manager / Parameter Store, then reference them in your ECS task definition.

ECS Express Mode (Forward-Look)

This generated path uses standard ECS/Fargate Terraform. If an ECS Express Mode path becomes available in this skill, treat it as an optional simplification for the Fargate override path, not as a replacement for the Elastic Beanstalk default without explicit user choice.

{{ENDIF}}

Phase 4: Verification

Health Checks

{{IF has_beanstalk}}

• Not done: Application responds on EB environment URL: http://{{EB_ENVIRONMENT_URL}}/ {{IF has_beanstalk_web}}
• Not done: Each customer-supplied eb_health_check_path_<app_sanitized>_web returns a successful response on its app’s EB environment URL {{ENDIF}} {{ENDIF}} {{IF has_fargate}}
• Not done: Application responds on ALB endpoint: https://{{ALB_DNS_NAME}}/
• Not done: Health check endpoint returns 200: https://{{ALB_DNS_NAME}}/health {{ENDIF}} {{IF has_postgres}}
• Not done: Database connectivity confirmed (application can read/write)
• Not done: Row counts match source database {{ENDIF}} {{IF has_redis}}
• Not done: Redis connectivity confirmed (application can read/write cache)
• Not done: Key counts match source Redis {{ENDIF}} {{IF has_kafka}}
• Not done: Kafka producers sending to MSK successfully
• Not done: Kafka consumers receiving from MSK successfully
• Not done: Topic/partition configuration matches source {{ENDIF}}

Functional Tests

• Not done: Run application test suite against AWS deployment
• Not done: Verify critical user flows end-to-end
• Not done: Check log output in CloudWatch Logs

Performance Baseline

• Not done: Response time within acceptable range (compare to Heroku baseline)
• Not done: No error rate increase in CloudWatch metrics
• Not done: Resource utilization (CPU/memory) within expected bounds

Phase 5: Cutover

DNS Cutover

1. Update DNS records to point at the active AWS endpoint:

{{IF has_beanstalk}}

{{ENDIF}} {{IF has_fargate}}

{{ENDIF}}

1. Set TTL low (60s) before cutover, restore after verification.

Decommission Heroku

After successful verification (recommend 48–72 hours of parallel running):

Post-Migration Lockdown

Once your application is fully running on AWS (no longer connecting from Heroku):

• Not done: Disable public access on RDS/Aurora: Confirm the database reports “Not publicly accessible”
• Not done: Restrict security groups: Ensure no 0.0.0.0/0 inbound rules remain; allow only VPC-internal traffic on database ports
• Not done: Verify backups: Confirm automated backups are enabled with appropriate retention
• Not done: Confirm private connectivity: Application connects to the database via private VPC networking (not public endpoint)

{{IF migration_approach == “interim_cutover_data_first”}}

• Not done: Close the interim access path in Terraform: reset interim_heroku_ingress_cidrs = [] and interim_db_public_access = false, terraform apply, then delete the interim ingress block — full procedure in “Interim Database Exposure” Step 4 above

{{ENDIF}}

Decommission Heroku Resources

After successful verification (recommend 48–72 hours of parallel running):

1. Scale Heroku dynos to 0:

   bashCopy

   heroku ps:scale web=0 worker=0 -a {{app_name}}

2. Disable Heroku maintenance mode (if still on):

   bashCopy

   heroku maintenance:off -a {{app_name}}

3. Remove add-ons and delete app when confident:

   bashCopy

   heroku addons:destroy --confirm {{app_name}} <addon_name>
   heroku apps:destroy --confirm {{app_name}}

{{IF deferred_addons.length > 0}}

Manual Migration Items

The following add-ons could not be automatically mapped to AWS equivalents and require manual migration:

{{FOR addon IN deferred_addons}} | {{addon.addon_name}} | {{addon.addon_plan}} | {{addon.provider}} | {{addon.reason}} | {{addon.recommendation}} | {{ENDFOR}}

Action Required

For each deferred add-on above:

1. Identify the equivalent AWS service or third-party replacement
2. Provision the replacement service manually
3. Migrate data/configuration from the Heroku add-on
4. Update application configuration to use the new service endpoint
5. Verify functionality before decommissioning the Heroku add-on

{{ENDIF}}

{{IF has_beanstalk_web}}

The generated per-app Elastic Beanstalk web variables have no defaults. A non-interactive plan fails and identifies any missing or invalid value.

{{ENDIF}}

3. Apply Terraform

4. Migrate Data

{{IF has_postgres}}

{{ENDIF}} {{IF has_redis}}

{{ENDIF}}

5. Deploy Application

{{IF has_beanstalk}} Deploy through the selected Elastic Beanstalk deploy method from MIGRATION_GUIDE.md Phase 3. The default is the generated GitHub Actions workflow. {{ENDIF}} {{IF has_fargate}} Build and push your container image, then update ECS services. See MIGRATION_GUIDE.md Phase 3 for details. {{ENDIF}}

6. Verify and Cutover

Follow the verification checklist in MIGRATION_GUIDE.md Phase 4, then perform DNS cutover per Phase 5.

Important Notes

• Placeholders: Connection strings and credentials use {{PLACEHOLDER}} format. Replace with actual values from Heroku credentials and Terraform outputs.
• Order matters: Apply Terraform BEFORE running data migration scripts. The target infrastructure must exist first.
• Backup: Always verify backups exist before performing destructive operations on Heroku.
• Parallel run: Recommended 48–72 hours of parallel running before decommissioning Heroku. {{IF deferred_addons.length > 0}}
• Manual items: {{deferred_addons.length}} add-on(s) require manual migration. See “Manual Migration Items” in MIGRATION_GUIDE.md. {{ENDIF}}

3B: Redis Migration Script

Trigger: has_redis == true

Write to $MIGRATION_DIR/scripts/migrate-redis.sh:

3C: No Kafka Migration Script

Kafka migration does NOT generate a standalone script because MirrorMaker 2 configuration is environment-specific and requires running infrastructure. The MIGRATION_GUIDE.md provides the procedure and configuration templates instead.

Step 4: Set Script Permissions

After writing scripts, ensure they are executable:

Step 5: Validate Generated Documentation

Verify all generated files:

1. MIGRATION_GUIDE.md exists and:

   • Contains “Prerequisites” section
   • Contains “Phase 1: Infrastructure Provisioning” section
   • If has_postgres: Contains “PostgreSQL Migration” subsection
   • If has_redis: Contains “Redis Migration” subsection
   • If has_kafka: Contains “Kafka Migration” subsection
   • If NOT has_postgres: Does NOT contain “PostgreSQL Migration” subsection
   • If NOT has_redis: Does NOT contain “Redis Migration” subsection
   • If NOT has_kafka: Does NOT contain “Kafka Migration” subsection
   • If has_postgres: Contains “Heroku CLI Cutover Sequence” subsection
   • If migration_method == "dms": Contains DMS limitation warning about CDC/continuous replication
   • If migration_approach == "interim_cutover_data_first": Contains “Interim Database Exposure” section whose Step 1 is the TLS prerequisite gate and whose Step 2 offers only bounded-allowlist connectivity paths
   • If migration_approach == "interim_cutover_data_first": Contains “Platform Risk Advisory” section
   • Does NOT instruct opening a database port (5432) to 0.0.0.0/0 anywhere — interim access must be a scoped CIDR allowlist applied through Terraform
   • If containerization_status != "containerized": Contains “Containerization Prerequisites” section
   • Contains “Post-Migration Lockdown” section
   • Contains “Config Var Migration” section
   • If has_beanstalk_web: Explains that each web app’s eb_application_port_<app>_web and eb_health_check_path_<app>_web are required before planning
   • If has_beanstalk: Contains selected EB deploy method instructions and the EB DNS cutover target, and emits no CodePipeline artifact unless eb_deploy_method is "codepipeline"
   • Does NOT hard-code a health check path for Elastic Beanstalk verification; use the applicable per-app eb_health_check_path_<app>_web instead
   • Contains “Verification” section with data-store-appropriate checks
   • If deferred_addons.length > 0: Contains “Manual Migration Items” section

2. README.md exists and:

   • Lists all artifact files present in $MIGRATION_DIR
   • Includes terraform apply command sequence
   • References correct target region
   • Includes estimated monthly cost

3. Scripts (if generated):

   • scripts/migrate-postgres.sh exists if has_postgres
   • scripts/migrate-redis.sh exists if has_redis
   • Scripts contain connection parameter placeholders (not real credentials)
   • Scripts are executable (chmod +x applied)

Error Handling