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.
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+)
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.
You need Homebrew to install the required package(s).
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: