Amazon EC2 Container Service
Developer Guide (API Version 2014-11-13)

Getting Started with Windows Containers

This tutorial walks you through manually getting Windows containers running on Amazon ECS. 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 web page that the container runs.

If you would rather have your cluster set up automatically with a provided AWS CloudFormation template, see Windows Containers AWS CloudFormation Template.

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. From the navigation bar, select the region to use.

  3. In the navigation pane, choose Clusters.

  4. On the Clusters page, choose Create Cluster.

  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 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, choose Quick Start.

  5. Choose the Microsoft Windows Server 2016 Base with Containers AMI for your container instance.

  6. 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.

  7. Choose Next: Configure Instance Details.

  8. 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 external network access to communicate with the Amazon ECS service endpoint, so if 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 Instances in the Amazon VPC User Guide.

  9. 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 will not connect to your cluster. For more information, see Amazon ECS Container Instance IAM Role.

  10. Configure your Windows container instance with the provided user data PowerShell script. 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 that value of the ECS_CLUSTER environment variable in the script below with the name of your cluster.


    To use the IAM roles for tasks feature with your Windows containers, replace the value of the ECS_ENABLE_TASK_IAM_ROLE environment variable in the script below with true. For more information, see Windows IAM Roles for Tasks.

    To use an HTTP proxy for your container agent traffic, add the following lines to the script below (in the Set agent env variables... section):

    $proxy = "proxy_ip_address_and_port" [Environment]::SetEnvironmentVariable("HTTP_PROXY", $proxy, "Machine") [Environment]::SetEnvironmentVariable("NO_PROXY", ",,\\.\pipe\docker_engine", "Machine")
    <powershell> ## The string 'windows' should be replaced with your cluster name # Set agent env variables for the Machine context (durable) [Environment]::SetEnvironmentVariable("ECS_CLUSTER", "windows", "Machine") [Environment]::SetEnvironmentVariable("ECS_ENABLE_TASK_IAM_ROLE", "false", "Machine") $agentVersion = 'v1.14.3' $agentZipUri = "$" $agentZipMD5Uri = "$agentZipUri.md5" ### --- Nothing user configurable after this point --- $ecsExeDir = "$env:ProgramFiles\Amazon\ECS" $zipFile = "$env:TEMP\" $md5File = "$env:TEMP\" ### Get the files from S3 Invoke-RestMethod -OutFile $zipFile -Uri $agentZipUri Invoke-RestMethod -OutFile $md5File -Uri $agentZipMD5Uri ## MD5 Checksum $expectedMD5 = (Get-Content $md5File) $md5 = New-Object -TypeName System.Security.Cryptography.MD5CryptoServiceProvider $actualMD5 = [System.BitConverter]::ToString($md5.ComputeHash([System.IO.File]::ReadAllBytes($zipFile))).replace('-', '') if($expectedMD5 -ne $actualMD5) { echo "Download doesn't match hash." echo "Expected: $expectedMD5 - Got: $actualMD5" exit 1 } ## Put the executables in the executable directory. Expand-Archive -Path $zipFile -DestinationPath $ecsExeDir -Force ## Start the agent script in the background. $jobname = "ECS-Agent-Init" $script = "cd '$ecsExeDir'; .\amazon-ecs-agent.ps1" $repeat = (New-TimeSpan -Minutes 1) $jobpath = $env:LOCALAPPDATA + "\Microsoft\Windows\PowerShell\ScheduledJobs\$jobname\ScheduledJobDefinition.xml" if($(Test-Path -Path $jobpath)) { echo "Job definition already present" exit 0 } $scriptblock = [scriptblock]::Create("$script") $trigger = New-JobTrigger -At (Get-Date).Date -RepeatIndefinitely -RepetitionInterval $repeat -Once $options = New-ScheduledJobOption -RunElevated -ContinueIfGoingOnBattery -StartIfOnBattery Register-ScheduledJob -Name $jobname -ScriptBlock $scriptblock -Trigger $trigger -ScheduledJobOption $options -RunNow Add-JobTrigger -Name $jobname -Trigger (New-JobTrigger -AtStartup -RandomDelay 00:1:00) </powershell> <persist>true</persist>
  11. Choose Next: Add Storage.

  12. On the Add Storage page, configure the storage for your container instance. The Windows OS and container images are quite large (approximately 9 GiB for the Windows server core base layers), and just a few images and containers quickly fill up the default 30 GiB volume size that the launch wizard uses. 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.

  13. Choose Review and Launch.

  14. On the Review Instance Launch page, under Security Groups, you'll see that the wizard created and selected a security group for you. By default, you should have port 3389 for RDP connectivity. If you want your containers to receive inbound traffic from the Internet, you need to 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 (the sample task definition later in this walk through uses port 8000, so you should open that to Anywhere), and choose Review and Launch.

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

  16. 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.

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

  18. 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.)

  19. 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 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 80 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. Scroll to the bottom of the page and choose Configure via JSON.

  5. 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": 100, "entryPoint":["powershell", "-Command"], "command":["New-Item -Path C:\\inetpub\\wwwroot\\index.html -Type 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>'; C:\\ServiceMonitor.exe w3svc"], "portMappings": [ { "protocol": "tcp", "containerPort": 80, "hostPort": 80 } ], "memory": 500, "essential": true } ] }
  6. 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 AWS Management 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.

    • Cluster: windows

    • Number of tasks: 1

    • Service name: windows-simple-iis

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