ECS Deploy Buildkite Plugin

A Buildkite plugin for deploying to Amazon ECS.

• Requires both aws and jq cli tools to be installed
• Registers a new task definition based on a given JSON file (register-task-definition)
• Updates the ECS service to use the new task definition (update-service)
• Waits for the service to stabilize (wait services-stable)

Example

steps:
  - label: ":ecs: :rocket:"
    concurrency_group: "my-service-deploy"
    concurrency: 1
    plugins:
      - ecs-deploy#v3.1.0:
          cluster: "my-ecs-cluster"
          service: "my-service"
          container-definitions: "examples/hello-world.json"
          task-family: "hello-world"
          image: "${ECR_REPOSITORY}/hello-world:${BUILDKITE_BUILD_NUMBER}"

Options

Required

cluster

The name of the ECS cluster.

Example: "my-cluster"

container-definitions

Experimental: Since version 3.0.0 you can skip this parameter and the container definitions will be obtained off the existing (latest) task definition. If this does not work for you, please open an issue in this repository.

The file path to the ECS container definition JSON file. This JSON file must be an array of objects, each corresponding to one of the images you defined in the image parameter.

Example: "ecs/containers.json"

[
    {
        "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
            }
        ]
    }
]

image

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"

image:
  - "012345.dkr.ecr.us-east-1.amazonaws.com/my-service:123"
  - "012345.dkr.ecr.us-east-1.amazonaws.com/nginx:123"

service

The name of the ECS service.

Example: "my-service"

task-family

The name of the task family.

Example: "my-task"

Optional

env (array)

An array of environment variables to add to every image's task definition in the NAME=VALUE format

execution-role

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.

region

The region we deploy the ECS Service to.

task-cpu (integer)

CPU Units to assign to the task (1024 constitutes a whole CPU). Example: 256 (1/4 of a CPU).

task-ephemeral-storage (integer)

Amount of GBs to assign in ephemeral storage to the task. Example: 25.

task-ipc-mode

IPC resource namespace to use in the task. If specified, should be one of host, task or none.

task-memory (integer)

Amount of memory (in Mbs) to allocate for the task. Example: 1024 (1Gb).

task-network-mode

Docker networking mode for the containers running in the task. If specified, should be one of bridge, host, awsvpc or none.

task-pid-mode

Process namespace to use for containers in the task. If specified, should be one of host or task.

task-role-arn

An IAM ECS Task Role to assign to tasks.

Requires the iam:PassRole permission for the ARN specified.

Fields inherited from the existing task definition

The following fields are automatically carried over from the latest active task definition and forwarded to register-task-definition. They are never reset to AWS defaults on deploy:

• volumes — task volumes
• placementConstraints — task placement constraints
• requiresCompatibilities — launch type requirements (e.g. FARGATE)
• runtimePlatform — CPU architecture and OS family; particularly important for ARM64/Graviton Fargate services, where omitting it causes AWS to silently revert cpuArchitecture to X86_64 on every deploy

AWS Roles

At a minimum this plugin requires the following AWS permissions to be granted to the agent running this step:

Policy:
  Statement:
  - Action:
    - ecr:DescribeImages
    - ecs:DescribeServices
    - ecs:DescribeTaskDefinition
    - ecs:RegisterTaskDefinition
    - ecs:UpdateService
    Effect: Allow
    Resource: '*'

Developing

To run testing, shellchecks and plugin linting use use bk run with the Buildkite CLI.

bk run

Or if you want to run just the tests, you can use the docker Plugin Tester:

docker run --rm -ti -v "${PWD}":/plugin buildkite/plugin-tester:latest

License

MIT (see LICENSE)