Run Amazon ECS tasks on Amazon WorkSpaces with Amazon ECS Anywhere - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsEpicsRelated resourcesAttachments

Run Amazon ECS tasks on Amazon WorkSpaces with Amazon ECS Anywhere

Created by Akash Kumar (AWS)

Environment: Production

Technologies: Containers & microservices; Modernization

Workload: All other workloads

AWS services: Amazon ECS; Amazon WorkSpaces; AWS Directory Service

Summary

Amazon Elastic Container Service (Amazon ECS) Anywhere supports the deployment of Amazon ECS tasks in any environment, including Amazon Web Services (AWS) managed infrastructure and customer managed infrastructure. You can do this while using a fully AWS managed control plane that’s running in the cloud and always up to date. 

Enterprises often use Amazon WorkSpaces for developing container-based applications. This has required Amazon Elastic Compute Cloud (Amazon EC2) or AWS Fargate with an Amazon ECS cluster to test and run ECS tasks. Now, by using Amazon ECS Anywhere, you can add Amazon WorkSpaces as external instances directly to an ECS cluster, and you can run your tasks directly. This reduces your development time, because you can test your container with an ECS cluster locally on Amazon WorkSpaces. You can also save the cost of using EC2 or Fargate instances for testing your container applications.

This pattern showcases how to deploy ECS tasks on Amazon WorkSpaces with Amazon ECS Anywhere. It sets up the ECS cluster and uses AWS Directory Service Simple AD to launch the WorkSpaces. Then the example ECS task launches NGINX in the WorkSpaces.

Prerequisites and limitations

Architecture

Target technology stack

  • A virtual private cloud (VPC)

  • An Amazon ECS cluster

  • Amazon WorkSpaces

  • AWS Directory Service with Simple AD

Target architecture 

ECS Anywhere sets up ECS cluster and uses Simple AD to launch WorkSpaces.

The architecture includes the following services and resources:

  • An ECS cluster with public and private subnets in a custom VPC

  • Simple AD in the VPC to provide user access to Amazon WorkSpaces

  • Amazon WorkSpaces provisioned in the VPC using Simple AD

  • AWS Systems Manager activated for adding Amazon WorkSpaces as managed instances

  • Using Amazon ECS and AWS Systems Manager Agent (SSM Agent), Amazon WorkSpaces added to Systems Manager and the ECS cluster

  • An example ECS task to run in the WorkSpaces in the ECS cluster

Tools

  • AWS Directory Service Simple Active Directory (Simple AD) is a standalone managed directory powered by a Samba 4 Active Directory Compatible Server. Simple AD provides a subset of the features offered by AWS Managed Microsoft AD, including the ability to manage users and to securely connect to Amazon EC2 instances.

  • Amazon Elastic Container Service (Amazon ECS) is a fast and scalable container management service that helps you run, stop, and manage containers on a cluster.

  • AWS Identity and Access Management (IAM) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them.

  • AWS Systems Manager helps you manage your applications and infrastructure running in the AWS Cloud. It simplifies application and resource management, shortens the time to detect and resolve operational problems, and helps you manage your AWS resources securely at scale.

  • Amazon WorkSpaces helps you provision virtual, cloud-based Microsoft Windows or Amazon Linux desktops for your users, known as WorkSpaces. WorkSpaces eliminates the need to procure and deploy hardware or install complex software.

Epics

TaskDescriptionSkills required

Create and configure the ECS cluster.

To create the ECS cluster, follow the instructions in the AWS documentation, including the following steps:

  • For Select cluster compatibility, choose Networking only, which will support an Amazon WorkSpace as an external instance to the ECS cluster.

  • Choose to create a new VPC.

Cloud architect
TaskDescriptionSkills required

Set up Simple AD and launch Amazon WorkSpaces.

To provision a Simple AD directory for your newly created VPC and launch Amazon WorkSpaces, follow the instructions in the AWS documentation.

Cloud architect
TaskDescriptionSkills required

Download the attached scripts.

On your local machine, download the ssm-trust-policy.json and ssm-activation.json files that are in the Attachments section.

Cloud architect

Add the IAM role.

Add environment variables based on your business requirements.

export AWS_DEFAULT_REGION=${AWS_REGION_ID}
export ROLE_NAME=${ECS_TASK_ROLE}
export CLUSTER_NAME=${ECS_CLUSTER_NAME}
export SERVICE_NAME=${ECS_CLUSTER_SERVICE_NAME}

Run the following command.

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

Add the AmazonSSMManagedInstanceCore policy to the IAM role.

Run the following command.

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

Add the AmazonEC2ContainerServiceforEC2Role policy to IAM role.

Run the following command.

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

Verify the IAM role.

To verify the IAM role, run the following command.

aws iam list-attached-role-policies --role-name $ROLE_NAME
Cloud architect

Activate Systems Manager.

Run the following command.

aws ssm create-activation --iam-role $ROLE_NAME | tee ssm-activation.json
Cloud architect
TaskDescriptionSkills required

Connect to your WorkSpaces.

To connect to and set up your Workspaces, follow the instructions in the AWS documentation.

App developer

Download the ecs-anywhere install script.

At the command prompt, run the following command.

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
App developer

Check integrity of the shell script.

(Optional) Run the following command.

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
App developer

Add an EPEL repository on Amazon Linux.

To add an Extra Packages for Enterprise Linux (EPEL) repository, run the  command sudo amazon-linux-extras install epel -y.

App developer

Install Amazon ECS Anywhere.

To run the install script, use the following command.

sudo ./ecs-anywhere-install.sh --cluster $CLUSTER_NAME --activation-id $ACTIVATION_ID --activation-code $ACTIVATION_CODE --region $AWS_REGION

Check instance information from the ECS cluster.

To check the Systems Manager and ECS cluster instance information and validate that WorkSpaces were added on the cluster, run the following command from your local machine.

aws ssm describe-instance-information" && "aws ecs list-container-instances --cluster $CLUSTER_NAME
App developer
TaskDescriptionSkills required

Create a task execution IAM role.

Download task-execution-assume-role.json and external-task-definition.json from the Attachments section. 

On your local machine, run the following command.

aws iam --region $AWS_DEFAULT_REGION create-role --role-name $ECS_TASK_EXECUTION_ROLE --assume-role-policy-document file://task-execution-assume-role.json
Cloud architect

Add the policy to the execution role.

Run the following command.

aws iam --region $AWS_DEFAULT_REGION attach-role-policy --role-name $ECS_TASK_EXECUTION_ROLE --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
Cloud architect

Create a task role.

Run the following command.

aws iam --region $AWS_DEFAULT_REGION create-role --role-name $ECS_TASK_EXECUTION_ROLE --assume-role-policy-document file://task-execution-assume-role.json
Cloud architect

Register the task definition to the cluster.

On your local machine, run the following command.

aws ecs register-task-definition --cli-input-json file://external-task-definition.json
Cloud architect

Run the task.

On your local machine, run the following command.

aws ecs run-task --cluster $CLUSTER_NAME --launch-type EXTERNAL --task-definition nginx
Cloud architect

Validate the task running state.

To fetch the task ID, run the following command.

export TEST_TASKID=$(aws ecs list-tasks --cluster $CLUSTER_NAME | jq -r '.taskArns[0]')

With the task ID, run the following command.

aws ecs describe-tasks --cluster $CLUSTER_NAME --tasks ${TEST_TASKID}
Cloud architect

Verify the task on the WorkSpace.

To check that NGINX is running on the WorkSpace, run the command curl http://localhost:8080.

App developer

Related resources

Attachments

To access additional content that is associated with this document, unzip the following file: attachment.zip