codedeploy-ecs-v2-handel-extension

This repository contains a Handel extension which creates a CodeDeploy application and a multi-service ECS cluster. The CodeDeploy application deploys to the ECS cluster using the blue/green deployment type.

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. This extension also takes care of setting up a blue/green deployment in CodeDeploy.

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.

Another lambda is also generated which can be run manually to create a new deployment to your ECS cluster. The name of this lambda is <stack_name>-create-deployment.

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: 2

name: codedeploy-ecs-example

extensions: # This tells Handel to import this extension
  codedeploy: codedeploy-ecs-handel-extension-v2
    
environments:
  dev:
    ecsCluster:
      type: 'codedeploy::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
      codedeploy:
        termination_wait_time: 30 # Optional. Specify how long (in minutes) to wait before terminating old instances. Default is 60
        time_before_auto_stop: 30 # Optional. Specify how long (in minutes) to wait before the deployment will be stopped automatically. 
                                  # For a deployment to succeed, the user must manually choose to continue after the test endpoint is configured.
                                  # Default is 60
      runscope_tests: # Optional. Keep in mind that AWS Lambda has a 15 minute maximum timeout, meaning that your max_allow_retries multiplied
                      # by your retry_delay should not be more than 15 minutes and should also allow time for the tests to run.
        max_allowable_retries: 3 # Required. The number of maximum times to retry the runscope tests if they fail. Default is 0
        retry_delay: 60 # Required. The amount of time, in seconds, to wait between retries. Default is 0                       
      # See https://handel.readthedocs.io/en/latest/supported-services/ecs.html for configuring load balancing, logging, and tagging

Image Names

This extension only supports images stored in your AWS account's EC2 Container Registry (ECR)

Reference an image as follows:

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

Notes

Since CloudFormation does not yet support creating CodeDeploy Blue/Green ECS deployments, the ECS services and the CodeDeploy application were created using the aws-sdk. This means that simply deleting the CloudFormation stack will not delete these resources. These resources must be deleted manually.