multi-service-ecs-handel-extension v0.0.2

multi-service-ecs-handel-extension

This repository contains a Handel extension which creates an ECS cluster with multiple ECS services

Motivation

Configuring a multi-service ECS cluster requires quite a bit of configuration (load balancer, target groups, security groups, routing, etc.). This extension configures all of this for you.

The other motivation is to create an IAM role that will allow for the manual creation of a CodeDeploy application and deployment group which uses the AWS blue/green ECS deployment type. AWS CloudFormation does not yet support blue/green ECS deployment types.

Also to support CodeDeploy blue/green deployments, this extension will generate a lambda which can be used by CodeDeploy to trigger runscope tests. This lambda looks in the AWS parameter store for the following variables <appName>.<environmentName>.runscope-trigger-url and <appName>.<environmentName>.runscope-access-token.

Usage

To use this extension, add it to the extensions section of your Handel file, and then add the ecs service to your environment:

version: 1

name: multi-service-ecs-example

extensions: # This tells Handel to import this extension
  cluster: multi-service-ecs-handel-extension
    
environments:
  dev:
    ecsCluster:
      type: 'cluster::ecs' # You must use the <extensionName>::<serviceName> syntax here
      cluster: # Optional.
        key_name: example-key # Optional. The key used to ssh into this service
        instance_type: t2.small # Optional. default is 't2.micro'
      services: # Required. 
      - name: service1 # Required.
        launch_type: EC2 # Optional. Default is 'EC2'
        auto_scaling: # Required.
          min_tasks: 2 # Required. This extension assumes that the desired task count = min_tasks
          max_tasks: 4 # Required.
          scaling_policies: # Optional. Configure scaling policies
          - type: up
            adjustment:
              value: 1
            alarm:
              metric_name: CPUUtilization
              comparison_operator: GreaterThanThreshold
              threshold: 70
          - type: down
            adjustment:
              value: 1
            alarm:
              metric_name: CPUUtilization
              comparison_operator: GreaterThanThreshold
              threshold: 30
        task_definition: # Required.
          name: exampleTask # Required.
          network_mode: bridge # Optional. Default is 'bridge'
          container: # Required.
            name: exampleContainer # Required
            image_name: brogerm/handel-multi-service-ecs-example # Optional. The Docker image that should be executed as the task
            max_mb: 2048 # Optional. Default: 128. The amount of memory in MB to allocate to the task
            cpu_units: 1024 # Optional. Default: 100. The amount of CPU units to allocate to the task. 1 vCPU = 1024
            port_mappings: # Optional. 
              - 8081
            routing: # Optional. This will configure a load balancer listener rule to route traffic between services
              base_path: '/basepath1/*'
              health_check_path: '/xhealth'
            environment_variables: # Optional.
              REGION: us-west-2
      # See https://handel.readthedocs.io/en/latest/supported-services/ecs.html for configuring load balancing, logging, and tagging

Image Names

The image_name parameter can take several forms:

If you want to pull a public image from somewhere like DockerHub, just reference the image name directly:

brogerm/handel-multi-service-ecs-example

If you want to reference an image in your AWS account’s EC2 Container Registry (ECR), reference it like this:

# The <account> piece will be replaced with your account's long ECR repository name
<account>/handel-multi-service-ecs-example

If you don’t specify an image_name, this extension will automatically choose an image name for you based on your Handel naming information. It will use the following image naming pattern:

<appName>-<serviceName>-<containerName>:<environmentName>

For example, if you don’t specify an image_name in the above example Handel file, the image this extension will look for is the following:

multi-service-ecs-example-ecsCluster-exampleContainer:dev