Skip to content

Run any Django management command on an AWS Elastic Container Service (ECS) cluster.

License

Notifications You must be signed in to change notification settings

azavea/django-ecsmanage

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

57 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

django-ecsmanage

https://github.com/azavea/django-ecsmanage/workflows/CI/badge.svg?branch=develop

A Django app that provides a management command allowing you to run any other management command on an AWS Elastic Container Service (ECS) cluster.

With django-ecsmanage, you can easily run migrations and other one-off tasks on a remote cluster from the command line:

$ django-admin ecsmanage migrate

Table of Contents

Installation

Install from PyPi using pip:

$ pip install django-ecsmanage

Update INSTALLED_APPS in your Django settings to install the app:

INSTALLED_APPS = (
    ...
    'ecsmanage',
)

Configuration

Settings for the management command are kept in a single configuration dictionary in your Django settings named ECSMANAGE_ENVIRONMENTS. Each entry in ECSMANAGE_ENVIRONMENTS should be a key-value pair corresponding to a named environment (like default or production) and a set of AWS resources associated with that environment. For example:

ECSMANAGE_ENVIRONMENTS = {
    'default': {
        'TASK_DEFINITION_NAME': 'StagingAppCLI',
        'CONTAINER_NAME': 'django',
        'CLUSTER_NAME': 'ecsStagingCluster',
        'LAUNCH_TYPE': 'FARGATE',
        'PLATFORM_VERSION': '1.4.0',
        'SECURITY_GROUP_TAGS': {
            'Name': 'sgAppEcsService',
            'Environment': 'Staging',
            'Project': 'ProjectName'
        },
        'SUBNET_TAGS': {
            'Name': 'PrivateSubnet',
            'Environment': 'Staging',
            'Project': 'ProjectName'
        },
        'ASSIGN_PUBLIC_IP': 'DISABLED',
        'AWS_REGION': 'us-east-1',
    },
}

This configuration defines a single environment, named default, with associated AWS ECS resources.

Environments

The key name for an environment can be any string. You can use this name with the --env flag when running the command to run a command on a different environment. Take this ECSMANAGE_ENVIRONMENTS configuration as an example:

ECSMANAGE_ENVIRONMENTS = {
    'default': {
        'TASK_DEFINITION_NAME': 'StagingAppCLI',
        'CLUSTER_NAME': 'ecsStagingCluster',
        'SECURITY_GROUP_TAGS': {
            'Name': 'sgStagingAppEcsService',
        },
        'SUBNET_TAGS': {
            'Name': 'StagingPrivateSubnet',
        },
    },
    'production': {
        'TASK_DEFINITION_NAME': 'ProductionAppCLI',
        'CLUSTER_NAME': 'ecsProductionCluster',
        'SECURITY_GROUP_TAGS': {
            'Name': 'sgProductionAppEcsService',
        },
        'SUBNET_TAGS': {
            'Name': 'ProductionPrivateSubnet',
        },
    },
}

This configuration defines two environments, default and production. Using the above settings, you could run production migrations with the following command:

$ django-admin ecsmanage --env production migrate

If the --env argument is not present, the command will default to the environment named default.

AWS Resources

The following environment configuration keys help the management command locate the appropriate AWS resources for your cluster:

Key Description Default
TASK_DEFINITION_NAME The name of your ECS task definition. The command will automatically retrieve the latest definition.  
CONTAINER_NAME The name of the Django container in your ECS task definition. django
CLUSTER_NAME The name of your ECS cluster.  
SECURITY_GROUP_TAGS A dictionary of tags to use to identify a security group for your task.  
SUBNET_TAGS A dictionary of tags to use to identify a subnet for your task.  
ASSIGN_PUBLIC_IP Whether to automatically assign a public IP address to your task. Can be ENABLED or DISABLED. DISABLED
LAUNCH_TYPE The ECS launch type for your task. FARGATE
PLATFORM_VERSION The Fargate platform version, if LAUNCH_TYPE is FARGATE. LATEST
AWS_REGION The AWS region to run your task. us-east-1

Developing

Local development is managed with Python virtual environments. Make sure that you have Python 3.8+ and pip installed before starting.

Install the development package in a virtual environment:

$ ./scripts/update

Run the tests:

$ ./scripts/test