[ECS]: AWS Copilot CLI (Formerly known as ECS CLI v2)

[kohidave]

Proposal for ECS CLI v2

⚠️ DISCLAIMER: This document outlines our vision for ECS CLI v2. Not all of these commands or integrations will be in the release. We want to gather early feedback on the ideas listed in this issue to make sure we’re building something useful and pivot if necessary.

Amazon ECS released version 1 of the Amazon ECS CLI in 2015. The Amazon ECS CLI v1 simplifies 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 this level of abstraction does not go far enough for developers who must still interact directly with Amazon ECS primitives.

The Amazon ECS development team is in the planning stages for a new major version (v2) of the Amazon ECS CLI. We are planning to shift the focus of the Amazon ECS CLI from using Docker Compose to model tasks and services to helping you model your Amazon ECS applications in a more holistic manner. We view this as a shift towards application-first development with an emphasis on usability and developer productivity.

The following is our initial proposal, which we would like feedback on.

What is ECS CLI v2?

ECS CLI v2 is an opinionated view of application-first development. This new iteration will introduce the concepts of applications and projects. An application is an Amazon ECS service or task. An application can also encapsulate other AWS resources, such as an Amazon SQS queue or a Amazon DynamoDB table, to achieve a business capability. Applications are independently deployable. A project is a namespace for a collection of related applications. If you build your applications through the Amazon ECS CLI, you’ll get some AWS best practices by default and have a smooth workflow for taking your applications from development to production. The new version of the Amazon ECS CLI will integrate with Infrastructure as Code toolkits like the AWS Cloud Development Kit (CDK) and HashiCorp Terraform so that you can grow in complexity and scale beyond what the Amazon ECS CLI aims to provide by default.

Modeling, provisioning, and deploying applications are only part of the application lifecycle for the developer. The Amazon ECS CLI aims to support workflows around troubleshooting and debugging to help when things go wrong.

Domains

These are the proposed categories to help you navigate our top-level commands.

• Getting started: These commands get you started with an Amazon ECS project. You can choose one of our existing application templates, for example a load-balanced expressjs app, or your existing Dockerfile. You can also choose how to manage your infrastructure as code, using, for example, our custom manifest format, AWS CloudFormation, AWS Cloud Development Kit, or Terraform. These commands help you create your infrastructure as code in your repository.
  Commands: ecs init, ecs project init.
• Develop: After the project template is created, you can iterate on its architecture. For example, you might want to add or remove an application. Examples including adding a new load-balanced service or scheduled task, adding a database or secret to an existing application, or listing all your applications. To deploy these changes you can either use a pipeline to release your changes to multiple stages or do ad-hoc deployments.
  Commands: ecs apps add, ecs apps db, ecs apps deploy, ecs pipelines.
• Observe: After an application is running in your cluster, you can examine it for validation or to understand what is going on during an incident. These commands revolve around telemetry and logging.
  Commands: ecs logs, ecs health, ecs trace.
• Operate: Manage the lifecycle of your ECS resources. These commands are similar to the AWS CLI and are granular enough to let you manage your images, tasks, services, or container instances directly.
  Commands: ecs images, ecs tasks, ecs services.
• Test: Test your application code and your infrastructure. Validate that your application is going to work as expected before you deploy, debug your application by setting breakpoints, or perform stress tests to discover the pressure points of your system.
  Commands: ecs local, ecs debug.
• Cost: Get pricing information about Amazon ECS and a breakdown of your infrastructure costs.
  Commands: ecs pricing.

Commands
These top-level commands are proposal and may not be in the final release. We want to experiment and simplify our commands while we are in preview with your feedback. They are listed here to give everyone a list of use cases and the vision we’d like to support.

$ ecs --help
Commands:
  Getting started  
     init                                 Initialize a project

  Develop  
     project                              Manage your projects
     env                                  Manage your environments
     app                                  Manage your applications
     pipeline                             Manage your CodePipelines
       
  Observe 
     logs                                 Display logs
     health                               Display metrics
     trace                                Display x-ray trace summaries
     
  Operate
     cluster                             Manage your clusters
     task                                Manage your tasks
     service                             Manage your services
     image                               Manage your ECR images
     task-def                            Manage your task definitions
     
  Test
     local                                Run your ECS task definition locally.
     debug                                Live debug an existing application.
     
  Cost
     pricing                              Display a breakdown of the cost of your application

Options:
 -h, --help                               Output usage information
 -v, --version                            Output the version number
 
Examples:
- Display the help menu for `apps` command 
  $ ecs apps --help

Releases

We plan to start with use cases that are not available in other available command line interfaces. Therefore, we believe focusing on the Getting started and Develop command categories first would be the most beneficial to users who want to use the Amazon ECS CLI.

Our plan is to release these features in preview in the new aws/amazon-ecs-cli-v2 GitHub repository and gather feedback. You can also track our tasks under the project on GitHub. While still in preview you can expect breaking changes to the commands.

What’s happening to v1?

The v1 CLI will continue existing as is. So if it already satisfies your existing use-cases you don’t have to upgrade. You can have both the v1 CLI and v2 CLI in your automated scripts if you’d like. We’ll continue to support all v1 commands until the commands with similar functionality (marked with ➡️ or 🔀) are ported over to v2. This includes bug-fixes, security patches and incremental updates as new ECS features are launched. However, once ported we will stop supporting the 🚫 dropped commands.

• ➡️ Available: We will port the command’s existing functionality over but the name of the command might be different (e.g. push ➡ images push). We will continue to do bug-fixes, security patches, and incremental ECS feature updates until we have the equivalent functionality in v2.
• 🔀 Available with caveats: The functionality will exist in v2, however you’ll have a different workflow. You might instead have to modify your infrastructure as code and do a deployment, or the action will be part of another command. We will continue to do bug-fixes, security patches, and incremental ECS feature updates until we have the including workflow in v2.
• 🚫 Dropped: For these commands, you can expect no more active development. That means no bug fixes, security patches, or new features.

v1 to v2 migration path

use-case	v1 command	supported in v2?	solution in v2
Define your application's cluster configuration: name, region, launch type.	configure	🔀	ecs init will bootstrap your application's infrastructure as code.
Create a cluster.	up	➡️	ecs env init will deploy your project's infrastructure including your cluster. This action will create a cluster but also all other resources that's in your application. If you want to just create a cluster you can use ecs clusters create that behaves similarly to the AWS CLI.
Deletes a cluster.	down	➡️	ecs project delete will delete all the resources associated with your project including your cluster. If you want to only delete the cluster then you can use ecs clusters delete.
Change the number of container instances in your cluster.	scale	➡️	ecs cluster scale will provide this functionality.
Lists all of the running containers in your ECS cluster.	ps	➡️	ecs cluster ps, ecs app ps, ecs project ps will all allow you to list running containers, including in your cluster.
Push an image to an Amazon ECR repo.	push	➡️	ecs image push will provide the same functionality.
Pull an image from an Amazon ECR repo.	pull	➡️	ecs image pull will provide the same functionality.
List images in an Amazon ECR repo.	images	➡️	ecs image will be ported as is.
Creates an ECS task definition from your Compose file.	compose create	🚫	We won't support translating Compose files to Task Definitions anymore. Please take a look at the "Migrating to v2" section below to see how we're planning to support existing ECS resources.
Create a task ECS task from your Compose file and run it.	compose up	🚫	Same as above, we won't be translating from a Compose file to a Task Definition so this command won't be supported.
Start a task with container overrides.	compose run	🔀	We won't be finding container overrides from your Compose file, however you should be able to run a task with container overrides with ecs task run.
Starting a task from a task definition.	compose start	🔀	ecs task run will achieve this functionality, however we won't be starting tasks from a Compose file. You can also use ecs app deploy
Stops all running tasks in your cluster.	compose stop	🔀	ecs task stop will achieve this functionality, however we won't be stopping tasks from a Compose file.
Lists all the containers in your cluster that were started by the compose project.	compose ps	🔀	ecs cluster ps, ecs app ps, ecs project ps will list running containers. However, these commands don't take a Compose file as input.
Adjust the number of running tasks in your cluster.	compose scale	🔀	ecs task scale will scale tasks based on your task group. However, this command doesn't take a Compose file as input.
Manage your ECS service from your Compose file.	compose service	🚫	Mirrors all the subcommands above for but instead of ecs task <subcommand>, you can use ecs service <subcommand>.
Validate that your container instances are compatible with your task definition.	check-attributes	🚫	v2 won't support this feature.
Retrieves container logs from CloudWatch.	logs	➡️	ecs logs will be ported as is.
Create and use private registry credentials in your container definition.	registry-creds	🔀	v2 won't have an explicit command for private registry credentials. However, since you own the infrastructure as code, you'll be able to modify the infrastructure's code and setup the necessary secrets.
Run a ECS task locally.	local	➡️	ecs local will be ported over as is.

We’re planning on adding a ecs-cli migrate cluster command to v1 to move the ECS cluster and VPC created with ecs-cli up under a project. Under the hood, this command will add a tag to these resources so we can group them under the same namespace. This way a new application created with the v2 CLI can leverage the same cluster and VPC. It will also enable you to use the --project flag for any command that supports it. For example, you should be able to use ecs clusters scale --project myProject to change the number of container instances.

If you are a heavy user of ecs-cli compose <service> create, we are planning on adding a --file flag. This way you can transform your Compose file and ecs-params.yml to create a task-definition and optionally a service-definition JSON file. You can then use the operational commands such as ecs tasks ors ecs task-defs similar to the AWS CLI to push these resources.
If you use ecs-cli compose part of your CD scripts and want to migrate to v2, our recommendation is for you to add the generated task definition or service file to your repository, modify those instead, and then use the operation commands to deploy your changes.

Feedback

We would like to hear your thoughts on this draft direction for v2 of the CLI. Please let us know in the comments below. Specifically, we’d like to know:

• Are there any use-cases that we’re missing that you’d like to see part of the v2 CLI?
• Are you dependent on v1’s Docker Compose functionality to create ECS tasks and services? If so why?

This feedback is subject to the AWS Customer Agreement, particularly Section 8.5 (Suggestions).

---

[FernandoMiguel]

This is bril ✨
So happy to see the team taking big steps and making ECS even better

[ghost]

would be nice to have integration with SSM Session Manager, where you can easy connect to a running continuers default shell interactively via the cli.

[surminus]

If you build your applications through the Amazon ECS CLI, you’ll get some AWS best practices by default and have a smooth workflow for taking your applications from development to production

This sounds excellent. Having just started to look at potentially moving some older infrastructure over to ECS I've struggled to find a recommended way to configure and deploy, and judging by the number of other ECS CLI tools I've stumbled across out there I guess others have also struggled with that, too.

Personally I would love to see a model of deployment that includes pre & post tasks as part of configuration. A deployment of an app isn't just updating a task definition and service, it also includes running one-off tasks, like database migrations, notification hooks and resource tagging. If this could be defined in configuration, along with suitable "rollback" mechanisms, it could be incredibly powerful in a single tool.

I'm not sure if people do this in their CD pipelines instead, but this feels like it's trying to create a PaaS-like experience with the flexibility of AWS, so super excited to see where this goes!

[mikesir87]

So one question... if this is allowing composition of apps using TF/Pulumi/CDK, there's a good chance apps within a single project could have leveraging more than just ECS (one app is Lambda-driven, etc.). Does it still make sense to call it an ECS CLI at that point? Or are you still trying to limit the scope to ECS-based applications at this time?

[efekarakus]

@mikesir87 We definitely see the value of building a project that has both Lambda and container apps. The primary focus of v2 will be improving the ECS developer experience, guided experiences that starts with a container and builds the rest of the infrastructure around it, but that doesn’t preclude us from supporting Lambda apps in the future.

[kohidave]

Howdy ya'll! We've reached our first milestone for the v2 CLI! Check out our blog post for more details!

Wanna learn more? Check out our wiki.

[diablodale]

I'm disappointed to see the Gen2 CLI won't directly support docker-compose files. I understand that AWS wants vendor lock-in, yet I feel that it is premature to leave behind this defacto standard.

Keep support for docker-compose -- or eliminate it completely

I do not see value in having a --file flag of which you write something about a one-way transform. Why? Because there is no value in me using this transform, checking into my repo, and constantly redoing/patching gaps. If you the Gen2 CLI is not directly using docker-compose files, then don't do it at all. It will lead to dev/test effort to make this ---file feature for little/no customer benefit.
On to another topic.

Needs YAML task definitions

JSON is a great syntax for computers to talk to each other, but a horrible syntax for humans to use for configuration. Well known. ECS Gen 2 forcing use of a AWS task definition in JSON is measurably more difficult than to do the same thing in YAML. This means that the ECS Gen2 cli will be harder to use and more difficult to maintain projects using it. ECS-CLI Gen2 needs to support YAML-based task definitions.

Merging makes live easier

In my projects, the merging capabilities of docker-compose greatly ease my development, testing, and deployment. Any task definition syntax you support in ECS cli Gen2 should be able to be merged with other task definitions using clear rules. What rules? See docker-compose.

[mtibben]

Did you try to use ecs-cli v1 in production? It was frankly a disaster. The docker-compose abstractions don't map onto ECS well at all. ECS team did exactly the right thing by using the ECS primitives, and creating an opinionated workflow with V2. Haven't used it yet, but I'm excited by the change

[mikesir87]

I personally tried to use ecs-cli v1 with compose and I'll agree it was quite rough. As you mentioned, the abstractions were tough, but I do agree that it's sad to see Compose dropped, instead of further adopted.

With the support of the extension fields (x-*) in Compose, it does allow other vendors to support additional fields. Examples might be x-network-mode, x-target-groups, or whatever. Then, our devs could more easily use the same (or very similar) compose files for dev and deploy.

[diablodale]

@mtibben , no disaster here. A few bugs in the v1 cli that I fixed myself. I did have to make a workaround due to ecs-cli v1 providing scaling in a limited manner. ecs-cli v1 integrating the scaling feature caused its own limitation that I had to work around. So what did I do? I used the sam toolset to make a quick app and deployed it.

If a team is looking for comprehensive coordination, k8s is the solution to explore. Its trajectory will surpass ECS across the global marketplace. So this is a competitive scenario. Yes, AWS provides k8s services. But it also has the proprietary ECS of which this toolset is focused. ECS is a great service which AWS was leader and wants to maintain that. k8s was forced on AWS so to be a market player and offer a service customers wanted. There is a tension here; an internal rivalry.

ECS may be good for solutions where k8s is not a fit. And therefore a toolset that works with ECS is useful. The aws cli is a low-level. ecs cli v1 is a mid-level toolset. Teams need a mid-level toolset for ECS. I have concern that the ecs cli v2 concept is too broad, too highlevel, and restrictive aka opinionated.

I'm concerned with a greater amount of challenges to occur due to ecs cli v2 increasing the number of services being integrated. For example, are services like Codepipeline and Secrets Mgr required? Maybe Codepipeline is useful in a highlevel toolset, but midlevel? And the latter has no clear benefit over SSM params for the storage of a git repo token. Though the latter is a revenue generator; $5/year for that secret mgr secret. With only 60k using this new toolset, they've generated $300k in revenue. That will pay for two heads on the AWS team. Personally, I prefer to give the git token to Codepipeline as it natively supports storing, or to store the token in SSM for centralized management. If ecs cli v2 really must, then accept an arn::ssm or arn::secretsmanager for where the token is located. Let the customer choose and manage.

I acknowledge that integration is always a difficult part of a project. Restricting the number of dependencies/services to integrate with the cli v2 should be carefully evaluated based on the AWS resources available to adequately spec, dev, and test those integrations. I recently fixed and PR'd two simple bugs in the ecs cli v1. That I had to do those fixes myself, doesn't inspire confidence in me that AWS has adequately resourced a ecs-cli v2 project for even more integrations/complexity.

sam cli is available for those that want to create "applications" and "services". What is the clear benefit of ecs cli v2 over sam? If they are both tools that create "applications", then they should be the same tool and just have different outputs based on a flag. sam --dest ecsclassic, sam --dest fargate, sam --dest lambda, etc. Of course, this is an oversimplification, so think conceptually about what I'm communicating and not flags or specific implementation.

Some might say the docker-compose syntax/grammar is a pain to maintain in the ecs cli codebase. As I understand, ecs cli v1 used an open-source library libcompose to parse that grammar. AWS profited by taking open-source Docker and making proprietary ECS. This is an opportunity for AWS to give back to open-source. It would be trivial to allocate part of two heads to breathe life into libcompose and update it so that both AWS and the larger community can benefit.

As @mikesir87 wrote, there are established ways in the docker-compose grammar to support far more settings that were previously in ecs-params. Later versions of 2.x grammar enabled this. Of course, this is feature detail; I'm not restricting progress to be limited to just ecs-params settings. Should ecs-cli v2 support docker swarm things that are in the docker-compose v3.x grammar? Probably not. Should ecs-cli v2 support things in the docker-compose v2.x grammar...I say yes. Should ecs-cli coordinate...when anyone says coordinate...I believe it important to look at what is being coordinated/orchestrated and choose the appropriate toolset/service for that. Again, think conceptual here...not specific implementation.

[efekarakus]

Hi everyone!

Docker Compose is a great tool to run your applications locally, and we think we can do a lot more for your local ECS experience with Compose. However, as mentioned above it becomes difficult to model ECS concepts and other AWS primitives within the confines of a Compose file. That’s why over time, in the ecs-cli v1, the ecs-params.yml file started getting more and more fields. This meant that the local experience and what’s running in production also started diverging.

sam cli is available for those that want to create "applications" and "services". What is the clear benefit of ecs cli v2 over sam?

The CLI v1 doesn’t take a stance on how to model containerized applications. You need to define and bring in additional AWS resources on your own. The sam CLI greatly simplifies integrating other services with Lambda but the unit of abstraction is individual AWS resources. With v2 we’re trying to move from “infrastructure as code” to “architecture as code”. We’d like to provide common application patterns used in the industry for developers to quickly start building applications with AWS best-practices baked in. While our focus is on adding this new application-level modeling, our next phase is going to be porting and enhancing the operation commands from v1 to v2 (inspecting service health, showing alarms and interesting metrics, etc). We want the CLI to help you for the entire application life-cycle including observability, and not just for deployments and builds.

For example, are services like Codepipeline and Secrets Mgr required? Maybe Codepipeline is useful in a highlevel toolset, but midlevel? And the latter has no clear benefit over SSM params for the storage of a git repo token.

We don’t want to force you into integrating with any service you don’t want! The patterns provided and the pipeline commands are available for you as a way to quickly and sustainably deploy your applications. We strive to keep the cost to a minimum with our patterns while still providing best-practices, and exploring visibility into the cost of your applications with the pricing command. To be clear, our incentives are 100% not driving costs, especially surreptitiously. We want to make ECS the best place to deploy your applications, that’s our only goal and that’s how our impact is measured - that almost always involves helping to lower your cost of ownership in any way that we can. Just as an example - we recently removed NAT gateways from our default templates because we thought they were too expensive.

If you have use-cases that don't fit into one of our patterns, we’d like for you to be able to define your own pattern so that you can customize your integrations. You can also use the individual commands such as ecs-preview app deploy to write your own CD scripts without leveraging the pipeline command that uses CodePipeline.

The v1 CLI will remain available, so if it already works for your use-case you don’t need to migrate to v2. We’ve shifted our resources over the past few months to developing v2 and it’s now in preview! We’d love for you to give it a spin and leave us feedback on the vision.

[clareliguori]

ECS CLI v2 is now in preview:
https://aws.amazon.com/about-aws/whats-new/2019/12/amazon-elastic-container-service-launches-a-new-cli-to-launch-and-manage-containerized-applications-easier/

[srrengar]

hi everyone, we've renamed the ECS CLI v2 to AWS Copilot and have added a bunch of new functionality. Check out our latest blog post here - https://aws.amazon.com/blogs/containers/introducing-aws-copilot/

[mwarkentin]

@srrengar Thanks! Now that copilot is available - are there other things that you think should be available before this issue is closed or does it make sense to move to dedicated issues for new features?

[JohnPreston]

I'm disappointed to see the Gen2 CLI won't directly support docker-compose files. I understand that AWS wants vendor lock-in, yet I feel that it is premature to leave behind this defacto standard.

Keep support for docker-compose -- or eliminate it completely

I do not see value in having a --file flag of which you write something about a one-way transform. Why? Because there is no value in me using this transform, checking into my repo, and constantly redoing/patching gaps. If you the Gen2 CLI is not directly using docker-compose files, then don't do it at all. It will lead to dev/test effort to make this ---file feature for little/no customer benefit.
On to another topic.

Needs YAML task definitions

JSON is a great syntax for computers to talk to each other, but a horrible syntax for humans to use for configuration. Well known. ECS Gen 2 forcing use of a AWS task definition in JSON is measurably more difficult than to do the same thing in YAML. This means that the ECS Gen2 cli will be harder to use and more difficult to maintain projects using it. ECS-CLI Gen2 needs to support YAML-based task definitions.

Merging makes live easier

In my projects, the merging capabilities of docker-compose greatly ease my development, testing, and deployment. Any task definition syntax you support in ECS cli Gen2 should be able to be merged with other task definitions using clear rules. What rules? See docker-compose.

I totally agree with what @diablodale said above: I was about to switch to copilot when it got announced a few weeks after I started working on my own project, thought about stopping it all together after the docker ecs-plugin announcement, but, dropped the idea of using either for lack of docker-compose support (and ecs-plugin expects ARNs, so no thanks :( )

If folks (@diablodale | @mikesir87) are interested in a tool that focuses on docker-compose v3 syntax support and ECS deployment, and makes the integration to other AWS services easier and follows for these the CloudFormation syntax, have a look at ECS ComposeX.

Note: I was just looking to see if there were any news on docker-compose support. I am only ever trying to get feedback on ComposeX

[srrengar]

Hello everyone! We're excited to announce that the AWS Copilot CLI is now generally available v1.0.0 🥳! To learn more about the CLI: https://aws.github.io/copilot-cli/