Deploying Windows Containers on Amazon ECS (Step-by-Step Guide)

Emmanuel Odhiambo

4 min read

·

Sep 25, 2026

--

Listen

Share

Press enter or click to view image in full size

Running Windows workloads in containers is still a real requirement for many teams — whether it’s legacy .NET Framework apps, Windows services, or IIS-based workloads.
Amazon ECS makes this possible without Kubernetes complexity, while still giving you scaling, security, and AWS-native integrations.

In this guide, you’ll learn how to deploy a Windows container on Amazon ECS using EC2 launch type, entirely from the AWS Console, and optionally via CloudFormation.

What You’ll Build

By the end of this tutorial, you’ll have:

• A Windows-compatible ECS cluster
• An EC2 instance running Windows Server + ECS Agent
• A Windows container deployed as an ECS Service
• Logs flowing to CloudWatch
• Infrastructure deployable via CloudFormation

When Should You Use Windows Containers on ECS?

This approach is ideal when:

• You run .NET Framework (not .NET Core)
• You rely on IIS or Windows services
• You need Windows-specific libraries or COM objects
• You want ECS simplicity without managing Kubernetes

Important: Windows containers are supported on ECS EC2, not Fargate.

Architecture Overview

High-level flow:

User → ECS Service → Windows EC2 Instance → Windows Container → CloudWatch Logs

Press enter or click to view image in full size

Prerequisites

Before starting, make sure you have:

• An AWS account
• Docker installed locally (Windows)
• A basic Windows container image (IIS example works well)

STEP 1 — Create an ECS Cluster (EC2 Launch Type)

1. Open AWS Console → ECS
2. Click Clusters → Create cluster
3. Choose EC2
4. Configure:

• Cluster name: windows-ecs-cluster

5. Click Create

Press enter or click to view image in full size

STEP 2 — Create an IAM Role for ECS Instances

1. Go to IAM → Roles → Create role
2. Choose AWS service → Elastic Container Service
3. Select EC2 Role for ECS
4. Attach:

• AmazonEC2ContainerServiceforEC2Role
• CloudWatchLogsFullAccess

5. Role name:

• ecsWindowsInstanceRole

6. Click Create role

Press enter or click to view image in full size

STEP 3 — Launch a Windows ECS-Optimized EC2 Instance

1. Go to EC2 → Launch Instance
2. Search AMIs for:

• Windows Server 2019/2022 ECS Optimized

3. Instance type:

• t3.large (minimum recommended)

4. IAM Role:

• ecsWindowsInstanceRole

5. User data:

• [Environment]::SetEnvironmentVariable("ECS_CLUSTER", "windows-ecs-cluster", "Machine") Restart-Service ecs

6. Launch instance

Press enter or click to view image in full size

STEP 4 — Create an ECR Repository for Windows Image

1. Go to ECR → Create repository
2. Name:

• windows-app

3. Visibility:

• Private

4. Click Create repository

Press enter or click to view image in full size

STEP 5 — Build and Push a Windows Container Image

Dockerfile (IIS):

FROM mcr.microsoft.com/windows/servercore/iis
RUN echo "Hello from Windows ECS" > C:\inetpub\wwwroot\index.html

Push to ECR:

docker build -t windows-app .
docker tag windows-app:latest <account-id>.dkr.ecr.<region>.amazonaws.com/windows-app:latest
docker push <repo-uri>:latest

STEP 6 — Create a Windows Task Definition

1. Go to ECS → Task Definitions → Create
2. Launch type:

• EC2

3. OS:

• Windows

4. Task name:

• windows-task

5. Add container:

• Name: iis
• Image: ECR image URI
• Port mapping: 80

6. Logging:

• Enable CloudWatch Logs
• Log group: /ecs/windows-task

7. Click Create

Press enter or click to view image in full size

STEP 7 — Create an ECS Service

1. Go to ECS → Clusters → windows-ecs-cluster
2. Click Create Service
3. Configure:

• Launch type: EC2
• Task definition: windows-task
• Service name: windows-service
• Desired tasks: 1

4. Networking:

• Use default VPC

5. Click Create Service

STEP 8 — Verify Deployment

1. Go to ECS → Tasks
2. Confirm task is RUNNING
3. Open EC2 Public IP in browser
4. You should see:

• Hello from Windows ECS

Press enter or click to view image in full size

CloudFormation Template

This template creates:

• ECS Cluster
• IAM Role
• Windows ECS EC2 Instance

AWSTemplateFormatVersion: '2010-09-09'
Description: Windows Containers on Amazon ECS (EC2)

Resources:
  ECSCluster:
    Type: AWS::ECS::Cluster
    Properties:
      ClusterName: windows-ecs-cluster
  ECSInstanceRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: ec2.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AmazonEC2ContainerServiceforEC2Role
        - arn:aws:iam::aws:policy/CloudWatchLogsFullAccess
  ECSInstanceProfile:
    Type: AWS::IAM::InstanceProfile
    Properties:
      Roles:
        - !Ref ECSInstanceRole
  ECSWindowsInstance:
    Type: AWS::EC2::Instance
    Properties:
      InstanceType: t3.large
      IamInstanceProfile: !Ref ECSInstanceProfile
      ImageId: ami-xxxxxxxx # Windows ECS Optimized AMI
      UserData:
        Fn::Base64: !Sub |
          <powershell>
          [Environment]::SetEnvironmentVariable("ECS_CLUSTER","windows-ecs-cluster","Machine")
          Restart-Service ecs
          </powershell>
Outputs:
  ClusterName:
    Value: !Ref ECSCluster

Best Practices for Windows Containers on ECS

• Use larger instance types
• Avoid frequent container restarts
• Monitor memory usage carefully
• Prefer long-running services over short jobs
• Use Application Load Balancer for production

Common Pitfalls

• Using Linux container images
• Insufficient EC2 memory
• Forgetting ECS cluster user data

Final Thoughts

Windows containers on Amazon ECS are a powerful bridge between legacy workloads and modern cloud infrastructure.
If you’re migrating older Windows applications, ECS provides a clean, scalable, AWS-native path forward.

Before you go

• Please take a moment to like the post and follow the writer!
• Did you know that over 400,000 developers share what they’re building, learning, and discovering across our platforms every month? Learn how you can contribute here