Your submission was sent successfully! Close

Thank you for signing up for our newsletter!
In these regular emails you will find the latest updates from Canonical and upcoming events where you can meet our team.Close

Thank you for contacting our team. We will be in touch shortly.Close

  1. Blog
  2. Article

on 28 May 2021

How to run ECS Anywhere workloads using Ubuntu on any infrastructure

ECS Anywhere allows you to use Amazon Web Services’ container service outside of the AWS cloud, and Canonical is proud to be a launch partner for this service. Using Ubuntu as the base OS for your ECS clusters on-prem or elsewhere will allow you to benefit from Ubuntu’s world-leading hardware support, professional services, and vast ecosystem, in turn allowing your ECS clusters to run with optimal performance everywhere you need it.

In this example, we will demonstrate running the ECS Anywhere agent on an Ubuntu server on-prem. We will use Multipass to simulate an on-prem server but you can run these instructions on any supported release of Ubuntu, whether in your data center or in any public cloud.


To follow along, you will need to have the AWS CLI utility installed and configured on your machine. We will use Multipass to create an Ubuntu VM but you can run these instructions directly on your Ubuntu servers where you want to run the ECS Anywhere workloads. You can use Multipass to easily and quickly get official Ubuntu VMs for Windows, macOS, and Linux.

To install Multipass on Linux:

sudo snap install multipass

Set Launch variables

On your Linux machine where you have the AWS CLI installed (not necessarily the machine where you will run the ECS Anywhere workloads), set the environment variables:


Create the IAM role

Create a file called ssm-trust-policy.json with the following contents:

  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Principal": {"Service": [
    "Action": "sts:AssumeRole"

Then create the role and verify:

aws iam create-role --role-name $ROLE_NAME --assume-role-policy-document file://ssm-trust-policy.json

aws iam attach-role-policy --role-name $ROLE_NAME --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

aws iam attach-role-policy --role-name $ROLE_NAME --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEC2ContainerServiceforEC2Role

# Verify
aws iam list-attached-role-policies --role-name $ROLE_NAME

Create ECS Anywhere Cluster

Create the ECS Anywhere cluster and activation key:

aws ecs create-cluster --cluster-name $CLUSTER_NAME

aws ssm create-activation --iam-role $ROLE_NAME | tee ssm-activation.json

Launch an Ubuntu VM with Multipass (optional)

We will now create an Ubuntu 20.04 VM with Multipass. This step is not required if you already have an Ubuntu server where you want to run the ECS Anywhere workloads. This could be any Ubuntu VM or bare metal machine in your data center, or even an Ubuntu instance running in a different public cloud. In that case, just run these commands on that server directly:

multipass launch focal -n ecs-anywhere-ubuntu

Install ECS Anywhere agent and required software on Ubuntu

Now we install the ECS Anywhere agent on the Ubuntu server. Make sure to replace the ACTIVATION_ID and ACTIVATION_CODE with the ones generated in the previous steps:

# Run all commands on the Ubuntu system where you will run the ECS workloads

export ACTIVATION_ID=<your activation ID>
export ACTIVATION_CODE=<your activation code>

# Download the ecs-anywhere install Script 
curl -o "" "" && sudo chmod +x

# (Optional) Check integrity of the shell script
curl -o "" "" && sha256sum -c

# Run the install script
sudo ./ \
    --cluster test-ecs-anywhere \
    --activation-id $ACTIVATION_ID \
    --activation-code $ACTIVATION_CODE \
    --region us-east-1

Validate the installation

After the installation completes, exit the SSH session and go back to your machine where you ran the original AWS CLI commands. Verify that the instances are connected and running:

aws ssm describe-instance-information

aws ecs list-container-instances --cluster $CLUSTER_NAME

Register Task Definition, and Run Task from command line now

Create a file called external-task-definition.json with the following contents:

  "requiresCompatibilities": [
  "containerDefinitions": [
      "name": "nginx",
      "image": "nginx:latest",
      "memory": 256,
      "cpu": 256,
      "essential": true,
      "portMappings": [
          "containerPort": 80,
          "hostPort": 8080,
          "protocol": "tcp"
  "networkMode": "bridge",
  "family": "nginx"

Then register a new task definition for our ECS Anywhere cluster and run that task on your Ubuntu server. 

#Register the task definition
aws ecs register-task-definition --cli-input-json file://external-task-definition.json

#Run the task
aws ecs run-task --cluster $CLUSTER_NAME --launch-type EXTERNAL --task-definition nginx

#Get the Task ID
TEST_TASKID=$(aws ecs list-tasks --cluster $CLUSTER_NAME | jq -r '.taskArns[0]')

#Verify Task is Running
aws ecs describe-tasks --cluster $CLUSTER_NAME --tasks $TEST_TASKID

Verify the container is listening

You should now be able to go to http://<your VM IP>:8080 now and see nginx running locally.


To clean up, perform the following steps:

# Cleanup SSM
aws ssm describe-activations | jq ".ActivationList | .[] | .ActivationId" | xargs -L 1 aws ssm delete-activation --activation-id

aws ssm describe-instance-information | jq ".InstanceInformationList | .[] | .InstanceId" | grep "mi-" | xargs -L 1 aws ssm deregister-managed-instance --instance-id

# Cleanup ECS resources
aws ecs list-container-instances --cluster $CLUSTER_NAME | jq ".containerInstanceArns | .[]" | xargs -L 1 aws ecs deregister-container-instance --cluster $CLUSTER_NAME --force --container-instance

aws ecs delete-cluster --cluster $CLUSTER_NAME

# Verify all items deleted are empty
aws ssm describe-activations
aws ssm describe-instance-information
aws ecs list-container-instances --cluster $CLUSTER_NAME

#Remove Multipass VM (optional)
multipass stop ecs-anywhere-ubuntu
multipass delete ecs-anywhere-ubuntu


You can use ECS Anywhere to run AWS ECS containers on any Ubuntu server, whether in your data center or in any public cloud.

In this example, we deployed an application as a standalone task. You can refer to the AWS documentation for examples of how to deploy an ECS application so that it is running continually or to place it behind a load balancer.

Contact Canonical today if you want to combine ECS Anywhere with Ubuntu Advantage to get the peace of mind of kernel live patching, full support on thousands of packages, FIPS modules, and many other advantages.

Related posts

Oliver Smith
17 May 2024

Migrating from CentOS to Ubuntu: a guide for system administrators and DevOps

Cloud and server Article

CentOS 7 is on track to reach its end-of-life (EoL) on June 30, 2024. Post this date, the CentOS Project will cease to provide updates or support, including vital security patches. Moving away from the RHEL-based ecosystem might appear daunting, but if you’re considering Ubuntu the switch can be both straightforward and economically viabl ...

Simon Fels
20 March 2024

Implementing an Android™ based cloud game streaming service with Anbox Cloud

Cloud and server Article

Since the outset, Anbox Cloud was developed with a variety of use cases for running Android at scale. Cloud gaming, more specifically for casual games as found on most user’s mobile devices, is the most prominent one and growing in popularity. Enterprises are challenged to find a solution that can keep up with the increasing ...

Carlos Bravo
2 February 2024

Generative AI on a GPU-Instance with Ubuntu on AWS: Part 1 – Image Generation

Ubuntu Article

This blog post will show you how to run one of the most used Generative AI models for Image generation on Ubuntu on a GPU-based EC2 instance on AWS ...