Skip to main content

Helper for registering new task definitions on AWS ECS and updating associated services.

Project description


ecs-task is an opinionated, but flexible tool for deploying to Amazon Web Service's Elastic Container Service.

It is built on the following premises:

  • ECS Services, load balancers, auto-scaling, etc. are managed elsewhere, e.g. Terraform, Cloudformation, etc.
  • Deploying to ECS is defined as:
    1. Update task definition with new image tag
    2. [Optional] Running any number of one-off Tasks, e.g. Django database migrations.
    3. [Optional] Updating Services to use the new Task Definition.
    4. [Optional] Updating Cloudwatch Event Targets to use the new Task Definition.
    5. Deregister old Task Definitions.
  • Applications manage their own Task/Container definitions and can deploy themselves to a pre-defined ECS Cluster.
  • The ability to rollback is important and should be as easy as possible.


pip install ecs-task

(Optionally, just copy to your project and install boto3).


This module is made up of a single class, ecs_task.ECSTask which is designed to be extended in your project. A basic example:

#!/usr/bin/env python
from ecs_task import ECSTask

class WebTask(ECSTask):
    task_definition = {
        "family": "web",
        "executionRoleArn": EXECUTION_ROLE_ARN,
        "containerDefinitions": [
                "name": "web",
                "image": "my_image:{image_tag}",
                "portMappings": [{"containerPort": 8080}],
                "cpu": 1024,
                "memory": 1024,
    update_services = [{"service": "web", "cluster": "my_cluster",}]

if __name__ == "__main__":

You could save this as _ecs/ and then execute it with python -m _ecs.web_dev --help

usage: [-h] {deploy,rollback,debug} ...

ECS Task

positional arguments:
    deploy              Register new task definitions using `image_tag`.
                        Update defined ECS Services, Event Targets, and run
                        defined ECS Tasks
    rollback            Deactivate current task definitions and rollback all
                        ECS Services and Event Targets to previous active
    debug               Dump JSON generated for class attributes.

optional arguments:
  -h, --help            show this help message and exit

Class attributes

A sub-class of ECSTask must include a task_definition to do anything. Any other attributes are optional. The following attributes are designed to be a 1-to-1 mapping to an AWS API endpoint via boto3. The values you provide will be passed as keyword arguments to the associated method with the correct Task Definition inserted. Any attribute that takes a list can make multiple calls to the given API.

A few additional attributes are available:

  • active_task_count: (int) the number of task definitions to keep active after a deployment. Default is 10.

  • sns_notification_topic_arn: (str) the ARN for an SNS topic which will receive a message whenever an AWS API call is executed. This can be used to trigger notifications or perform additional tasks related to the deployment. The message is in the format:

        "client": client,  # boto3 client (usually "ecs")
        "method": method,  # method called (e.g., "update_service")
        "input": kwargs,   # method input as a dictionary
        "result": result   # results from AWS API
  • notification_method_blacklist_regex (re.Pattern) a pattern of methods to avoid sending notifications for. Default is re.compile(r"^describe_|get_|list_|.*register_task")

Command Interface

Each class is intended to be "executable" by calling .main(). Multiple class instances can be called in a given file by using:

if __name__ == "__main__":
    for klass in [WebTask, WorkerTask]:


Just prints the value of each class attribute to the console. Useful if you're doing some class inheritance and want to verify what you have before running against AWS.


The deploy subcommand accepts an additional argument, image_tag which is used to update any Container Definitions in the task which have the {image_tag} placeholder. It will:

  1. Register a new Task Definition
  2. Run Tasks (as defined in run_tasks)
  3. Update Services (as defined in update_services)
  4. Update Event Targets (as defined in events__put_targets)
  5. Deregister any active Task Definitions older than active_task_count (by default, 10)


  1. Deregister the latest active Task Definition
  2. Update Services (as defined in update_services) with the previous active Task Definition
  3. Update Event Targets (as defined in events__put_targets) with the previous active Task Definition

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ecs-task-0.3.1.tar.gz (6.2 kB view hashes)

Uploaded source

Built Distribution

ecs_task-0.3.1-py2.py3-none-any.whl (6.5 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page