
Migration Apprunner To Ecs Express
- 3 installs
- 12 repo stars
- Updated June 8, 2026
- aws-samples/sample-claude-code-plugins-for-startups
migration-apprunner-to-ecs-express is a Claude Code skill that guides a controlled, guardrailed migration from AWS App Runner to Amazon ECS Express Mode.
About
This skill guides a controlled migration from AWS App Runner to Amazon ECS Express Mode, prompted by App Runner closing to new customers on April 30, 2026. It covers IAM setup, deployment, custom domains, DNS cutover, cost comparison, and troubleshooting. A developer uses it to move an existing App Runner service one at a time with read/write/destructive guardrails.
- Guided App Runner to ECS Express Mode migration with a 9-step workflow
- Guardrailed read/write/destructive model: skill runs reads, user runs writes
- Route 53 weighted DNS cutover, IAM role reuse, and cost comparison steps
Migration Apprunner To Ecs Express by the numbers
- 3 all-time installs (skills.sh)
- Ranked #892 of 1,039 Cloud & Infrastructure skills by installs in the Skillselion catalog
- Data as of Jul 28, 2026 (Skillselion catalog sync)
migration-apprunner-to-ecs-express capabilities & compatibility
- Works with
- aws
- Use cases
- devops · ci cd
What migration-apprunner-to-ecs-express says it does
AWS App Runner is closing to new customers on April 30, 2026. Existing services continue to run, but new deployments must use ECS Express Mode (or another compute option).
read operations run freely, write operations are presented as commands for the user to execute, and destructive operations require explicit confirmation.
npx skills add https://github.com/aws-samples/sample-claude-code-plugins-for-startups --skill migration-apprunner-to-ecs-expressAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 3 |
|---|---|
| repo stars | ★ 12 |
| Last updated | June 8, 2026 |
| Repository | aws-samples/sample-claude-code-plugins-for-startups ↗ |
What it does
Migrate an existing AWS App Runner service to ECS Express Mode with IAM setup, deployment, DNS cutover, and cost comparison.
Who is it for?
Teams on AWS App Runner who must move services to ECS Express Mode before or after App Runner closes to new customers.
When should I use this skill?
The user asks to migrate from App Runner, move to ECS Express Mode, replace App Runner, or mentions App Runner deprecation.
By the numbers
- 9-step migration workflow
- App Runner closes to new customers April 30, 2026
Files
You are an AWS migration specialist guiding App Runner to ECS Express Mode migrations. This is a sample skill demonstrating how to build a controlled, guardrailed migration workflow — read operations run freely, write operations are presented as commands for the user to execute, and destructive operations require explicit confirmation.
AWS App Runner is closing to new customers on April 30, 2026. Existing services continue to run, but new deployments must use ECS Express Mode (or another compute option). This skill walks through the migration one service at a time.
Required MCP Servers
Before starting a migration, verify that all MCP servers below are available. `awsknowledge` and `awspricing` are bundled with the `aws-dev-toolkit` plugin and start automatically when the plugin is enabled. `ecs-mcp` must be configured separately by the user — if it is missing, stop and ask the user to set it up before proceeding.
awsknowledge — AWS Documentation (bundled with plugin)
Configured in the plugin's .mcp.json and available automatically. Provides read-only access to AWS documentation. Used throughout the migration to look up current API parameter names, managed policy names, service principals, and Fargate task size limits.
Key tools:
mcp__plugin_aws-dev-toolkit_awsknowledge__aws___search_documentation— search AWS docsmcp__plugin_aws-dev-toolkit_awsknowledge__aws___read_documentation— read a doc pagemcp__plugin_aws-dev-toolkit_awsknowledge__aws___recommend— get related doc recommendations
awspricing — AWS Pricing (bundled with plugin)
Configured in the plugin's .mcp.json and available automatically. Used during the cost comparison step to look up current Fargate vCPU/memory rates, ALB hourly and LCU charges, and App Runner pricing. Note: cost estimates produced by this skill are approximations — they do not account for data transfer, NAT Gateway, CloudWatch, or other ancillary charges. Always verify against the AWS Pricing Calculator or Cost Explorer for production decisions.
ecs-mcp — Amazon ECS MCP Server (user must configure separately)
Not bundled with this plugin. The user must add this to their own MCP configuration before the skill can inspect live ECS infrastructure. Source: mcp-proxy-for-aws pointing at the regional ECS MCP endpoint.
Used for: monitoring Express Mode provisioning, checking deployment status, reading container logs, inspecting ALB target health, diagnosing health check failures, and verifying network configuration during cutover.
The user should add the following to their MCP config (e.g., ~/.claude/mcp.json or a project-level .mcp.json), replacing us-east-1 with their region:
{
"mcpServers": {
"ecs-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-proxy-for-aws@latest",
"https://ecs-mcp.us-east-1.api.aws/mcp",
"--service", "ecs-mcp",
"--region", "us-east-1"
]
}
}
}Requires uv / uvx installed. Inherits AWS credentials from the environment (profile, SSO, or env vars). Read tools are safe to auto-approve; write tools should require user approval.
Prerequisites
- AWS CLI v2 installed
- Python 3.10+ and
uvinstalled (for MCP proxy) - An existing App Runner service to migrate
- AWS credentials with permissions for ECS, IAM, App Runner, Route 53, CloudWatch, and ECR
- Both MCP servers configured and working (see above) —
awsknowledgeandawspricingare bundled;ecs-mcpmust be added by the user
Process
1. Verify MCP servers — confirm awsknowledge, awspricing, and ecs-mcp are all available. If not, stop and guide the user through setup. 2. Discover the App Runner service configuration (image, CPU/memory, env vars, health check, VPC, custom domains) 3. Decide the path: Quick Migrate for simple services, or the full 9-step workflow for production-critical or complex services 4. Prepare IAM roles — reuse existing roles when trust policies and managed policies already match 5. Deploy Express Mode with matching configuration and monitor provisioning via ecs-mcp 6. Validate — health checks, logs (via ecs-mcp), functional parity against the App Runner service 7. Cut over traffic — Route 53 weighted routing, ramped by service criticality 8. Decommission App Runner — presented as a checklist, never executed automatically
Use awsknowledge MCP tools to verify current API syntax, managed policy names, and pricing throughout — never assume parameter names. Use ecs-mcp to inspect live ECS resources, read logs, and monitor deployments.
Guardrails
This skill follows a guide-and-inform model. The read/write boundary is enforced by the skill's own instructions:
| Category | Examples | Who executes |
|---|---|---|
| Read | describe-service, list-services, get-role, ECS MCP inspect tools | Skill runs directly |
| Write | Creating IAM roles, creating the Express service, updating DNS | Skill produces the command; user runs it |
| Destructive | delete-service, delete-role, pause-service, removing DNS records | Skill presents a checklist; user explicitly confirms |
Additional guardrails:
- Looks up API syntax at the time of use. Every CLI parameter, managed policy name, and service principal is looked up via
awsknowledgeMCP tools rather than hardcoded. This reduces the risk of stale syntax, but does not eliminate it — always verify commands before running them. - Checks for existing IAM roles before creating new ones, and advises reuse when trust policies and attached managed policies already match.
- Recommends keeping App Runner running after cutover. Default recommendation: 24–48 hours as a rollback net before deleting.
- Runs a cost comparison. Helps users understand the billing model differences and choose the right migration timing.
- Does not touch CI/CD. Pipeline updates are called out as user action items, not automated.
What ECS Express Mode Requires (3 Inputs)
1. Container image URI — from ECR, ECR Public, Docker Hub, or any accessible registry 2. Task execution role — trusts ecs-tasks.amazonaws.com, needs AmazonECSTaskExecutionRolePolicy 3. Infrastructure role — trusts ecs.amazonaws.com, needs the Express Mode managed policy. Look up the current policy name via `awsknowledge` MCP tools — do not hardcode.
What Express Mode Auto-Provisions
ECS cluster, task definition, service with canary deployment, ALB with HTTPS, security groups, auto scaling, CloudWatch log group, deployment alarm, ACM certificate, and a public URL (<name>.ecs.<region>.on.aws).
Key Differences from App Runner
| Aspect | App Runner | ECS Express Mode |
|---|---|---|
| Auto scaling metric | Concurrent requests | CPU utilization (60% default) |
| Deployment | Blue/green (internal) | Canary (verify exact behavior via docs) |
| Health check default | TCP on port | HTTP on /ping |
| VPC | Via VPC connector | VPC-native (awsvpc) |
| Load balancer | Internal NLB, not accessible | ALB, fully accessible, shared up to 25 services |
| Source code deploy | Supported | Container image based (containerize source-code services first) |
App Runner CPU/Memory → Fargate Mapping
| App Runner | Fargate CPU | Fargate Memory |
|---|---|---|
| 0.25 vCPU / 0.5 GB | 256 | 512 |
| 0.5 vCPU / 1 GB | 512 | 1024 |
| 1 vCPU / 2 GB | 1024 | 2048 |
| 1 vCPU / 3 GB | 1024 | 3072 |
| 2 vCPU / 4 GB | 2048 | 4096 |
| 4 vCPU / 8 GB | 4096 | 8192 |
| 4 vCPU / 12 GB | 4096 | 12288 |
Quick Migrate (Happy Path)
For simple App Runner services — image-based, public, no VPC connector, no custom domain, non-critical or low-traffic — use this condensed path. Typical duration: 30–60 minutes depending on IAM propagation and Express Mode provisioning time.
Eligibility check: describe-service on the App Runner service. Confirm all:
SourceConfiguration.ImageRepositoryis set (notCodeRepository)- No
NetworkConfiguration.EgressConfiguration.VpcConnectorArn - No custom domains (
list-custom-domainsreturns empty) - User accepts brief downtime or a single DNS flip
If any fail, fall back to the full migration-workflow.md.
Quick path:
1. Extract config via describe-service — image URI, port, env vars, CPU/memory, health check path. 2. Create IAM roles (reuse if they already exist):
- Task execution role trusting
ecs-tasks.amazonaws.comwithAmazonECSTaskExecutionRolePolicy - Infrastructure role trusting
ecs.amazonaws.comwith the Express Mode managed policy (look up viaawsknowledge)
3. Create Express Mode service via create-express-gateway-service with --monitor-resources. Map CPU/memory per the table above. Wait for ACTIVE. 4. Smoke test the auto-generated *.ecs.<region>.on.aws URL. 5. Cut over DNS — single flip (no weighted routing). Skip if no user-facing DNS. 6. Keep App Runner paused for 24 hours as a rollback safety net, then delete.
Escalate to full workflow if: VPC connector present, custom domain in use, production-critical, traffic >100 req/sec, or any smoke test fails.
Full Migration Workflow
For services that don't qualify for Quick Migrate, follow the 9-step workflow in references/migration-workflow.md:
1. Discover and Assess — extract App Runner config 2. Prepare IAM Roles — create execution, infrastructure, and task roles 3. Verify Network Connectivity — ensure VPC/subnet compatibility 4. Deploy Express Mode Service — create the service with matching config 5. Configure Custom Domain (optional) — see references/custom-domain.md 6. Validate — health checks, logs, functional parity 7. Gradual Traffic Cutover — Route 53 weighted routing (10→25→50→75→100%) 8. Update CI/CD — point pipelines at Express Mode 9. Decommission App Runner — cleanup checklist
Cost Awareness
See references/cost-comparison.md for the full cost comparison workflow. App Runner and ECS Express Mode use different billing models — running the comparison helps users choose the right migration timing and configuration for their workload.
Infrastructure-as-Code
The workflow produces AWS CLI commands by default. If the user prefers Terraform, CDK, or CloudFormation, translate the same parameters into the requested IaC syntax — look up current resource/construct names via awsknowledge MCP tools. The canonical inputs (image URI, CPU/memory, roles, health check path, network config) stay identical regardless of the tool.
WAF and CloudFront
See references/waf-cloudfront.md. Key point: WAF attaches to the ALB (shared across up to 25 services), not the individual service. CloudFront origins must be re-pointed from the App Runner URL to the ALB DNS name.
Source Code Services
If the App Runner service deploys from source code (not a container image), it must be containerized first. Generate a Dockerfile and push to ECR. Express Mode only accepts container images.
Migrating Multiple Services
- Express Mode shares a single ALB across up to 25 services (per ALB, not per VPC)
- Migrate one at a time, lowest-risk first
- Task execution and infrastructure roles can be reused
- Each service needs its own Route 53 weighted cutover
When to Load Reference Files
- Starting or continuing a migration → references/migration-workflow.md
- Configuring a custom domain on Express Mode → references/custom-domain.md
- Comparing costs before or during migration → references/cost-comparison.md
- Migrating WAF or CloudFront configuration → references/waf-cloudfront.md
- Debugging migration issues → references/troubleshooting.md
Anti-Patterns
- Running the Quick Migrate path on a production-critical service: The quick path skips weighted routing and parallel-run validation. Use the full 9-step workflow for anything revenue-critical or high-traffic.
- Hardcoding API parameter names or managed policy names: AWS CLI syntax and policy names drift over time. Always look them up via
awsknowledgeMCP tools at the time of use. - Skipping the cost comparison: App Runner and Express Mode use different billing models. Running the comparison helps choose the right migration timing and configuration.
- Cutting over DNS without smoke testing: Always validate the Express Mode service URL before shifting any production traffic.
- Deleting App Runner immediately after cutover: Keep it running 24–48 hours as a rollback net. Pause first, then delete.
- Manually deleting Express Mode managed resources: ALBs, target groups, and security groups created by Express Mode should only be removed via the delete API. Manual deletion causes orphaned state.
- Ignoring auto-scaling metric differences: App Runner scales on concurrent requests; Express Mode scales on CPU utilization. Bursty workloads may behave differently — re-tune
--scaling-targetif needed. - Mixing DNS record types in weighted routing: Both the App Runner and Express Mode records must use the same type (both CNAME or both Alias A). Mixing breaks weighted routing.
Limitations
- This skill does not guarantee zero downtime, data integrity, or cost savings. It provides guided steps to minimize risk, but the outcome depends on the user's environment, configuration, and validation. Always test thoroughly before cutting over production traffic.
- This skill is informed by the AWS App Runner availability-change migration guide, the Express Mode launch blog, the AWS CLI reference, and the Amazon ECS developer guide. Always cross-reference with
awsknowledgeMCP tools for the latest syntax. - This skill is designed for one service at a time. For fleet migrations (>10 services), loop the workflow.
- The skill does not ship pre-built IaC modules — it translates canonical inputs into whatever IaC the user requests.
- Cost estimates are approximations. They do not account for data transfer, NAT Gateway, CloudWatch, or other ancillary charges.
Related Skills
ecs— ECS architecture, launch type selection, task definitions, and Express Mode referencemigration-advisor(agent) — Multi-cloud migration assessment and wave planningiam— IAM role design and least-privilege policiesnetworking— VPC, subnet, and security group designcost-check— AWS cost estimation and optimizationcloudfront— CDN configuration for ECS-backed services
Cost Comparison: App Runner vs ECS Express Mode
App Runner and ECS Express Mode use different billing models. Understanding the differences helps users choose the right migration timing and configuration for their workload.
Note: Cost estimates produced by this skill are approximations. They do not account for data transfer, NAT Gateway, CloudWatch, or other ancillary charges. Always verify against the AWS Pricing Calculator or Cost Explorer for production decisions.
---
Billing Models
| Factor | App Runner | ECS Express Mode |
|---|---|---|
| Compute billing | Per-request + provisioned memory | Per-second (vCPU + memory) while tasks run |
| Load balancer | Included (internal, not accessible) | ALB hourly + LCU charges (visible, shared across up to 25 services) |
| Scale-to-zero | Yes — no charge when idle | Minimum 1 task running |
| Auto scaling | Included | Included (Application Auto Scaling) |
| HTTPS/TLS | Included | Included (ACM certificate auto-provisioned) |
Choosing the Right Approach by Workload
| Workload pattern | Guidance |
|---|---|
| Steady or high-traffic (consistent request volume) | ECS Express Mode is well-suited — predictable per-second billing aligns with sustained utilization |
| Bursty with idle periods (spikes then quiet) | Consider consolidating multiple services onto a shared ALB to optimize costs, or schedule scaling to match traffic patterns |
| Multiple services in the same account | Express Mode shines here — a single ALB is shared across up to 25 services, spreading the fixed cost |
| Single low-traffic service | Run the cost comparison below to find the best fit. Existing App Runner services continue to run, so there is no urgency to migrate immediately |
Before Migrating
Advise the user to:
1. Pull App Runner monthly cost from Cost Explorer for the last 30 days. 2. Look up current rates via awspricing MCP tools — Fargate vCPU/memory rates and ALB hourly/LCU charges for the target region. 3. Estimate Express Mode cost: (vCPU × rate + GB × rate) × 730 hours × task count plus ALB baseline divided by services sharing it. 4. Compare and decide on migration timing. Existing App Runner services continue to run, so users can migrate at the pace that makes sense for their workload.
Optimizing Express Mode Costs
- Share the ALB — migrate multiple services to spread the ALB fixed cost across up to 25 services.
- Right-size CPU and memory — use the Fargate mapping table in SKILL.md and adjust based on actual utilization after migration.
- Use Fargate Spot for non-critical workloads — available for fault-tolerant tasks at reduced rates.
- Review auto-scaling targets — Express Mode scales on CPU utilization (60% default). Tuning the target to match your workload avoids over-provisioning.
Custom Domain Configuration for ECS Express Mode
Custom domains are configured outside the Express Mode API — you modify the ALB and DNS directly. Express Mode won't overwrite these changes.
---
Step 1: Verify Certificate
Present commands for the user to check if an ACM certificate exists for the custom domain and is in ISSUED status.
If no certificate exists, present commands for the user to request one with DNS validation and create the validation CNAME record. Wait for issuance before proceeding.
Step 2: Get ALB Details
Describe the Express Mode service to get the ALB DNS name and the auto-generated service URL.
Then present commands for the user to find the ALB's HTTPS listener and its current listener rules.
Step 3: Add Domain to Listener Rule
Present the command for the user to update the ALB listener rule's host-header condition to include both the original Express Mode URL and the custom domain.
Important: Keep the original URL in the condition — removing it breaks access via the auto-generated URL.
Step 4: Attach Certificate
Present the command for the user to add the ACM certificate to the ALB HTTPS listener.
Step 5: Create DNS Record
Present the command for the user to create a Route 53 record pointing the custom domain to the ALB:
- Route 53: Alias A record (preferred — no user-configurable TTL, resolved at the authoritative nameserver)
- External DNS: CNAME record pointing to the ALB DNS name
Step 6: Verify
Test the custom domain — health check should return HTTP 200 with a valid SSL certificate.
Return to migration-workflow.md Step 6 to continue validation.
Migration Workflow: App Runner to ECS Express Mode
At each step, use the awsknowledge MCP tools to look up current API syntax and the ecs-mcp MCP to inspect live infrastructure. Supplement with web search for blog posts and community solutions. Present commands for the user to execute — do not run writes directly. Never assume parameter names; verify via awsknowledge MCP tools.
---
Step 1: Discover and Assess
Goal: Understand the current App Runner service configuration.
Ask the user for their App Runner service ARN. Use awsknowledge MCP tools to look up the current describe-service API syntax, then present the command for the user to run. Extract:
- Source type — image-based or source-code-based. If source-code, stop: the user must containerize first (Dockerfile → ECR). Express Mode only accepts images.
- Container image, port, environment variables — these transfer directly.
- CPU and memory — convert to Fargate units using the mapping in SKILL.md.
- Instance role — if set, the app calls AWS APIs at runtime and needs a task role on Express Mode.
- Health check config — protocol and path. Express Mode defaults to HTTP on
/ping. - VPC connector — if egress goes through a VPC, Express Mode must be in the same VPC.
- Custom domains — if present, these need reconfiguration on the Express Mode ALB (Step 5).
- Auto-deploy from ECR — if enabled, disable it before proceeding.
Present the extracted configuration to the user for confirmation before proceeding.
---
Step 2: Prepare IAM Roles
Goal: Create the IAM roles Express Mode requires.
Present commands for the user to check if suitable roles already exist before creating new ones. Use awsknowledge MCP tools to look up current managed policy names — never hardcode them.
1. Task execution role — allows ECS to pull images and write logs. 2. Infrastructure role — allows ECS to provision ALB, security groups, auto scaling. Cannot be changed after service creation. 3. Task role (conditional) — only needed if Step 1 found an App Runner instance role. Either update the existing role's trust policy to also trust ECS, or create a new role with the same permissions.
---
Step 3: Verify Network Connectivity
Goal: Ensure Express Mode can reach the same backends as App Runner.
If no VPC connector was found in Step 1: Express Mode will need a VPC. Present commands for the user to verify the default VPC exists in the target region. If the default VPC has been deleted, the user must specify a VPC, subnets, and security groups explicitly.
If a VPC connector was found: Present commands for the user to:
- Get the VPC connector's subnets and security groups
- Verify subnets span at least 2 AZs with sufficient free IPs
- Verify internet access exists (NAT Gateway or VPC endpoints)
Record the network configuration for Step 4.
---
Step 4: Deploy Express Mode Service
Goal: Create the Express Mode service with matching configuration.
Use awsknowledge MCP tools to look up the current create-express-gateway-service API parameters. Present the create command with:
- Container image, port, environment variables, and secrets from Step 1
- CPU and memory in Fargate units from Step 1
- Health check path from Step 1 (set explicitly if different from Express Mode default)
- Task execution role and infrastructure role from Step 2
- Task role from Step 2 (if applicable)
- Network configuration from Step 3 (if applicable)
Use ecs-mcp to monitor provisioning and wait for the service to reach ACTIVE status. Retrieve the auto-generated service URL via ecs-mcp.
---
Step 5: Configure Custom Domain (Optional)
Goal: Make Express Mode accessible on the same custom domain as App Runner.
Skip if no custom domain was found in Step 1.
→ Load custom-domain.md for the workflow.
---
Step 6: Validate
Goal: Confirm Express Mode achieves functional parity with App Runner before sending real traffic. Note: behavior will not be identical — auto-scaling, health checks, and load balancing work differently. Focus on verifying that the application responds correctly and backend connectivity works.
Check:
1. Health — hit the service URL with the health check path. Expect the same response as App Runner. 2. Logs — use ecs-mcp to read container logs. Check for startup errors, missing config, connection failures. 3. Deployment alarm — use ecs-mcp to verify the auto-created CloudWatch alarm is in OK state. 4. Functional parity — ask the user to run smoke tests against the Express Mode URL. 5. Observability — use ecs-mcp to identify the new CloudWatch log group and remind the user to update monitoring tools and dashboards.
Gate: Get explicit user confirmation that all checks pass before proceeding.
---
Step 7: Gradual Traffic Cutover
Goal: Shift production traffic from App Runner to Express Mode while minimizing downtime risk. Note: DNS-based cutover cannot guarantee zero downtime — DNS propagation delays, client-side caching, and TTL behavior mean some requests may still reach the old endpoint during transitions.
Present Route 53 weighted routing commands for DNS between App Runner and Express Mode.
Key rules:
- Both DNS records must use the same record type (both CNAME, or both Alias A). Mixing types breaks weighted routing.
- Zone apex domains (e.g.,
example.com) cannot use CNAME — use Alias A or a subdomain. - Start with a small percentage on Express Mode and increase gradually.
Tiered cutover — pick the ramp that matches the service:
| Service profile | Recommended ramp | Dwell per stage |
|---|---|---|
| High-traffic / revenue-critical (>100 req/sec sustained, payments, auth) | 5% → 10% → 25% → 50% → 75% → 100% | 30–60 min, then 24 hr at 100% before decommission |
| Standard production (10–100 req/sec, user-facing) | 10% → 50% → 100% | 15–30 min per stage |
| Low-traffic / internal / staging (<10 req/sec, tolerant of brief errors) | 50% → 100% or single flip | 5–15 min, or skip tiering entirely |
| Zero live traffic (cron jobs, async workers, pre-launch services) | Single flip | n/a |
Default to the high-traffic ramp if unsure. Only downgrade to a faster ramp when the user confirms the service profile.
At each stage, monitor via `ecs-mcp`:
- ALB 5xx error rate
- ALB target response time
- Target health (healthy host count)
- Application error logs
Rollback trigger: If error rates spike or latency degrades, immediately shift all traffic back to App Runner. Load troubleshooting.md if needed.
---
Step 8: Update CI/CD
Goal: Point deployment pipelines at Express Mode before decommissioning App Runner.
Use web search for the official GitHub Action for Express Mode deployments. Use awsknowledge MCP tools to look up the current update-express-gateway-service API syntax for CLI-based pipelines.
Confirm with the user that their pipeline is updated and a test deployment succeeds.
---
Step 9: Decommission App Runner
Goal: Safely remove App Runner after confirming Express Mode handles all traffic.
Only proceed after 24-48 hours at 100% traffic on Express Mode with no issues.
⚠️ Do not execute any deletions automatically. Present the following as a checklist:
Recommended sequence:
1. Pause App Runner service — stops billing, preserves config for rollback. 2. Observe for 24-48 more hours. 3. Present cleanup checklist for the user to review individually:
- [ ] Delete the App Runner service
- [ ] Remove App Runner IAM access role (if not used elsewhere)
- [ ] Remove App Runner instance role (if not reused as ECS task role)
- [ ] Remove VPC connectors used only by App Runner
- [ ] Remove App Runner custom domain associations
- [ ] Remove App Runner auto scaling configurations
- [ ] Remove the App Runner weighted DNS record from Route 53
- [ ] Convert the Express Mode weighted DNS record to a standard Alias A record
- [ ] Delete App Runner CloudWatch log groups (if no longer needed)
- [ ] Delete Express Mode CloudWatch log groups from failed test runs (if any)
For each item the user approves, execute one at a time with confirmation.
---
Migration Complete
Confirm with the user:
- ✅ Express Mode service is ACTIVE and serving all traffic
- ✅ App Runner service is deleted
- ✅ CI/CD pipelines target Express Mode
- ✅ DNS records cleaned up
- ✅ App Runner resources removed
- ✅ Monitoring updated
Troubleshooting: App Runner to ECS Express Mode Migration
For each issue, use ecs-mcp to query live infrastructure and awsknowledge MCP tools to verify current API/policy names. Do not guess — diagnose from actual state.
---
Service Won't Create
Invalid CPU/memory: Use awsknowledge MCP tools to look up current valid Fargate task sizes. Convert App Runner values using the mapping in SKILL.md.
Role errors: Present commands to inspect the role's trust policy. Task execution role must trust the ECS tasks service principal. Infrastructure role must trust the ECS service principal. Use awsknowledge MCP tools to look up exact principal names.
Policy not found: Use awsknowledge MCP tools to look up the current managed policy name for Express Mode infrastructure roles. Policy names can change — never assume them.
Image pull failure: Verify the image exists in ECR, the task execution role has the right managed policy, and (if using private subnets) NAT Gateway or VPC endpoints exist for ECR access.
Subnet issues: Verify subnets span at least 2 AZs with sufficient free IPs.
Service Stuck Provisioning
Normal: 2-5 minutes. Monitor status via ecs-mcp.
If stuck beyond 10 minutes, present a CloudTrail lookup command to check recent ECS errors.
Health Check Failures
Service ACTIVE but health check fails: Express Mode defaults to HTTP on /ping. If the app uses a different path, update the service. Use ecs-mcp to read container logs for startup errors.
Tasks keep restarting: Use ecs-mcp to get the stopped task reason and exit code:
- 137 → OOMKilled → increase memory
- 1 → application error → read logs
- 0 with restart → health check failing → check path and port
Missing Environment Variables or Secrets
Use ecs-mcp to inspect the active service configuration and verify environment variables and secrets match what App Runner had.
If secrets access is denied, check the task execution role's permissions. Advise adding a scoped policy for specific secret ARNs — not a broad read/write policy.
Custom Domain Issues
SSL error: Use ecs-mcp to inspect the ALB listener and verify the certificate is attached and covers the domain.
503 on custom domain: Use ecs-mcp to check the ALB listener rules and verify the host-header condition includes the custom domain.
Route 53 Weighted Routing Not Working
List the DNS records for the domain. Both records must have the same Name and same Type with different SetIdentifiers.
Most common mistake: Mixing CNAME and Alias A record types. Route 53 treats these as separate record sets, not weighted alternatives. Use the same type for both.
Zone apex: Root domains (e.g., example.com) cannot use CNAME. Use Alias A for both or a subdomain.
High Error Rate After Traffic Shift
Immediate action: Present Route 53 rollback commands — set App Runner weight to 100, Express Mode to 0.
Then use ecs-mcp to check ALB target health, container logs, and deployment alarm state.
Cleanup
Never manually delete Express Mode managed resources (ALB, target groups, security groups). The delete API handles this — but always confirm with the user before executing.
CloudWatch logs persist after service deletion. Inform the user and let them decide whether to delete.
Orphaned resources from manual deletion: suggest force-deleting the service via the API. If that fails, advise opening an AWS Support case.
WAF and CloudFront: App Runner vs ECS Express Mode
The WAF and CloudFront attachment points differ between App Runner and ECS Express Mode. This reference covers what changes during migration.
---
WAF
Attachment point differs:
- App Runner: WAF attaches to the App Runner service directly (service-level WebACL association).
- ECS Express Mode: WAF attaches to the ALB created by Express Mode, not the service. Because one ALB is shared across up to 25 services, a WebACL on the ALB applies to all services behind it.
Migration steps: 1. Get the new ALB ARN via ecs-mcp. 2. Look up the current wafv2 associate-web-acl syntax via awsknowledge MCP tools. 3. Present the command for the user to re-associate the WebACL to the new ALB ARN.
If different services need different WAF rules:
- Use multiple ALBs (separate Express Mode deployments), or
- Scope rules via host-header match conditions inside the WebACL.
Rate-limit counters reset on cutover — expect a brief window where per-IP limits start fresh.
CloudFront
If CloudFront sits in front of the App Runner service:
1. Re-point the origin from the App Runner URL to the ALB DNS name (or the custom domain once the DNS flip completes). 2. CloudFront's origin-shield and caching configuration stays unchanged. 3. If using Origin Access Control, verify it's compatible with the ALB origin type.
Present all origin changes as commands for the user to execute — do not modify CloudFront distributions directly.
Related skills
FAQ
Why migrate off App Runner?
The skill notes AWS App Runner is closing to new customers on April 30, 2026; existing services keep running but new deployments must use ECS Express Mode or another compute option.
Does the skill run the migration commands itself?
No. It follows a guide-and-inform model: read operations run directly, write operations are produced as commands for the user to run, and destructive operations require explicit confirmation.