Home

Awesome

ECS Service

Overview

This tool aims to simplify the deployment of docker-based services on Amazon's ECS platform.

How it works

Creation/deployment of ECS services is backed by AWS Cloud Formation.

Every command in the tool maps to a stack operation in Cloud Formation.

To use ecs-service you need to use a Cloud Formation template which creates an ECS service along with a Task Definition.

When creating your service, you must supply this template along with the version of the service you wish to run. The tool will create a CF stack with the name you provide.

After the service is created, you can issue commands to update the running version of the service which will result in a stack update.

Instead of having a separate CF template per environment, the idea is to have a single template which works across all environments. Because the tool lets you supply parameters and environment variables to your docker container, your stack template can remain the same between environments.

Requirements

Installation

npm install -g ecs-service

AWS REGION

You must export the AWS region you are deploying your service to, or supply it via the -r parameter.

export AWS_REGION=us-east-1

AWS Credentials

The tool will use the standard credential chain used by other aws cli tools.

If you wish to supply credentials manually see Options

Supported Commands

Deploy Service

To create or update an existing service you must provide:

To deploy the service, use the following command:

$ ecs-service deploy [stackname] [version] [template_file] [params_file]

This command will create/update a CF stack with the provided stackname and supply the service version via the AppVersion parameter. For the remaining non-default parameters, it will use the parameter file.

The command will wait until the successful creation/update of the stack.

Supplying Environment Variables to your docker container

If your docker container is configured via Environment Variables you must supply them via the Container Definition's Environment property. This can be tedious to update when your environment variables change. Hardcoding environment specific values in your task definition would require you to maintain several copies of your task definition; one per environment.

ecs-service allows you to supply a env file when creating/updating services which will be used to populate the Container Definition's Environment property.

The --env-file parameter can be used to supply an env file containing all of your environment variables.

Example ENV file

EXTERNAL_SERVICE_URI=http://api.myservice.com
FOO=test
BAR=blah

Each line defines an environment variable.

Example Usage

Using the --env-file parameter, you can supply a env file which will be used to pass environment variables to your container.

$ ecs-service deploy [stackname] [version] [template_file] [params_file] --env-file <file>

This parameter can be used with any of the commands provided.

Encrypting Environment Variables

Encrypted environment variables can be supplied to your docker container using kms-env.

Update Service

If you need to run a new version of your service or update environment variables you can use the simpler run command. Instead of having to provide a template and parameter files you can use this command if you only need to adjust the version or scale of your service.

This command requires:

$ ecs-service update [stackname] [version]

This command will update your ecs service to use the specified version of your container image.

Environment Variables

As mentioned under the Deploy command, you can use the --env-file parameter to supply a file containing environment variables for your container.

Stop Service

To stop a service, you can issue the stop command which will set the desired count of your service to 0.

$ ecs-service stop [stackname]

Note: this will not remove/delete your ECS service or Task Definition.

Destroy Service

To completely remove the resources associates with your service stack you can use the destroy command.

This command will result in a stack deletion operation.

$ ecs-service destroy [stackname]

Optional Parameters

Setting the scale for your service

To specify the number of instances of your service to run, use the --scale parameter.

Example

To run two instances of an existing service called myservice we can issue the following command:

$ ecs-service update myservice 0.1.0 --scale 2

Specifying AWS Tags for the service stack

If you need your service stack to have associated tags, you can do so via the --tag-file parameter.

Example

A tag file is a JSON file with an object where the keys are names of tags to create and values are the tag values.

Example Tag File - tags.json

{
    "Owner": "Alice",
    "Project": "Top Secret"
}

Given the above tag file we can provide it via the --tag-file command as follows:

$ ecs-service deploy myservice 0.1.0 service.json params.json --tag-file tags.json

The above command will create myservice using the template in service.json with the tags Owner=Alice and Project=Top Secret

AWS Credentials

To supply credentials manually you can use the following parameters:

Using Profiles

Alternatively you can supply an AWS credential profile to use via: