Upgrading to 0.11.0

As of 0.11.0, Empire uses CloudFormation to provision AWS resources. The existing non-CloudFormation scheduler is now deprecated and will be removed in the 1.0 release of Empire. Existing users are encouraged to migrate their applications to the new CloudFormation backend.

Why?

When we first built Empire, ECS had just been made generally available and CloudFormation didn't have support for any of the ECS resources, so we had to use the raw AWS api's to provision services and task definitions.

Over time, this has grown increasingly cumbersome to maintain, and forced Empire to become a state manager, like Terraform and CloudFormation. Moving resource state management to CloudFormation opens up a lot of possibilities for Empire moving forward, since it reduces the scope of what we have to build and maintain. It also fixes a number of long standing annoyances when using Empire, like the inability to easily find ECS services and ELB's for an application.

What about existing applications?

With the 0.11.0 release, CloudFormation becomes the default backend for new apps, but existing applications will continue to use the old backend, until you migrate those applications to the CloudFormation backend. You can follow the steps outlined in the Scheduler Migration Guide to migrate applications.

Upgrading

Moving to the CloudFormation backend will require some addition IAM permissions and AWS resources:

Resources

• EMPIRE_S3_TEMPLATE_BUCKET: This should be the name of an S3 bucket that Empire can use to store CloudFormation templates.
• EMPIRE_CUSTOM_RESOURCES_TOPIC: This should be the ARN of an SNS topic that the CloudFormation backend will use to send requests to create Custom::InstancePort resources.
• EMPIRE_CUSTOM_RESOURCES_QUEUE: This should be the queue url of an SQS queue that is subscribed to the SNS topic above. Empire will poll this queue for custom resources to provision.

It's recommended that you also set the EMPIRE_ENVIRONMENT variable to something meaningful (e.g. production or staging). Empire will use this a prefix to the names of CloudFormation stacks that get created. If you're running multiple environments in a single AWS account, be sure to set this.

Permissions

Additionally, you'll need to add some extra permissions to Empire's IAM policy. Here's an example of the IAM statements that you should add:

{
  "Effect": "Allow",
  "Action": [
    "sqs:ReceiveMessage",
    "sqs:DeleteMessage"
  ],
  "Resource": { "Fn::GetAtt": ["CustomResourcesQueue", "Arn"] }
},
{
  "Effect": "Allow",
  "Action": [
    "sns:Publish"
  ],
  "Resource": { "Ref": "CustomResourcesTopic" }
},
{
  "Effect": "Allow",
  "Action": [
    "s3:PutObject",
    "s3:PutObjectAcl",
    "s3:PutObjectVersionAcl",
    "s3:GetObject",
    "s3:GetObjectVersion",
    "s3:GetObjectAcl",
    "s3:GetObjectVersionAcl"
  ],
  "Resource": { "Fn::Join": ["", ["arn:aws:s3:::", { "Ref": "TemplateBucket" }, "/*"]] }
},
{
  "Effect": "Allow",
  "Action": [
    "cloudformation:CreateStack",
    "cloudformation:UpdateStack",
    "cloudformation:DeleteStack",
    "cloudformation:ListStackResources",
    "cloudformation:DescribeStackResource",
    "cloudformation:DescribeStacks"
  ],
  "Resource": ["*"]
},
{
  "Effect": "Allow",
  "Action": [
    "elasticloadbalancing:SetLoadBalancerPoliciesOfListener"
  ],
  "Resource": ["*"]
},
{
  "Effect": "Allow",
  "Action": [
    "route53:GetChange*"
  ],
  "Resource": "arn:aws:route53:::change/*"
},

Full a full list of IAM permissions that Empire requires, you can refer to the EmpirePolicy resource in the example CloudFormation stack