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.

Prerequisites

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:

AWS_DEFAULT_REGION=us-east-1
ROLE_NAME=ecsMithrilRole
CLUSTER_NAME=test-ecs-anywhere
SERVICE_NAME=test-ecs-anywhere-svc

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": [
      "ssm.amazonaws.com"
    ]},
    "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 "ecs-anywhere-install.sh" "https://amazon-ecs-agent-packages-preview.s3.us-east-1.amazonaws.com/ecs-anywhere-install.sh" && sudo chmod +x ecs-anywhere-install.sh

# (Optional) Check integrity of the shell script
curl -o "ecs-anywhere-install.sh.sha256" "https://amazon-ecs-agent-packages-preview.s3.us-east-1.amazonaws.com/ecs-anywhere-install.sh.sha256" && sha256sum -c ecs-anywhere-install.sh.sha256

# Run the install script
sudo ./ecs-anywhere-install.sh \
    --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": [
    "EXTERNAL"
  ],
  "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.

Cleanup

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

Summary

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.