migration-apprunner-to-ecs-express

What this skill does

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 docs
- `mcp__plugin_aws-dev-toolkit_awsknowledge__aws___read_documentation` — read a doc page
- `mcp__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:

```json
{
  "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 `uv` installed (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) — `awsknowledge` and `awspricing` are bundled; `ecs-mcp` must 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 `awsknowledge` MCP 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. Co