ecs-deploy simplifies deployments on Amazon ECS by providing a convinience CLI tool for complex actions, which are executed pretty often.
- support for complex task definitions (e.g. multiple containers & task role)
- easily redeploy the current task definition (including docker pull of eventually updated images)
- deploy new versions/tags or all containers or just a single container in your task definition
- scale up or down by adjusting the desired count of running tasks
- add or adjust containers environment variables
- run one-off tasks from the CLI
- automatically monitor deployments in New Relic
Deploy a new version of your service:
$ ecs deploy my-cluster my-service --tag 1.2.3
Redeploy the current version of a service:
$ ecs deploy my-cluster my-service
Scale up or down a service:
$ ecs scale my-cluster my-service 4
The project is availably on PyPI. Simply run:
$ pip install ecs-deploy
As ecs-deploy is based on boto3 (the official AWS Python library), there are several ways to configure and store the authentication credentials. Please read the boto3 documentation for more details (http://boto3.readthedocs.org/en/latest/guide/configuration.html#configuration). The simplest way is by running:
$ aws configure
Alternatively you can pass the AWS credentials (via --access-key-id and --secret-access-key) or the AWS configuration profile (via --profile) as options when you run ecs.
Currently the following actions are supported:
Redeploy a service either without any modifications or with a new image, environment variable and/or command definition.
Scale a service up or down and change the number of running tasks.
Run a one-off task based on an existing task-definition and optionally override command and/or environment variables.
For detailed information about the available actions, arguments and options, run:
$ ecs deploy --help $ ecs scale --help $ ecs run --help
All examples assume, that authentication has already been configured.
To redeploy a service without any modifications, but pulling the most recent image versions, run the follwing command. This will duplicate the current task definition and cause the service to redeploy all running tasks.:
$ ecs deploy my-cluster my-service
To change the tag for all images in all containers in the task definition, run the following command:
$ ecs deploy my-cluster my-service -t 1.2.3
To change the image of a specific container, run the following command:
$ ecs deploy my-cluster my-service --image webserver nginx:1.11.8
This will modify the webserver container only and change its image to "nginx:1.11.8".
The -i or --image option can also be passed several times:
$ ecs deploy my-cluster my-service -i webserver nginx:1.9 -i application my-app:1.2.3
This will change the webserver's container image to "nginx:1.9" and the application's image to "my-app:1.2.3".
To add a new or adjust an existing environment variable of a specific container, run the following command:
$ ecs deploy my-cluster my-service -e webserver SOME_VARIABLE SOME_VALUE
This will modify the webserver container definition and add or overwrite the environment variable SOME_VARIABLE with the value "SOME_VALUE". This way you can add new or adjust already existing environment variables.
You can add or change multiple environment variables at once, by adding the -e (or --env) options several times:
$ ecs deploy my-cluster my-service -e webserver SOME_VARIABLE SOME_VALUE -e webserver OTHER_VARIABLE OTHER_VALUE -e app APP_VARIABLE APP_VALUE
This will modify the definition of two containers. The webserver's environment variable SOME_VARIABLE will be set to "SOME_VALUE" and the variable OTHER_VARIABLE to "OTHER_VALUE". The app's environment variable APP_VARIABLE will be set to "APP_VALUE".
To change the command of a specific container, run the following command:
$ ecs deploy my-cluster my-service --command webserver "nginx"
This will modify the webserver container and change its command to "nginx".
To change or set the role, the service's task should run as, use the following command:
$ ecs deploy my-cluster my-service -r arn:aws:iam::123456789012:role/MySpecialEcsTaskRole
This will set the task role to "MySpecialEcsTaskRole".
To change the number of running tasks and scale a service up and down, run this command:
$ ecs scale my-cluster my-service 4
To run a one-off task, based on an existing task-definition, run this command:
$ ecs run my-cluster my-task
You can define just the task family (e.g. my-task
) or you can run a specific revision of the task-definition (e.g.
my-task:123
). And optionally you can add or adjust environment variables like this:
$ ecs run my-cluster my-task:123 -e my-container MY_VARIABLE "my value"
You can override the command definition via option -c
or --command
followed by the container name and the
command in a natural syntax, e.g. no conversion to comma-separation required:
$ ecs run my-cluster my-task -c my-container "python some-script.py param1 param2"
With ECS deploy you can track your deployments automatically. Currently only New Relic is supported:
To record a deployment in New Relic, you can provide the the API Key (Attention: this is a specific REST API Key, not the license key) and the application id in two ways:
Via cli options:
$ ecs deploy my-cluster my-service --newrelic-apikey ABCDEFGHIJKLMN --newrelic-appid 1234567890
Or implicitly via environment variables NEW_RELIC_API_KEY
and NEW_RELIC_APP_ID
$ export NEW_RELIC_API_KEY=ABCDEFGHIJKLMN $ export NEW_RELIC_APP_ID=1234567890 $ ecs deploy my-cluster my-service
Optionally you can provide an additional comment to the deployment via --comment "New feature X"
and the name of the user who deployed with --user john.doe