Announcing the Amazon ECS CLI v2

Amazon ECS released version 1 of the Amazon ECS CLI in 2015. The Amazon ECS CLI simplified the management of your Amazon ECS clusters, tasks, services, and ECR repositories by enabling you to create profiles and cluster configurations with default settings. While many customers have found the Amazon ECS CLI useful, we have received feedback that they want the Amazon ECS CLI to do more. In particular many people reached out on social media, GitHub issues, and support tickets to say that they wanted a more application focused experience that didn’t require interacting with lower-level ECS primitives as much.

We reached out to the community and worked deeply with some of our customers who provided feedback to find out more about what they needed. The culmination of this work is Amazon ECS CLI v2, a new open source command line tool that focuses on delivering an end-to-end experience for developing and deploying applications on Amazon ECS. The Amazon ECS CLI v2 provides opinionated best practice patterns by default and offers an easy workflow for customers to get started, develop, test, deploy, operate, and observe their containerized applications, all without extensive prior knowledge of Amazon Web Services.

This article will cover the tenets behind the project and dig deeper into all the new functionality that is now available to you when you use Amazon ECS CLI v2.

Development Tenets

One of the first steps was to craft some new tenets to guide the future direction of the Amazon ECS CLI. Here are the tenets we came up with based on your feedback:

  • Create modern applications by default. Applications created with the ECS CLI use the best practices of modern applications by default: they are serverless, they use infrastructure as code, they are observable, and they are secure.
  • Users think in terms of architecture, not of infrastructure. Developers creating a new microservice shouldn’t have to specify VPCs, load balancer settings, or complex pipeline configuration. They may not know anything about other AWS services. They should be able to specify what “kind” of application it is and how it fits into their overall architecture; the infrastructure should be generated from that.
  • Operations is part of the workflow. Modeling, provisioning, and deploying applications are only part of the application lifecycle for the developer. The CLI must support workflows around troubleshooting and debugging to help when things go wrong.
  • Deliver applications continuously. While the ECS CLI can be used to manually deploy changes to an application, we always help customers to move to CI/CD by helping them set up and manage pipelines.

Just as with other aspects of our open source development you can submit a PR on the project to improve these tenets too.

Overall, these tenets showed us that we needed to make a few changes in Amazon ECS CLI v2. First we needed to organize the workflow around some new primitives: applications and projects. The CLI needed to get more opinionated, to help users do the right thing automatically. It also needed to grow in scope, to help users across the entire lifecycle of their applications, including ongoing operations and monitoring.

We decided to organize all the new functionality of the command line experience into a few top-level categories. In this article we will look at each of these categories and what commands they include.

Installing Amazon ECS CLI v2

First I need to download and install the CLI. I start with the list of released binaries on Github and select the latest version. Next I run some commands on my development machine to download the binary and add it to my path so I can access it on the command line from any folder.

chmod +x ecs-preview-linux-v0.0.4
sudo cp ecs-preview-linux-v0.0.4 /usr/local/bin/ecs

The above instructions are for a Linux environment. The folder also contains binaries for Mac OS X and Windows, so substitute the appropriate binary for your personal development machine.

Getting Started with a Deployment

Getting started is often the hardest step, especially if you are getting started with a new tool that you have never used before. We decided to create an interactive experience that analyzes the files in the current working direction, and asks you questions about your application to help you set up your first ECS application. Let’s see how this works.

I type ecs init to launch an interactive wizard that asks me some questions about my application. I can choose the type of application, in this case a load balanced web application. The wizard locates my Dockerfile that describes the application and automatically generates a manifest that describes the ports and other container deployment properties.

At this point I am all set to run my application locally, build it, and test it locally, but I also have an option to prepare a staging environment to deploy my application to.

I don’t have to specify any settings or enter any complex details. The command line tool automatically creates a high availability environment spread across two Availability Zones, with an internet gateway, public subnets and routing tables. It creates an ECS cluster to deploy containers in this VPC, and an Application Load Balancer to distribute traffic to the containers once they are running.

Deploy my application

Now I have everything needed in order to deploy my application to the staging environment.

I type ecs app deploy to create my first deployment to this new environment. Since this is the first build the command line tool will automatically build my Docker container based on the Dockerfile it found earlier, and push that built container to an automatically created Elastic Container Registry.

Finally it rolls the container out into the ECS cluster that it created earlier and gives me the application URL that I can use to send traffic to my application.

As I expected, I now have a small web app that depicts Nyan cat flying through space. I was able to deploy it with just a Dockerfile and two commands!

Create a Pipeline

The new ECS CLI has already made it really easy to deploy the application but I’m not done yet. The next thing I want to create is an automated deployment pipeline. This way I can continuously update the application as I add new code.

All I need to do this is run ecs pipeline init. The CLI wizard prompts me to enter the name of my GitHub repo, and a GitHub access token for connecting to the GitHub repo. This GitHub access token gets safely stored in AWS Secrets Manager. Later an automatically created AWS CodePipeline will use the access token to fetch my code from the repo, build it, and then deploy it.

Once the pipeline is configured, I run ecs pipeline update to deploy the configured pipeline and activate it.

To test out this brand new pipeline, I can make a small CSS change to update the background color from blue to orange:

body {
  width: 100%;
  height: 100%;
  margin: 0;
  padding: 0;
  background: orange; /*#036;*/
  overflow: hidden;

I commit the change to my GitHub repo, and a minute later my AWS CodePipeline kicks off and I can see the automatic build run to completion:

I can access the application again, and now as expected I see Nyan cat flying through an orange color page.

Going forward, all I have to do to deploy my application is modify a file in my repository, commit it, and push it to the GitHub repository. This triggers an automatic build that uses the ECS CLI on the server side to deploy the application. This means that engineers on the team can contribute to the software and deploy without even needing the ECS CLI installed on their local development laptops.


We hope that the new Amazon ECS CLI v2 will make it even easier for you to get started with deploying your containerized application on AWS. The new higher-level commands and opinionated patterns for deployment can help you succeed faster. As always, please let us know what you’d like to see added to the project by opening an issue on our public roadmap.

You can get started with the Amazon ECS CLI v2 by visiting the GitHub repo:

Check out the official documentation as well for a detailed getting started guide.

You can also find the code for the application used in this article at:

Nathan Peck

Nathan Peck

Developer advocate for serverless containers at Amazon Web Services, working on Amazon Elastic Container Service and AWS Fargate. Likes building startup architecture and microservices.