dotnet-aws-ecs

name	dotnet-aws-ecs
description	Generates IaC (CloudFormation or CDK) and a deployment guide to deploy a .NET workload to Amazon ECS Fargate on Linux containers with an Application Load Balancer. Produces a VPC, ECS cluster, task definition, ALB, and auto-scaling. NOT for Windows containers, EC2 launch type, or Kubernetes/EKS deployments.
version	1
allowed-tools	["Read","Write","Shell"]

Deploy .NET Workload to AWS ECS Fargate

When to Use This Skill

Use this skill when:

• A .NET application (Web API, ASP.NET Core MVC/Razor, Blazor Server) is running locally and ready for cloud deployment
• The developer wants to deploy to ECS Fargate (serverless containers) on AWS
• The developer wants IaC that provisions everything in a single stack

Do NOT use this skill for:

• Applications that aren't yet running locally
• Windows container deployments
• EC2 launch type deployments
• Kubernetes/EKS deployments
• Serverless (Lambda) deployments

Objective

Produce IaC (CloudFormation or CDK — user chooses) and a step-by-step deployment guide. The output provisions:

• VPC with public and private subnets (2 AZs) — or uses an existing VPC and subnets provided by the user
• Application Load Balancer (internet-facing or internal)
• ECS Cluster with Fargate service (2 tasks)
• ECR repository for the container image
• IAM roles (task execution + task role)
• Auto-scaling (CPU-based target tracking)
• CloudWatch log group

Keep it focused on compute and networking. No databases, caches, or auth services.

Recommended MCP Server

This skill works best when the AWS Knowledge MCP server is configured. It provides access to up-to-date AWS documentation for ECS, CloudFormation, CDK, and related services.

• URL: https://knowledge-mcp.global.api.aws
• Usage: When generating IaC or resolving deployment issues, use the AWS Knowledge MCP to look up current resource property schemas, valid parameter values, and best practices (e.g., search_documentation for ECS task definition properties, Fargate platform versions, ALB listener rules, or CDK construct APIs).

If the MCP is not configured, the skill will still work using embedded guidance in the reference files, but results may not reflect the latest AWS service changes.

Phases

Phase 0 — Gather Information

Before generating anything, determine:

1. Application details — find the web project, read .csproj for TargetFramework, check Program.cs for health check path
2. Container port — check ASPNETCORE_URLS, launchSettings.json, or default (8080 for .NET 8+, 5000 for earlier)
3. Existing Dockerfile — if one exists alongside the project, use it; otherwise generate one in Phase 2

Ask the Developer

• IaC format: "Do you prefer CloudFormation (YAML) or CDK (C#)?"
• VPC selection: "Would you like to deploy into a new VPC (default) or an existing VPC?"
  • If the user chooses existing VPC, ask for the VPC ID and subnet IDs (2 public, 2 private).
  • Optionally, if the AWS CLI is available and an AWS profile is configured, offer to retrieve the list of existing VPCs and their subnets by running:

    aws ec2 describe-vpcs --query "Vpcs[*].{VpcId:VpcId,Name:Tags[?Key=='Name']|[0].Value,CidrBlock:CidrBlock}" --output table
    

    Then, once the user selects a VPC:

    aws ec2 describe-subnets --filters "Name=vpc-id,Values=<vpc-id>" --query "Subnets[*].{SubnetId:SubnetId,AZ:AvailabilityZone,CidrBlock:CidrBlock,Name:Tags[?Key=='Name']|[0].Value,Public:MapPublicIpOnLaunch}" --output table
    

    Important: Always ask for user approval before running any AWS CLI commands.
• ALB scheme: "Should the load balancer be internet-facing or internal?"
• Container health check: "By default, the chiseled (minimal) Docker image is used for security. This means the ECS console will show container health as 'Unknown' since chiseled images have no shell or curl — the ALB health check still protects against unhealthy tasks. Would you like to enable the ECS container health check instead? This requires switching to a non-chiseled image (larger, but gives explicit 'Healthy' status in the ECS console)."
  • If the user chooses container health check: use the non-chiseled runtime image (-noble) in the Dockerfile and add a HealthCheck block to the task definition container. See references/cloudformation-template-guide.md § "Container Health Check" and references/dockerfile-guide.md § "Non-Chiseled Alternative".
  • If the user declines (default): use the chiseled image and do not add a container-level health check. After deployment, inform the user that "Unknown" container health in the ECS console is expected.

Phase 1 — Generate IaC

Generate the ECS Fargate infrastructure based on the user's IaC choice.

Read references/cloudformation-template-guide.md for CloudFormation structure, or references/cdk-template-guide.md for CDK structure.

New VPC (default)

Both formats must include:

• VPC, subnets (2 public, 2 private), Internet Gateway, NAT Gateways, route tables
• ALB security group, ECS task security group
• Application Load Balancer (scheme per user choice), target group, HTTP listener
• ECR repository
• ECS cluster, task definition (Fargate, Linux, 256 CPU / 512 MiB), service (2 tasks)
• IAM roles: ECS Task Execution Role, ECS Task Role
• Auto-scaling: target tracking on CPU at 70%
• CloudWatch log group

Existing VPC

When the user opts to deploy into an existing VPC, the template must:

• Accept VPC ID and subnet IDs as parameters (no VPC/subnet/gateway/route resources are created)
• Still create all security groups, ALB, ECS, ECR, IAM, auto-scaling, and log group resources
• Reference the provided VPC/subnet IDs wherever the new-VPC template would reference !Ref VPC or !Ref PublicSubnet1, etc.

See the "Existing VPC Mode" sections in references/cloudformation-template-guide.md and references/cdk-template-guide.md for implementation details.

Output Location

• CloudFormation: <project-root>/infra/ecs-fargate.yaml
• CDK: <project-root>/infra/EcsFargate.Cdk/

Phase 2 — Generate Dockerfile

If the application doesn't already have a Dockerfile, generate one.

Read references/dockerfile-guide.md for the patterns.

Key points:

• Multi-stage build (SDK → chiseled-ubuntu runtime)
• Match base image to TargetFramework
• Expose the correct port
• Run as non-root user via $APP_UID (chiseled images have no shell/adduser)
• Place alongside the web project (same directory as the .csproj)
• Place .dockerignore at the Docker build context root, not inside the web project folder

Phase 2.5 — Validate Docker Build Locally

After generating the Dockerfile, validate the Docker image builds successfully.

Read references/dockerfile-guide.md § "Local Validation" for the procedure.

Key points:

• Check if Docker is installed locally; if not, skip validation and add a manual validation section to the deployment guide
• Run docker build from the build context root
• Run the container briefly to confirm the runtime starts (expect DB connection errors if no database is available — that's OK)
• Clean up all test containers and images after validation
• If the build fails, fix the Dockerfile and retry before proceeding

Phase 3 — Generate Deployment Guide

Produce a markdown deployment guide with step-by-step CLI commands.

Read references/deployment-guide-template.md for the structure.

The guide must cover:

1. Prerequisites (AWS CLI, Docker)
2. Deploy the infrastructure stack
3. Build and push the container image to ECR
4. Update the ECS service to pull the new image
5. Verify deployment (ALB URL, ECS service status, logs)
6. Cleanup (delete stack, delete ECR images)
7. Cost estimation
8. Next steps (HTTPS, custom domain, CI/CD)

Output Location

<project-root>/infra/DEPLOYMENT.md

Constraints

• Single stack — not multiple stacks or nested stacks
• Use !Sub with ${EnvironmentName} prefix for resource names (CloudFormation) or equivalent parameterization (CDK)
• All ECS tasks in private subnets, ALB in public subnets
• Default to 256 CPU / 512 MiB for dev — add comments noting production sizing
• 2 desired tasks with deployment circuit breaker enabled
• Do NOT include databases, caches, queues, or auth services
• Do NOT hardcode account IDs or regions
• Dockerfile lives alongside the .csproj (application source), NOT in the infra/ folder

Output Structure

<project-root>/
├── infra/
│   ├── ecs-fargate.yaml              # CloudFormation template (if chosen)
│   ├── EcsFargate.Cdk/               # CDK project (if chosen)
│   └── DEPLOYMENT.md                 # Step-by-step deployment guide
├── <WebProject>/
│   └── Dockerfile                    # If not already present (alongside .csproj)

Reporting

After generation, summarize:

• What the stack provisions
• IaC format chosen
• VPC mode (new VPC or existing VPC with ID)
• ALB scheme (internet-facing or internal)
• Estimated monthly cost (dev environment)
• Any manual steps required
• Suggested next steps