Docker with Amazon ECS

Amazon ECS is a highly scalable, high-performance container orchestration service that supports Docker containers and allows you to easily run and scale containerized applications on AWS.

AWS CLI

This section provides some brief instructions on how to install and configure the AWS CLI. For the most recent information on how to install the AWS Command Line Interface see the Installing the AWS CLI guide. The steps below provide a quick short-hand of this guide.

Requirements: Python 2 (version 2.6.5+) or Python 3 (version 3.3+)

pip install awscli --upgrade --user

brew install awscli

Verify that the AWS CLI is installed correctly:

aws --version

Next we'll need to configure the AWS CLI. For the most recent information on how to configure the AWS Command Line Interface see the Configuring the AWS CLI guide. The steps below provide a quick short-hand of this guide.

Run the following command to configure the AWS CLI in your environment:

aws configure

You'll be prompted to provide the following information:

• AWS Access Key ID
• AWS Secret Access Key
• Default region name (e.g. us-east-1)
• Default output format (e.g. json)

You can retrieve the AWS Access Key ID and AWS Secret Access Key in your AWS Console | My Account | Security Credentials. For the Default region name you may choose the region ID (e.g. us-east-1) suggested by the region query parameter in the URL of the AWS console session you're logged in with, e.g.

https://console.aws.amazon.com/console/home?region=us-east-1

Amazon ECS CLI

This section provides some brief instructions on how to install and configure the Amazon ECS CLI. For the most recent information on how to install the Amazon ECS CLI see the Installing the Amazon ECS CLI guide. The steps below provide a quick short-hand of this guide.

Download the latest version of the ECS CLI:

sudo curl -o /usr/local/bin/ecs-cli https://s3.amazonaws.com/amazon-ecs-cli/ecs-cli-linux-amd64-latest

sudo curl -o /usr/local/bin/ecs-cli https://s3.amazonaws.com/amazon-ecs-cli/ecs-cli-darwin-amd64-latest

Apply execute permissions to the ECS CLI:

sudo chmod +x /usr/local/bin/ecs-cli

Verify that the ECS CLI is working properly:

ecs-cli --version

Next we'll need to configure the Amazon ECS CLI. For the most recent information on how to configure the Amazon ECS CLI see the Configuring the Amazon ECS CLI guide. The steps below provide a quick short-hand of this guide.

The Amazon ECS CLI requires the following basic configuration information:

• ECS profile
• AWS credentials
• AWS Region in which to create your cluster
• default ECS cluster name

This information is stored in the following configuration file (based on your OS platform):

• Linux, Mac OS X: ~/.ecs/config
• Windows:  %userprofile%\AppData\local\ecs\config

To setup an ECS CLI profile run the following command, substituting $ECS_PROFILE_NAME  with your desired profile name, $AWS_ACCESS_KEY_ID and $AWS_SECRET_ACCESS_KEY with your AWS security credentials.

ecs-cli configure profile --profile-name $ECS_PROFILE_NAME --access-key $AWS_ACCESS_KEY_ID --secret-key $AWS_SECRET_ACCESS_KEY

Next, create a cluster configuration, which defines the AWS region to use, resource creation prefixes and the cluster name to use with the ECS CLI. Replace the related variables with your own preferences (see the example below).

ecs-cli configure --cluster $ECS_CLUSTER_NAME --default-launch-type $ECS_TYPE --region $ECS_REGION --config-name $ECS_CONFIG_NAME

In the command above you may choose to leave out the --config_name option and have the default cluster configuration in place. Below is an example of the various configuration attributes involved:

ECS_CLUSTER_NAME="devshell-ecs"
ECS_TYPE="EC2" # or FARGATE
ECS_REGION="us-east-1"
ECS_CONFIG_NAME="devshell-ecs"

Deployment

To illustrate a simple Amazon ECS deployment, let's assume we have a Docker composition manifest named devshell.ecs.yml describing our app. Here are the steps to deploy, setup and teardown our app:

Start the ECS cluster (replace your --instance-type and --keypair attribute values with your own):

ecs-cli up --capability-iam --instance-type t2.large --keypair keypair_name

Deploy the app with the related Docker composition manifest (replace the --file and --project-name attribute values with your own):

ecs-cli compose --file devshell.ecs.yml --project-name devshell service up

View your ECS app service(s) (this would list the related Docker composition stack):

ecs-cli ps

Stop (teardown) the running app (replace the --file and --project-name attribute values with your own):

ecs-cli compose --file devshell.ecs.yml --project-name devshell service down

Stop the ECS cluster:

ecs-cli down

You may see the related (deployment) ECS resources in your AWS Console:

• ECS clusters
• ECS task definitions