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.
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: