Welcome to ECS Compose-X documentation

PYPI_VERSION PyPI - License PY_DLS

CodeStyle TDD with pytest BDD with Behave

Code scan with SonarCloud BUILD

The no-code CDK for docker-compose & AWS ECS

Deploy your services to AWS ECS from your docker-compose files in 3 steps

  • Step 1. Install ECS Compose-x

  • Step 2. Use your existing docker-compose files. Optionally, add Compose-X extensions.

  • Step 3. Deploy to AWS with AWS CloudFormation

What does it do?

  • Automatically deploy applications to AWS using existing docker-compose files
    • Deploys multiple applications to AWS in a single command

    • Creates AWS resources such as EC2 Instances, ECS Clusters and Containers

    • Automatically configures IAM roles and Networking for secure and reliable access

  • Expand the definitions with AWS CloudFormation resources
    • For supported resources, supports full CloudFormation properties

    • For existing resources, will detect them and allow to use the Return Values with other components

  • Allows to use existing resources in your AWS Account

  • Can be extended with custom modules/hooks to customize the deployment process

  • Automatically rolls back the application in case of errors, to previous version or to a stable state

Install

# Inside a python virtual environment
python3 -m venv venv
source venv/bin/activate
pip install pip -U
pip install ecs-composex

# For your user only, without virtualenv
pip install ecs-composex --user

How is it different ?

There are a lot of similar tools out there, including published by AWS. So here are a few of the features that we think could be of interest to you.

Works with docker-compose

The most important thing for ECS Compose-X is to allow people to use the same compose files they use locally to spin services up in AWS ECS. Other tools, such as Copilot, require you to rewrite into their specific format and input.

Modularity and “Plug & Play”

The origin of ECS Compose-X was to provide developers with the ability of deploying an entire test stack from scratch. However, the reality is more that companies have already gotten VPC/Networking sorted out, other applications, services and resources already exist and new services need access to that existing infrastructure.

So with ECS-ComposeX we have since very early on , defined Lookup , which allows you to use your existing services and resources you have in AWS. Via API discovery, all the settings, configuration of those will be used to grant the necessary access and define configuration accordingly for your services to use these successfully.

ECS Compose-X on was written to make AWS accessible to developers and cloud engineers of all level. For developers, we hope that enables them to create new environment of their own and want to quickly iterate over it.

Note

When using Lookup , the resource in AWS will never be altered to avoid conflicts.

Deploy to AWS Fargate, AWS EC2 and ECS Anywhere

Since the beginning, the focus has been on running with AWS Fargate, as it is what allows developers least effort to deploying applications. But by users demand, the project was adapted to support deploying to existing EC2 based clusters, as well as on ECS Anywhere.

With the growing adoption of other ARM there is also now support to specify whether you want to run your services on AWS Fargate using Graviton processors.

See also

See how to enable ECS Anywhere with ecs.compute.platform

Easy compute definition

ECS Compose-X allows you to define which services should be running on EC2 / Fargate, use ARM64 or X86_64 architecture, CapacityProviders etc. for each individual service.

When using Lookup , it will also automatically detect configuration, which avoids configuration settings conflicts and errors.

Attributes auto-correct

A fair amount of the time, deployments via AWS CloudFormation, Ansible and other IaC will fail because of incompatible settings. This happened a number of times, with a lot of different AWS Services.

Whilst giving you the ability to use all properties of AWS CloudFormation objects, whenever possible, ECS Compose-X will understand how two services are connected and will auto-correct the settings for you.

For example, if you set the Log retention to be 42 days, which is invalid, it will automatically change that to the closest valid value (here, 30).

Using JSON Schema specifications

Docker Compose follows a well known, well documented and open source JSON Schema definition to ensure consistency in the compose files syntax, making it very accessible for all to use.

ECS Compose-X uses that schema definition to ensure compatibility with docker-compose , and uses JSON Schemas for extensions in order to ensure the compose files input are correct before doing any further processing.

Additional content

Modules and Source Code

Indices and tables

Credits

This package would not have been possible without the amazing job done by the AWS CloudFormation team! This package would not have been possible without the amazing community around Troposphere ! This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.