Amazon ECS: using the CLI with Docker Compose

The Amazon ECS Command Line Interface (CLI) is a command line interface for Amazon EC2 Container Service (Amazon ECS). It provides high-level commands to simplify creating, updating, and monitoring clusters and tasks from your local development environment.

One interesting thing is that ECS CLI supports Docker Compose  for defining and running multi-container applications. We can use the CLI as an alternative to the AWS Management Console on the web.

In this brief post I will show you how to setup the CLI and integrate it with Docker Compose. All steps are supposed to running on macOS Sierra environment, but you can adapt it easily on your environment too.

1. Download and configure the CLI

1. First of all, download the CLI 

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

2. Then, Apply execute permissions to the binary.

   1. $ sudo chmod +x /usr/local/bin/ecs-cli

3. Finally, you can check the cli version

   1. $ ecs-cli --version
      ecs-cli version 0.4.6 (3e2a382)

Now you can configure the CLI. The minimum configuration is very basic, of course you can go deep in more fine grained config as well.

$ ecs-cli configure --region us-west-2 --access-key $AWS_ACCESS_KEY_ID --secret-key $AWS_SECRET_ACCESS_KEY --cluster ecs-cli-demo

Change region, access-key, secret-key and cluster to the value you need.

2. Deploy a Compose file to a cluster

You can now start using the CLI, and let's start by creating a new cluster (named ecs-cli-demo in our previous configuration). To do that, you can run this command on the CLI

$ ecs-cli up --keypair aws-keypair-test --capability-iam --size 2 --instance-type t2.medium --force

This commands create a cluster of 2 EC2 instances of type t2.medium. Change parameters values accordingly to your needs (e.g.: key pair name, size and instance type). The ECS CLI uses AWS Cloudformation to create the cluster via a Cloudformation Stack.

Also, by using the --force param you can tell to Cloudformation that you need a complete stack recreation (e.g.: you already have a previous stack named "ecs-cli-demo" and you want to replace it).

You can also use the helper to see all available parameters and default values:

$ ecs-cli help up

Once the creation is completed you should see the new cluster availble in the AWS Console.

Now we can run tasks on the ECS cluster. Tasks are basically groups of containers. Our first task will be a sample web page.

Let's start by creating a docker-compose.yml file:

version: '2'
services:
web:
image: amazon/amazon-ecs-sample
ports:
 - "80:80"

The amazon-ecs-sample image simply contains a web page.

Now we can create an ECS task definition and start an ECS task withe the following command

$ ecs-cli compose up

You can see the task that is running with ecs-cli compose ps, the output will be something similar to :

fc4d116d-eeba-436b-b76b-770754493456/web RUNNING 54.154.216.119:80->80/tcp ecscompose-ecs-cli:1

If you navigate your web browser to the task’s IP address (in my example is 54.154.216.119), you'll see the sample app running in the ECS cluster.

View fullsize

Great ! We have deployed our compose file to a ECS cluster.

This is just a starting point we can use to understand how to use the widely used Docker Compose format to manage an ECS cluster with the CLI. From now on we can use this technique to deploy more complex projects.