AWS Setup

Getting Started

Initial setup requires some background knowledge of how ECS operates. Refer to the AWS documentation if you are new to ECS.

Terminology

• task definition: An ECS construct defining a single application's container configurations. See more information here

• service: An ECS construct that defines a group of running instances of a configured task definition. See more information here

• target: An application can define multiple targets which may specify different commands to run, different docker images to spin up, a different scale, different environment variables, and so on. Commonly, applications may have staging and production environments, as well as running a web server, background jobs, and other various tasks. For instance, if an application defines a staging/production environment along with a web server and background worker, the deploy targets will be:

  staging_web
  staging_worker
  production_web
  production_worker
  

• family: The application name plus the deploy target, i.e. myappname_mytarget. When deploying a given target for your application, the family name is used to look up the corresponding task definition and service on ECS.

Application Setup

1. Within your application directory, Create a config/broadside.conf.rb file.
2. Copy in the sample configuration listed here:

Broadside.configure do |config|
  config.application = 'your_application_name'
  config.docker_image = 'your_image'
  config.ecs.cluster = 'your_cluster'
  config.targets = {}
end

1. Configure your deploy targets. We recommend using a name like environment_role, e.g. staging_web or production_worker. Each target should follow the format listed here.
2. See more configuration options.

ECS Setup

AWS Credentials

Broadside expects AWS credentials to exist in dotfiles as expected for aws cli. Essentially, you will need the following file:

~/.aws/credentials

[default]
aws_access_key_id=YOUR_ACCESS_KEY_ID
aws_secret_access_key=YOUR_SECRET_ACCESS_KEY

IAM Permissions

1. Broadside uses the AWS API and thus requires permissions to perform deployments. Here is a suitable IAM policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt12345",
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstances"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "Stmt12345",
            "Effect": "Allow",
            "Action": [
                "ecs:DeregisterTaskDefinition",
                "ecs:DescribeClusters",
                "ecs:DescribeContainerInstances",
                "ecs:DescribeServices",
                "ecs:DescribeTaskDefinition",
                "ecs:DescribeTasks",
                "ecs:ListClusters",
                "ecs:ListContainerInstances",
                "ecs:ListServices",
                "ecs:ListTaskDefinitionFamilies",
                "ecs:ListTaskDefinitions",
                "ecs:ListTasks",
                "ecs:Poll",
                "ecs:RegisterTaskDefinition",
                "ecs:RunTask",
                "ecs:StartTask",
                "ecs:StopTask",
                "ecs:SubmitContainerStateChange",
                "ecs:SubmitTaskStateChange"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

Service and Task Definition Setup

The Easy Way

Broadside can now setup your task_definition and service via the bootstrap command, provided you configured the task_definition_config and service_config in your target.

You may alternatively choose to handle the setup steps using terraform or aws cli.

The Really Annoying Way

If you refuse to bootstrap (we really recommend it), here are the steps for the AWS GUI setup:

1. In the ECS console, create a task definition for your application. The name of that task definition must match the family, e.g. APPNAME_DEPLOYTARGET
2. In the task definition, set up your containers:

• The first container of the task definition must have the same name as the family, and must run the primary application.
• Subsequent containers will be ignored by broadside.
• Volumes, links, and compute resources will be ignored by broadside.

1. If running a web application, optionally create an elastic load balancer.
2. Create a service named after the family, within the cluster that you specified in the broadside.conf.rb. Set the initial scale to 0.
3. Note that your cluster needs to have enough compute resources to handle your application, otherwise you will be unable to deploy it.