Merge remote-tracking branch 'upstream/master' into always-output-events

Author: Patrick Robinson

README.md

@@ -1,4 +1,4 @@
-# ECS Deploy Buildkite Plugin (Alpha) ![Build status](https://badge.buildkite.com/67da940833c8744761259918c52d4a005e2b5599a173d1e131.svg?branch=master)
+# ECS Deploy Buildkite Plugin ![Build status](https://badge.buildkite.com/67da940833c8744761259918c52d4a005e2b5599a173d1e131.svg?branch=master)
 
 A [Buildkite plugin](https://buildkite.com/docs/agent/v3/plugins) for deploying to [Amazon ECS](https://aws.amazon.com/ecs/).
 
@@ -7,8 +7,6 @@ A [Buildkite plugin](https://buildkite.com/docs/agent/v3/plugins) for deploying
 * Updates the ECS service to use the new task definition ([`update-service`](http://docs.aws.amazon.com/cli/latest/reference/ecs/update-service.html))
 * Waits for the service to stabilize ([`wait services-stable`](http://docs.aws.amazon.com/cli/latest/reference/ecs/wait/services-stable.html))
 
-_The ECS service must have been created before using this plugin._
-
 ## Example
 
 ```yml
@@ -17,7 +15,7 @@ steps:
     concurrency_group: "my-service-deploy"
     concurrency: 1
     plugins:
-      - ecs-deploy#v1.1.0:
+      - ecs-deploy#v1.2.0:
           cluster: "my-ecs-cluster"
           service: "my-service"
           task-definition: "examples/hello-world.json"
@@ -53,29 +51,67 @@ Example: `"my-task"`
 
 ### `image`
 
-The Docker image to deploy.
+The Docker image to deploy. This can be an array to substitute multiple images in a single container definition.
+
+Examples:
+`"012345.dkr.ecr.us-east-1.amazonaws.com/my-service:123"`
+
+```yaml
+image:
+  - "012345.dkr.ecr.us-east-1.amazonaws.com/my-service:123"
+  - "012345.dkr.ecr.us-east-1.amazonaws.com/nginx:123"
+```
+
+### `task-role-arn` (optional)
 
-Example: `"012345.dkr.ecr.us-east-1.amazonaws.com/my-service:123"`
+An IAM ECS Task Role to assign to tasks.
+Requires the `iam:PassRole` permission for the ARN specified.
 
-### `target-group`
+### `target-group` (optional)
 
 The Target Group ARN to map the service to.
 
 Example: `"arn:aws:elasticloadbalancing:us-east-1:012345678910:targetgroup/alb/e987e1234cd12abc"`
 
-### `target-container-name`
+### `target-container-name` (optional)
 
 The Container Name to forward ALB requests to.
 
-### `target-container-port`
+### `target-container-port` (optional)
 
 The Container Port to forward requests to.
 
+### `execution-role` (optional)
+
+The Execution Role ARN used by ECS to pull container images and secrets.
+
+Example: `"arn:aws:iam::012345678910:role/execution-role"`
+
+Requires the `iam:PassRole` permission for the execution role.
+
+### `deployment-configuration` (optional)
+
+The minimum and maximum percentage of tasks that should be maintained during a deployment. Defaults to `100/200`
+
+Example: `"0/100"`
+
 ## AWS Roles
 
-Requires the following AWS roles to be granted to the agent running this step:
+At a minimum this plugin requires the following AWS permissions to be granted to the agent running this step:
+
+```yml
+Policy:
+  Statement:
+  - Action:
+    - ecr:DescribeImages
+    - ecs:DescribeServices
+    - ecs:RegisterTaskDefinition
+    - ecs:UpdateService
+    Effect: Allow
+    Resource: '*'
+```
 
-* TODO
+This plugin will create the ECS Service if it does not already exist, which additionally requires the `ecs:CreateService` permission.
 
 ## Developing
 

examples/multiple-images.json

@@ -0,0 +1,26 @@
+[
+    {
+        "essential": true,
+        "image": "amazon/amazon-ecs-sample",
+        "memory": 100,
+        "name": "sample",
+        "portMappings": [
+            {
+                "containerPort": 80,
+                "hostPort": 80
+            }
+        ]
+    },
+    {
+        "essential": true,
+        "image": "amazon/amazon-ecs-sample",
+        "memory": 100,
+        "name": "sample",
+        "portMappings": [
+            {
+                "containerPort": 80,
+                "hostPort": 80
+            }
+        ]
+    }
+]

hooks/command

@@ -1,18 +1,54 @@
 #!/bin/bash
 set -euo pipefail
 
+# Reads either a value or a list from plugin config
+function plugin_read_list() {
+  prefix_read_list "BUILDKITE_PLUGIN_ECS_DEPLOY_$1"
+}
+
+# Reads either a value or a list from the given env prefix
+function prefix_read_list() {
+  local prefix="$1"
+  local parameter="${prefix}_0"
+
+  if [[ -n "${!parameter:-}" ]]; then
+    local i=0
+    local parameter="${prefix}_${i}"
+    while [[ -n "${!parameter:-}" ]]; do
+      echo "${!parameter}"
+      i=$((i+1))
+      parameter="${prefix}_${i}"
+    done
+  elif [[ -n "${!prefix:-}" ]]; then
+    echo "${!prefix}"
+  fi
+}
+
 cluster=${BUILDKITE_PLUGIN_ECS_DEPLOY_CLUSTER?}
 task_family=${BUILDKITE_PLUGIN_ECS_DEPLOY_TASK_FAMILY?}
 service_name=${BUILDKITE_PLUGIN_ECS_DEPLOY_SERVICE?}
-image=${BUILDKITE_PLUGIN_ECS_DEPLOY_IMAGE?}
+images=()
+while read -r line ; do
+  [[ -n "$line" ]] && images+=("$line")
+done <<< "$(plugin_read_list IMAGE)"
 task_definition=${BUILDKITE_PLUGIN_ECS_DEPLOY_TASK_DEFINITION?}
 desired_count=${BUILDKITE_PLUGIN_ECS_DEPLOY_DESIRED_COUNT:-"1"}
 task_role_arn=${BUILDKITE_PLUGIN_ECS_DEPLOY_TASK_ROLE_ARN:-""}
 target_group=${BUILDKITE_PLUGIN_ECS_DEPLOY_TARGET_GROUP:-""}
-# Resolve any runtime environment variables it has
-target_group=$(eval "echo $target_group")
+load_balancer_name=${BUILDKITE_PLUGIN_ECS_DEPLOY_LOAD_BALANCER_NAME:-""}
 target_container=${BUILDKITE_PLUGIN_ECS_DEPLOY_TARGET_CONTAINER_NAME:-""}
 target_port=${BUILDKITE_PLUGIN_ECS_DEPLOY_TARGET_CONTAINER_PORT:-""}
+execution_role=${BUILDKITE_PLUGIN_ECS_DEPLOY_EXECUTION_ROLE:-""}
+
+# Resolve any runtime environment variables it has
+target_group=$(eval "echo $target_group")
+load_balancer_name=$(eval "echo $load_balancer_name")
+
+deployment_config=${BUILDKITE_PLUGIN_ECS_DEPLOY_DEPLOYMENT_CONFIGURATION:-"100/200"}
+# shellcheck disable=SC2206
+min_max_percent=(${deployment_config//\// })
+min_deploy_perc=${min_max_percent[0]}
+max_deploy_perc=${min_max_percent[1]}
 
 function create_service() {
     local cluster_name=$1
@@ -22,10 +58,18 @@ function create_service() {
     local target_group_arguments
     target_group_arguments=$(generate_target_group_arguments "$5" "$6" "$7")
 
+    # shellcheck disable=SC2016
     service_defined=$(aws ecs describe-services --cluster "$cluster_name" --service "$service_name" --query 'services[?status==`ACTIVE`].status' --output text |wc -l)
     if [[ $service_defined -eq 0 ]]; then
         echo "--- :ecs: Creating a Service $service_name in cluster $cluster_name"
-        aws ecs create-service --cluster "$cluster_name" --service-name "$service_name" --task-definition "$task_definition" --desired-count "$desired_count" $target_group_arguments
+        # shellcheck disable=SC2086
+        aws ecs create-service \
+        --cluster "$cluster_name" \
+        --service-name "$service_name" \
+        --task-definition "$task_definition" \
+        --desired-count "$desired_count" \
+        --deployment-configuration "maximumPercent=${max_deploy_perc},minimumHealthyPercent=${min_deploy_perc}" \
+        $target_group_arguments
     fi
 }
 
@@ -34,21 +78,33 @@ function generate_target_group_arguments() {
     local target_container=$2
     local target_port=$3
     local target_group_arguments=""
-    if [[ -n $target_group ]] && [[ -n $target_container ]] && [[ -n $target_port ]]; then
-      target_group_arguments="--load-balancers targetGroupArn=${target_group},containerName=${target_container},containerPort=${target_port}"
+    if [[ -n $target_container ]] && [[ -n $target_port ]]; then
+      local load_balancer_ref=""
+      if [[ -n $target_group ]]; then
+        load_balancer_ref="targetGroupArn=${target_group}"
+      elif [[ -n $load_balancer_name ]]; then
+        load_balancer_ref="loadBalancerName=${load_balancer_name}"
+      else
+        echo "+++ ^^^"
+        # shellcheck disable=SC2016
+        echo '+++ You must specify either `target-group` or `load-balancer-name`'
+        exit 1
+      fi
+
+      target_group_arguments="--load-balancers ${load_balancer_ref},containerName=${target_container},containerPort=${target_port}"
     fi
     echo "$target_group_arguments"
 }
 
 ## This is the template definition of your containers
-container_definitions_json=$(jq --arg IMAGE "$image" \
-'.[0].image=$IMAGE' \
-"$task_definition"
-)
-
-echo "jq --arg IMAGE $image \
-'.taskDefinition.containerDefinitions[0].image=\$IMAGE' \
-$task_definition" > /tmp/foo
+image_idx=0
+container_definitions_json=$(cat "${task_definition}")
+for image in "${images[@]}"; do
+  container_definitions_json=$(echo "$container_definitions_json" | jq --arg IMAGE "$image" \
+  ".[${image_idx}].image=\$IMAGE"
+  )
+  image_idx=$((image_idx+1))
+done
 
 echo "--- :ecs: Registering new task definition for ${task_family}"
 register_command="aws ecs register-task-definition \
@@ -58,6 +114,11 @@ register_command="aws ecs register-task-definition \
 if [[ -n "${task_role_arn}" ]]; then
     register_command+=" --task-role-arn ${task_role_arn}"
 fi
+
+if [[ -n "${execution_role}" ]]; then
+    register_command+=" --execution-role-arn ${execution_role}"
+fi
+
 json_output=$(eval "$register_command")
 register_exit_code=$?
 
@@ -73,13 +134,17 @@ echo "Registered ${task_family}:${task_revision}"
 # Create service if it doesn't already exist
 create_service "$cluster" "${task_family}:${task_revision}" "$service_name" "$desired_count" "$target_group" "$target_container" "$target_port"
 
+# shellcheck disable=SC2016
 lb_config=$(aws ecs describe-services --cluster "$cluster" --services "$service_name" --query 'services[?status==`ACTIVE`]' |jq -r '.[0].loadBalancers[0]')
-error="+++ Cannot update a service to add a load balancer. First delete the service and then run again, or rename the service to force a new one to be created"
+error="+++ ^^^
++++ Cannot update a service to add/remove a load balancer. First delete the service and then run again, or rename the service to force a new one to be created"
 
 # No easy way to tell if the target group has changed, since describe-services only returns the load balancer name
-if [[ "$lb_config" == "null" ]] && [[ -n $target_group ]]; then
-  echo "$error"
-  exit 1
+if [[ "$lb_config" == "null" ]]; then
+  if [[ -n "$target_group" ]] || [[ -n "$load_balancer_name" ]]; then
+    echo "$error"
+    exit 1
+  fi
 fi
 
 if [[ "$lb_config" == "null" ]]; then
@@ -88,6 +153,12 @@ if [[ "$lb_config" == "null" ]]; then
 elif [[ $(echo "$lb_config" |jq -r '.containerName') != "$target_container" ]] || [[ $(echo "$lb_config" |jq -r '.containerPort') -ne $target_port ]]; then
   echo "$error"
   exit 1
+elif [[ -n "$target_group" ]] && [[ $(echo "$lb_config" |jq -r '.targetGroupArn') != "$target_group" ]]; then
+  echo "$error"
+  exit 1
+elif [[ -n "$load_balancer_name" ]] && [[ $(echo "$lb_config" |jq -r '.loadBalancerName') != "$load_balancer_name" ]]; then
+  echo "$error"
+  exit 1
 fi
 
 echo "--- :ecs: Updating service for ${service_name}"

plugin.yml

@@ -15,17 +15,23 @@ configuration:
     task-family:
       type: string
     image:
-      type: string
+      type: [ string, array ]
     desired-count:
       type: string
     task-role-arn:
       type: string
     target-group:
       type: string
+    load-balanccer-name:
+      type: string
     target-container-name:
       type: string
     target-container-port:
       type: integer
+    execution-role:
+      type: string
+    deployment-config:
+      type: string
   required:
     - cluster
     - service