Docker with Amazon ECS

Docker with Amazon ECS

Looking to deploy your Docker containers with Amazon Elastic Container Service (ECS)? Here's a brief guide to get you going. This article uses the AWS and ECS CLI tooling in the process.


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.

The 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+)

Installing awscli on Linux

Run the following command to install the awscli package using pip:

pip install awscli --upgrade --user

After installing awscli you may have to add the AWS CLI Executable to your Command-Line Path.

Installing awscli on macOS

We use Homebrew to install the required package(s).

brew install awscli

Configuring 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

The 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, based on your platform of choice.

Linux:

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

macOS:

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

Grant execute permissions to the ecs-sli binary:

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, macOS: ~/.ecs/config

  • Windows: %userprofile%\AppData\local\ecs\config

To set up 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"

Deploying your app

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, set up, 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: