Microsoft Workloads on AWS

Amazon Elastic Container Service (ECS) Anywhere support on Windows

In AWS, customers are running their most mission-critical workloads on Amazon Elastic Container Service (Amazon ECS) with Windows as their compute layer. Some applications have requirements for low latency access to on-premises systems or data processing locally due to data residency requirements or local system dependencies. These requirements might be a roadblock for the ongoing modernization strategy.

In May 2021, AWS announced Amazon Elastic Container Service (ECS) Anywhere, a feature of Amazon ECS that enables you to easily run and manage container workloads on customer-managed infrastructure. ECS Anywhere builds upon the ease and simplicity of Amazon ECS to provide a consistent tooling and API experience across your container-based applications. Whether on premises or in the cloud, you’ll have similar cluster management, workload scheduling, and monitoring you’ve come to know from Amazon ECS. You can reduce operational costs and overhead of container orchestration on premises by using the completely managed solution that ECS Anywhere provides. ECS Anywhere helps you meet compliance requirements and scale your business without sacrificing your on-premises investments.

Today, we are excited to announce ECS Anywhere support on Windows. With this latest release, customers can now take advantage of the simplicity of Amazon ECS and the fact that “it just works” for their Windows containers applications, both on premise or in any other cloud provider.

How it works

In this blog post, we will walk through the following steps to deploy a Windows container to Amazon ECS Anywhere:

1. Create an Elastic Container Service (ECS) cluster.
2. (Option 1) Web Console Experience – Registering a Windows external instance.
3. (Option 2) AWS CLI Experience – Registering a Windows external instance.
4. Launch a Windows-based Task definition

1. Create an Elastic Container Service (ECS) cluster

In order to keep the walk-through short and focused on ECS Anywhere, I’m going to create an ECS cluster through AWS Command Line Interface (CLI). There is no difference between creating an ECS cluster to execute on-premises or cloud tasks, as the control plane remains on AWS. Execute the following command:

aws ecs create-cluster --cluster-name YOURCLUSTERNAME --settings name=containerInsights,value=enabled

2. (Option 1) Web Console experience – Registering an external instance

Amazon ECS Anywhere provides support for registering an external instance, such as an on-premises server or virtual machine (VM), to your Amazon ECS cluster. External instances help you satisfy compliance, data gravity, and other business requirements by running your workloads on the infrastructure you own while enjoying simple and familiar ECS tooling.

The following diagram provides a high-level system architecture overview of Amazon ECS Anywhere:

Figure 1: Architecture design
Figure 1: Architecture design

Before you start using external instances, check the official documentation for supported operating systems and networks requirements.

2.1 To register a Windows Server virtual machine as Amazon ECS External instance, log into the ECS Console v2.

2.2 Navigate to Clusters from side menu.

2.3 Select the cluster in which the customer managed instance needs to be registered. In my example, I have selected ECSAnywhere-Windows, that is the cluster created on step 1.1.

2.4 Navigate to Infrastructure tab.

2.5 Select Register External Instances.

Figure 2: Amazon ECS Console
Figure 2: Amazon ECS Console

2.6 On the next screen, select the appropriate values for the fields, including the IAM role. If you don’t have an external instance IAM role, please visit this link for instructions on how to create one.

Figure 3: Register external instances console.
Figure 3: Register external instances console.

2.7 Select Generate registration command.

2.8 Copy the Windows command and run in PowerShell as an Administrator on your Windows instance.

Figure 4: Register external instances console
Figure 4: Register external instances console

The installation script will download, install all the dependencies on the Windows Virtual machine, and perform the following tasks for you:

  • Install Docker as a container runtime for Amazon ECS.
  • Install SSM agent.
  • Install ECSTools PowerShell module.
  • Install ECS agent.
  • Register instance as an SSM-managed instance on System Manager.
  • Start ECS agent, which will register the instance to the ECS cluster.

If the installation process requires a system restart, you can re-run the same command mentioned earlier after the system has been restarted. This will allow you to continue with the remaining installation steps.

3. (Option 2) AWS CLI experience – Register a Windows external instance

Customers seeking to automate the registration of external instances can benefit from the step-by-step commands mentioned in this optional step and add it as part of their existing automation deployment system.

3.1 Create a Systems Manager activation pair. This is used for Systems Manager managed instance activation. The output includes an ActivationId and ActivationCode. You will use these in a later step. Make sure that you specify the ECS Anywhere IAM role that you created by following the official documentation: Required IAM permissions for external instance.

Execute the following command:

aws ssm create-activation --iam-role ecsAnywhereRole | tee ssm-activation.json


Figure 5: Command output
Figure 5: Command output

3.2 On your on-premises server or virtual machine (VM), download and execute the installation script on a PowerShell session:

Invoke-RestMethod -URI "" -OutFile “ecs-anywhere-install.ps1”

3.3 Run the installation script. Specify the cluster name, Region, and the Systems Manager activation ID and activation code from step 3.1 above.

.\ecs-anywhere-install.ps1 -Region $Region -Cluster $Cluster -ActivationID $ActivationID -ActivationCode $ActivationCode

If the installation process requires a system restart, you can re-run the same command mentioned earlier after the system has been restarted. This will allow you to continue with the remaining installation steps.

4. Launch a Windows-based task

The following task definition is a sample application that uses the servercore/iis Windows container image. This task will run a simple IIS website with one HTML page that you can use to verify that the task is running.

4.1 Create a launch task definition on the Amazon ECS console v2 by following the official documentation or by using the following JSON file via AWS CLI or Amazon ECS console v1:

                "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 Anywhere.</p>'; C:\\ServiceMonitor.exe w3svc"

4.2 Congratulations, you have just launched your first on-premise ECS Task. Access the Tasks console on your cluster check for the Launch Type as External. You can also access HTML test web page by the IP address attached to the task.

Figure 6: Amazon Elastic Container Service console
Figure 6: Amazon Elastic Container Service console

Supported features with Amazon ECS Anywhere on Windows

In addition to the original list of features, following are a few additional features supported on Windows tasks:

  • Amazon FSx for Windows File Server is supported with Amazon ECS Anywhere. For more details, please visit the documentation available here.
  • ECS Exec supported for Windows tasks with Amazon ECS Anywhere.
  • Group Managed Service Accounts (gMSA) are supported with Amazon ECS Anywhere using AWS Managed Microsoft AD, as well as the on-premises Active Directory Domain Services. The steps for running ECS tasks with gMSA are available here.


With Amazon ECS Anywhere, you don’t need to run and operate separate container management software for your on-premises container workloads. Using the familiar ECS control plane to orchestrate your containers and run tasks on your infrastructure, you’ll spend less time on operational overhead and more time focusing on driving innovation for your business. Amazon ECS Anywhere enables you to leverage your existing capital investments in on-premises datacenters while simultaneously taking advantage of running workloads in the cloud. Consistent Amazon ECS tooling for orchestrating container services on premises and in the cloud makes it easier for you to migrate your containers workloads to the cloud in the future.

AWS can help you assess how your company can get the most out of cloud. Join the millions of AWS customers that trust us to migrate and modernize their most important applications in the cloud. To learn more on modernizing Windows Server or SQL Server, visit Windows on AWS. Contact us to start your migration journey today.

Marcio Morales

Marcio Morales

Marcio Morales is a Principal Specialist Solution Architect at Amazon Web Services, helping customers to migrate and modernize their infrastructure into AWS. He is the author of the book "Running Windows Containers on AWS" and a global SME for Windows containers. He helps AWS customers design, build, secure, and optimize Windows container workloads on AWS.

Harsh Rawat

Harsh Rawat

Harsh is a Software Development Engineer at Amazon Web Services, working with containers and container orchestrators.