Getting Started with Windows Containers - Amazon Elastic Container Service

Getting Started with Windows Containers

This tutorial walks you through manually getting Windows containers running on Amazon ECS with the Amazon ECS-optimized Windows AMI. You create a cluster for your Windows container instances, launch one or more container instances into your cluster, register a task definition that uses a Windows container image, create a service that uses that task definition, and then view the sample webpage that the container runs.

Step 1: Create a Windows Cluster

You should create a new cluster for your Windows containers. Linux container instances cannot run Windows containers, and vice versa, so proper task placement is best accomplished by running Windows and Linux container instances in separate clusters. In this tutorial, you create a cluster called windows for your Windows containers.

To create a cluster with the AWS Management Console

  1. Open the Amazon ECS console at

  2. In the navigation pane, choose Clusters.

  3. On the Clusters page, choose Create Cluster.

  4. Choose EC2 Windows + Networking and choose Next step.

  5. For Cluster name enter a name for your cluster (in this example, windows is the name of the cluster). Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.

  6. Choose Create an empty cluster, Create.

To create a cluster with the AWS CLI

  • You can create a cluster using the AWS CLI with the following command:

    aws ecs create-cluster --cluster-name windows

Step 2: Launching a Windows Container Instance into your Cluster

You can launch a Windows container instance using the AWS Management Console, as described in this topic. Before you begin, be sure that you've completed the steps in Setting Up with Amazon ECS. After you've launched your instance, you can use it to run tasks.

To launch a Windows container instance

  1. Open the Amazon EC2 console at

  2. From the navigation bar, select the region to use.

  3. From the console dashboard, choose Launch Instance.

  4. On the Choose an Amazon Machine Image (AMI) page, type ECS_Optimized in the Search community AMIs field and press the Enter key. Choose Select next to the Windows_Server-2019-English-Full-ECS_Optimized-2019.09.11 AMI.


    There are Amazon ECS-optimized AMIs for both Windows Server 2019 and Windows Server 2016. For more information, see Amazon ECS-optimized AMIs.

  5. On the Choose an Instance Type page, you can select the hardware configuration of your instance. The t2.micro instance type is selected by default. The instance type that you select determines the resources available for your tasks to run on.

  6. Choose Next: Configure Instance Details.

  7. On the Configure Instance Details page, set the Auto-assign Public IP check box depending on whether to make your instance accessible from the public internet. If your instance should be accessible from the internet, verify that the Auto-assign Public IP field is set to Enable. If your instance should not be accessible from the Internet, choose Disable.


    Container instances need access to communicate with the Amazon ECS service endpoint. This can be through an interface VPC endpoint or through your container instances having public IP addresses.

    For more information about interface VPC endpoints, see Amazon ECS interface VPC endpoints (AWS PrivateLink).

    If you do not have an interface VPC endpoint configured and your container instances do not have public IP addresses, then they must use network address translation (NAT) to provide this access. For more information, see NAT Gateways in the Amazon VPC User Guide and HTTP Proxy Configuration in this guide. For more information, see Tutorial: Creating a VPC with Public and Private Subnets for Your Clusters.

  8. On the Configure Instance Details page, select the ecsInstanceRole IAM role value that you created for your container instances in Setting Up with Amazon ECS.


    If you do not launch your container instance with the proper IAM permissions, your Amazon ECS agent does not connect to your cluster. For more information, see Amazon ECS Container Instance IAM Role.

  9. Expand the Advanced Details section and paste the provided user data PowerShell script into the User data field. By default, this script registers your container instance into the windows cluster that you created earlier. To launch into another cluster instead of windows, replace the red text in the script below with the name of your cluster.


    The -EnableTaskIAMRole option is required to enable IAM roles for tasks. For more information, see Windows IAM Roles for Tasks.

    <powershell> Import-Module ECSTools Initialize-ECSAgent -Cluster 'windows' -EnableTaskIAMRole </powershell>
  10. Choose Next: Add Storage.

  11. On the Add Storage page, configure the storage for your container instance. The Windows OS and container images are large (approximately 9 GiB for the Windows server core base layers), and just a few images and containers quickly fill up the default 50-GiB volume size for the Amazon ECS-optimized Windows AMI. A larger root volume size (for example, 200 GiB) allows for more containers and images on your instance.

    You can optionally increase or decrease the volume size for your instance to meet your application needs.

  12. Choose Review and Launch.

  13. On the Review Instance Launch page, under Security Groups, you see that the wizard created and selected a security group for you. By default, you should have port 3389 for RDP connectivity. To have your containers to receive inbound traffic from the internet, open those ports as well.

    1. Choose Edit security groups.

    2. On the Configure Security Group page, ensure that the Create a new security group option is selected.

    3. Add rules for any other ports that your containers may need and choose Review and Launch. The sample task definition later in this walk through uses port 8080, so you should open that to Anywhere.

  14. On the Review Instance Launch page, choose Launch.

  15. In the Select an existing key pair or create a new key pair dialog box, choose Choose an existing key pair, then select the key pair that you created when getting set up.

    When you are ready, select the acknowledgment field, and then choose Launch Instances.

  16. A confirmation page lets you know that your instance is launching. Choose View Instances to close the confirmation page and return to the console.

  17. On the Instances screen, you can view the status of your instance. It takes a short time for an instance to launch. When you launch an instance, its initial state is pending. After the instance starts, its state changes to running, and it receives a public DNS name. (If the Public DNS column is hidden, choose the Show/Hide icon and choose Public DNS.)

  18. After your instance has launched, you can view your cluster in the Amazon ECS console to see that your container instance has registered with it.


    It can take up to 15 minutes for your Windows container instance to register with your cluster.

Step 3: Register a Windows Task Definition

Before you can run Windows containers in your Amazon ECS cluster, you must register a task definition. The following task definition example displays a simple webpage on port 8080 of a container instance with the microsoft/iis container image.

To register the sample task definition with the AWS Management Console

  1. Open the Amazon ECS console at

  2. In the navigation pane, choose Task Definitions.

  3. On the Task Definitions page, choose Create new Task Definition.

  4. On the Select launch type compatibilities page, choose EC2, Next step.


    The Fargate launch type is not compatible with Windows containers.

  5. Scroll to the bottom of the page and choose Configure via JSON.

  6. Paste the sample task definition JSON below into the text area (replacing the pre-populated JSON there) and choose Save.

    { "family": "windows-simple-iis", "containerDefinitions": [ { "name": "windows_sample_app", "image": "microsoft/iis", "cpu": 512, "entryPoint":["powershell", "-Command"], "command":["New-Item -Path C:\\inetpub\\wwwroot\\index.html -ItemType file -Value '<html> <head> <title>Amazon ECS Sample App</title> <style>body {margin-top: 40px; background-color: #333;} </style> </head><body> <div style=color:white;text-align:center> <h1>Amazon ECS Sample App</h1> <h2>Congratulations!</h2> <p>Your application is now running on a container in Amazon ECS.</p>' -Force ; C:\\ServiceMonitor.exe w3svc"], "portMappings": [ { "protocol": "tcp", "containerPort": 80, "hostPort": 8080 } ], "memory": 768, "essential": true } ] }
  7. Verify your information and choose Create.

To register the sample task definition with the AWS CLI

  1. Create a file called windows-simple-iis.json.

  2. Open the file with your favorite text editor and add the sample JSON above to the file and save it.

  3. Using the AWS CLI, run the following command to register the task definition with Amazon ECS.


    Make sure that your AWS CLI is configured to use the same region that your Windows cluster exists in, or add the --region your_cluster_region option to your command.

    aws ecs register-task-definition --cli-input-json file://windows-simple-iis.json

Step 4: Create a Service with Your Task Definition

After you have registered your task definition, you can place tasks in your cluster with it. The following procedure creates a service with your task definition and places one task on your cluster.

To create a service from your task definition with the console

  1. On the Task Definition: windows-simple-iis registration confirmation page, choose Actions, Create Service.

  2. On the Create Service page, enter the following information and then choose Create service.

    • Launch type: EC2

    • Cluster: windows

    • Service name: windows-simple-iis

    • Service type: REPLICA

    • Number of tasks: 1

    • Deployment type: Rolling update

To create a service from your task definition with the AWS CLI

  • Using the AWS CLI, run the following command to create your service.

    aws ecs create-service --cluster windows --task-definition windows-simple-iis --desired-count 1 --service-name windows-simple-iis

Step 5: View Your Service

After your service has launched a task into your cluster, you can view the service and open the IIS test page in a browser to verify that the container is running.


It can take up to 15 minutes for your container instance to download and extract the Windows container base layers.

To view your service

  1. Open the Amazon ECS console at

  2. On the Clusters page, choose the windows cluster.

  3. In the Services tab, choose the windows-simple-iis service.

  4. On the Service: windows-simple-iis page, choose the task ID for the task in your service.

  5. On the Task page, expand the iis container to view its information.

  6. In the Network bindings of the container, you should see an External Link IP address and port combination link. Choose that link to open the IIS test page in your browser.

                            Windows simple IIS test page