Deploying to Amazon ECS

There are many strategies that can be used to deploy containers to Amazon ECS using Shippable Assembly Lines. This page will describe how you can use the managed deploy job to take a single Docker image and deploy it as an individual container to your cluster on Amazon ECS.

For custom deployments using cloud-native CLIs, where you write all the deployment scripts yourself, check out our document on Deploying to Amazon ECS with Cloud-Native CLI.

Assumptions

We assume that the application is already packaged as a Docker image and available in a Docker registry that Shippable supports. If you want to know how to build, test and push a Docker image through CI to a Docker registry, these links will help:

If you're not familiar with Shippable, it is also recommended that you read the Platform overview doc to understand the overall structure of Shippable's DevOps Assembly Lines platform.

Deployment workflow

You can configure your deployment with Shippable's configuration files in a powerful, flexible YAML based language. The specific YAML blocks that need to be authored are covered in the document.

This is a pictorial representation of the workflow required to deploy your application. The green boxes are jobs and the grey boxes are the input resources for the jobs. Both jobs and inputs are specified in Shippable configuration files.

These are the key components of the assembly line diagram -

Resources (grey boxes)

  • app_image is a required image resource that represents the Docker image of the app stored in Amazon ECR.
  • op_cluster is a required cluster resource that represents Amazon ECS cluster to which you're deploying the application.
  • app_options is an optional dockerOptions resource that represents the options of the application container.
  • app_env is an optional params resource that stores key-value pairs that are set as environment variables for consumption by the application.
  • app_replicas is an optional replicas resource that specifies the number of instances of the container to deploy.

Jobs (green boxes)

  • app_service_def is a required manifest job used to create a service definition of a deployable unit of your application, encompassing the image, options and environment that is versioned and immutable.
  • app_deploy_job is a required deploy job which deploys a manifest to a cluster resource.

Configuration

The configuration for this Assembly Line is in the shippable.yml file at the root of the repository -

  • Resources (grey boxes) are defined in the resources section of theshippable.yml file.

  • Jobs (green boxes) are defined in the jobs section of theshippable.yml file.

This file should be committed to your source control. Step 5 of the workflow below will describe how to add the config to Shippable.

Deployment instructions

1. Define Docker image

  • Description: app_image is an image resource that represents your Docker image stored in Amazon ECR
  • Required: Yes.
  • Integrations needed: AWS Keys, or any supported Docker registry if your image isn't stored in ECR.

Steps

  1. Create an account integration for AWS Keys in your Shippable UI. Instructions to create an integration are here:

    Copy the friendly name of the integration, in our case we named it aws_keys_int.

  2. Add the following yml block to your shippable.yml file.

resources:

  - name: app_image # resource friendly name
    type: image
    integration: aws_keys_int    #friendly name of your integration          
    pointer:
      sourceName: "679404489841.dkr.ecr.us-east-1.amazonaws.com/deploy-ecs-basic"    #image name
    seed:
      versionName: "master.1"  #Specify the tag of your image.

2. Create service definition

  • Description: app_service_def is a manifest job used to create a service definition of a deployable unit of your application. The service definition consists of the image, options and environment. The definition is also versioned (any change to the inputs of the manifest creates a new semantic version of the manifest) and is immutable.
  • Required: Yes.

Steps

Add the following yml block to your shippable.yml file.

jobs:

  - name: app_service_def
    type: manifest
    steps:
     - IN: app_image

3. Define cluster

  • Description: op_cluster is a cluster resource that represents the cluster on Amazon ECS where your application is deployed to.
  • Required: Yes.
  • Integrations needed: AWS Keys Integration

Steps

Add the following yml block to the existing resources section in your shippable.yml file.

resources:

  - name: op_cluster    # resource friendly name
    type: cluster
    integration: aws_keys_int   # friendly name of integration from step 1          
    pointer:
      sourceName: "deploy-ecs-cluster" # name of the actual cluster in ECS
      region: "us-east-1" # AWS region where cluster is located.

4. Create deployment job

  • Description: app_deploy_job is a deploy job that actually deploys the application manifest to the cluster and starts the container.
  • Required: Yes.

Steps

Add the following yml block to the existing jobs section in your shippable.yml file.

jobs:

  - name: app_deploy_job
    type: deploy
    steps:
      - IN: app_service_def
      - IN: op_cluster

5. Add config to Shippable

Once you have the shippable.yml file as described above, commit it to your repository. This repository is called a sync repository.

Follow these instructions to import your configuration files into your Shippable account.

6. Trigger your workflow

When you're ready for deployment, right-click on the manifest job in the SPOG View, and select Run Job. Your Assembly Line will also trigger every time the app_image changes, i.e. each time you have a new Docker image.

Customizing container options

By default, we set the following options while deploying your container:

  • memory : 400mb
  • desiredCount : 1
  • cpuShares : 0
  • All available CPU
  • no ENVs are added to the container

However, you can customize these and many other options by including a dockerOptions resource in your service definition.

Steps

1. Add a dockerOptions resource

Add a dockerOptions resource to your shippable.yml file. For example, to set memory to 1024MB and expose port 80, you would write the following snippet:

resources:

  - name: app_options
    type: dockerOptions
    version:
      memory: 1024
      portMappings:
        - 80:80

For a complete reference for dockerOptions, read the resource page.

2. Update service definition

Next, you should update your manifest with this new resource:

jobs:

  - name: app_service_def
    type: manifest
    steps:
     - IN: app_image
     - IN: app_options

Setting env vars

You can also include environment variables needed by your application in your service definition manifest. To do this, you need a params resource that lets you include key-value pairs.

Steps

1. Add a params resource

Add a params resource to your shippable.yml file. For example, to set environment variables needed to connect to your database:

resources:

  - name: app_env
    type: params
    version:
      params:
        DB_URL: "my.database.local"
        DB_PORT: 3306
        DB_NAME: "foo"

For a complete reference for params, read the resource page.

2. Update service definition

Next, you should update your manifest with this new resource:

jobs:

  - name: app_service_def
    type: manifest
    steps:
     - IN: app_image
     - IN: app_env

For a complete reference for manifest, read the job page.

Scaling app instances

By default, we always deploy one instance of your application. You can scale it as needed by including a replicas resource in your service definition manifest.

Steps

1. Add a replicas resource

Add a replicas resource to your shippable.yml file. For example, to scale your application to 5 instances:

resources:

  - name: app_replicas
    type: replicas
    version:
      count: 5

For a complete reference for replicas, read the resource page.

2. Update deploy job

Next, you should update your deploy with this new resource:

jobs:

  - name: app_deploy_job
    type: deploy
    steps:
      - IN: app_service_def
      - IN: op_cluster
      - IN: app_replicas

For a complete reference for deploy, read the job page.

Sample project

Here are some links to a working sample of this scenario. This is a simple Node.js application that runs some tests and then pushes the image to Amazon ECR. It also contains all of the pipelines configuration files for deploying to Amazon ECS.

Source code: devops-recipes/deploy-ecs-basic

Ask questions on Chat

Feel free to engage us on Chat if you have any questions about this document. Simply click on the Chat icon on the bottom right corner of this page and someone from our customer success team will get in touch with you.

Improve this page

We really appreciate your help in improving our documentation. If you find any problems with this page, please do not hesitate to reach out at support@shippable.com or open a support issue. You can also send us a pull request to the docs repository.