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. More information here.

• service: An ECS construct that defines a group of running instances of a configured task definition. 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. As an example, applications may have staging and production environments, as well as running a web server, background jobs, and other various tasks, each of which would be configured as a target. If an application had a staging and production environment along with a web server and background worker for each, the deploy targets might 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.default_docker_image = 'your_image'
  config.aws.ecs_default_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. You will either need to create the file ~/.aws/credentials:

[default]
aws_access_key_id=YOUR_ACCESS_KEY_ID
aws_secret_access_key=YOUR_SECRET_ACCESS_KEY

Or you can manually build an Aws::Credentials object and configure it manually in your broadside.conf.rb file:

Broadside.configure do |config|
  config.aws.credentials = Aws::Credentials.new('access_key', 'secret_key')
end

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

Broadside can setup your initial 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 or even the AWS GUI.