A well-written Continuous Deployment (CD) pipeline ensures that on every merge to a release branch, an artifact is created and deployed to the correct environment.
While working with containerized applications the CD pipeline needs to contain the following steps
- Code checkout
- Install dependencies
- Build the image
- Push to a container registry
- Use the latest image for the next deployment
- Trigger a new deployment
In this tutorial, we will write a CD pipeline that does all of the above tasks using Github Actions. We will deploy our application using AWS ECS.
AWS ECS is a fully managed container orchestration service from AWS. It helps you easily deploy, manage and scale containerized applications.
This tutorial assumes that you have a solid understanding of
It also makes the implicit assumption that your application is already deployed on ECS. At the end of this tutorial you will be able automate your deployments on merge to a release branch.
In this tutorial I will take you through how to
- Trigger a workflow on merge to a release branch.
- Build and push the image to the Elastic Container Registry
- Update the task-definition using the newly created image
- Deploy your application to the new environment
Starter Project
Please clone the following repository: https://github.com/wednesday-solutions/ecs-cd-starter
Setup database connection
Update the relevant database connection details in the .env.development
DB_URI=postgres://<role>:<password>@<host>:<port>/<db>
POSTGRES_HOST=<host>
POSTGRES_DB=<db>
POSTGRES_USER=<user>
POSTGRES_PASSWORD=<password>
Add secrets
We need to add the following secrets
- AWS_ACCESS_KEY_ID ACCESS_KEY_ID with access to deploy
- AWS_SECRET_ACCESS_KEY Associated SECRET_ACCESS_KEY
- AWS_REGION Region in which the cluster is deployed
- AWS_ECR_REPOSITORY Name of the ECR repository that we will push the image to.
Step 1
Add the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY secrets*.*
Step 2
Add the AWS deployment region
Step 3
Get the repository name from the AWS console and add it as a secret.
I have omitted the -dev
since that represents the stage. We will be using the same workflow to deploy to multiple environments and will hence infer the stage at runtime.
Create the task-definition.json for all the environments
Step 1
Go to the following URL: https://ap-south-1.console.aws.amazon.com/ecs/home?region=ap-south-1#/taskDefinitions
I'm using ap-south-1
as the AWS region. Please change the URL according to the region you are in
Step 2
Select the task definition for your environment and project. In my case its the ecs-cd-starter-dev
Step 3
Select the latest revision and go to the JSON
tab
Step 4
Copy the JSON.
Run the following snippet in the terminal
mkdir task-definition
touch task-definition/dev.json
Paste the JSON from the AWS console into the newly created file.
I use dev.json
since dev
is my default branch name. I want the code that is pushed to this branch deployed to the dev
environment.
You will need to repeat this step for the qa
and production
environments.
Trigger the workflow to run on merge to a release branch
Step 1 - Create workflow
Create a new workflow for continuous deployment in the .github/workflows
folder
touch .github/workflows/cd.yml
Step 2 - Setup triggers
Identify your release branches. The first release branch will be your default branch which should also be the branch that the team typically raises a pull request to when they want to add a new feature.
In my case this is the dev
branch. Typically you would have 2 more environments.
- qa
- production
So let's trigger this workflow whenever there is a push on one of these branches.
name: ECS Starter CD Develop
on:
push:
branches:
- dev
- qa
- master
jobs:
docker-build-push-deploy:
name: Docker build, push and deploy
runs-on: ubuntu-latest
steps:
Paste the above code into the newly created cd.yml
file
Step 3 - Checkout code
This step pulls the latest code.
...
steps:
- name: Checkout
uses: actions/checkout@v2
Step 4 - Get branch name
Get the current branch name. This step will fetch the current git branch name and store it. It can now be accessed like so: ${{steps.vars.outputs.stage}}
...
steps:
...
- name: Get branch name
id: vars
run: echo ::set-output name=stage::${GITHUB_REF#refs/*/}
Step 5 - Configure AWS Credentials
Configure AWS Credentials and region. Use the values from Github secrets to configure the AWS Credentials.
To get a better understanding of all of the configuration options please go through the documentation here: https://github.com/aws-actions/configure-aws-credentials#usage
...
steps:
...
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v1
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ secrets.AWS_REGION }}
Step 6 - Login to ECR
Use the aws-actions/amazon-ecr action to log in to AWS ECR.
To get a better understanding of all of the configuration options please go through the documentation here: https://github.com/aws-actions/amazon-ecr-login#usage
...
steps:
...
- name: Login to Amazon ECR
id: login-ecr
uses: aws-actions/amazon-ecr-login@v1
Step 7 - Build tag and push image to ECR
We now need to build the docker image,. tag and push it to AWS ECR. Use the commit hash to tag the image.
...
steps:
...
- name: Build, tag, and push image to Amazon ECR
env:
ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
ECR_REPOSITORY: ${{ secrets.AWS_ECR_REPOSITORY }}-${{steps.vars.outputs.stage}}
AWS_REGION: ${{ secrets.AWS_REGION }}
IMAGE_TAG: ${{ github.sha }}
run: |
docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG3
Step 8 - Render the task definition
We create a new task-definition revision by updating the value of image. We will point to the image that we just pushed to ECR.
...
steps:
...
- name: Render Amazon ECS task definition
id: ecs-cd-starter-container
uses: aws-actions/amazon-ecs-render-task-definition@v1
with:
task-definition: task-definition/${{steps.vars.outputs.stage}}.json #1
container-name: ecs-cd-starter-${{steps.vars.outputs.stage}} #2
image: ${{ steps.login-ecr.outputs.registry }}/${{ secrets.AWS_ECR_REPOSITORY }}-${{steps.vars.outputs.stage}}:${{ github.sha }}
- the task-definition folder will contain task-definitions for all of the environments. I create json files with the name of the environment and access it using
${{steps.vars.outputs.stage}}.json
in the workflow - I name my containers with the stage as the suffix. I reference it using
<container-name>${{steps.vars.outputs.stage}}.json
in the workflow. - We reference the image that we just pushed to the ECR registry.
Step 9 - Deploy to ECS
We use the latest revision of the task-definition that we just created to deploy the application to ECS. I use the same -branchName
suffix when naming my service and cluster
...
...
steps:
...
- name: Deploy to Amazon ECS service
uses: aws-actions/amazon-ecs-deploy-task-definition@v1
with:
task-definition: ${{ steps.pawlyclinic-api-container.outputs.task-definition }}
service: ecs-cd-starter-${{ steps.vars.outputs.stage }}
cluster: ecs-cd-starter-${{ steps.vars.outputs.stage }}
Step 10 - Logout of ECR
Once the deployment is done logout of ECR
...
steps:
...
- name: Logout of Amazon ECR
if: always()
run: docker logout ${{ steps.login-ecr.outputs.registry }}
Where to go from here
Now that you have setup a CD pipeline to deploy your application to ECS I would recommend reading our article on "how to execute batch jobs in a multi-container environment"
I hope you enjoyed this tutorial on how to create a CD pipeline to deploy your ECS application. If you have any questions or comments, please join the forum discussion below.
Top comments (1)
This is indeed a very interesting article. Thank you.