Introduction

The AWS CodeDeploy is Amazon Web Service deployment service that is responsible for automatic deployment of software application from the build enviroment to various compute service. The AWS CodeDeploy is one of the services that makes up the AWS CodePipeline, together with AWS CodeCommit (source code repository), AWS CodeBuild (for running unit test, and building the application), and the AWS CodeArtifacts (for storing the artifacts for deployment). We have previous posts on the how to configure CodeCommit, CodeBuild and CodePipeline which you can check out.

There is also a previous tutorial on how to configure AWS CodeDeploy with Github. However, here, we will be walking through how to use AWS CodeDeploy for deployment of docker image from the AWS Elastic Container Registry (ECR) into an Ubuntu OS EC2 instance. Checkout a quick walkthrough of how to deploy an Ubuntu EC2 instance in AWS here.

IMPORTANT NOTE

Before we begin to configure the AWS CodeDeploy, you should have the appspec.yml file added to the root of your project.

The appspec.yml file contains a set of bash script commands that tells AWS CodeDeploy the how to deploy the application in the compute service. These bash scripts are saved in the scrips directory of the root of your project directory. Without the appspec.yml and the corresponding scrips directory in your project, AWS CodeDeploy will not be able to run your application.

So, head over to your project source code, and create the appspec.yml file. Paste the below code snippet in the file and save.

version: 0.0
os: linux
files:
  - source: /
    destination: /home/ubuntu/admin-codedeploy
permissions:
  - object: /home/ubuntu/admin-codedeploy
    pattern: "**"
    owner: root
    group: root
hooks:
  BeforeInstall:
    - location: scripts/before_install.sh
      timeout: 1200
      runas: root
  AfterInstall:
    - location: scripts/build_run.sh
      timeout: 600
      runas: root

Take note of the destination and object path in the file above. You will need to create the path inside your EC2 instance.

You will also need to create the scripts directory with the before_install.sh and build_run.sh file inside the directory. And since we are deploying with docker image from the ECR registry, our scripts will be commands to pull and run the container inside our EC2. Make sure the directory is in the root of your project.

For the before_install.sh, paste the script below:

#!/bin/bash
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 836768216030.dkr.ecr.us-east-1.amazonaws.com

docker pull 836768216030.dkr.ecr.us-east-1.amazonaws.com/admin:admin-latest

For the build_run.sh file, paste the script below:

#!/bin/bash

docker rm -f admin-latest || true

docker run --name admin-latest --restart always -d -p 3006:3000 836768216030.dkr.ecr.us-east-1.amazonaws.com/admin:admin-latest

Once you have created both files inside the script directory in the root of you project, you can proceed to creating your deployment group and application for AWS CodeDeploy.

create aws codedeploy application

On the side pane, select the Application, click the orange Create Application button.

Supply the Application Name, and the Compute platform. Here, I will be using the EC2/On-premises platform. I already created an EC2 with the production tag in a previous tutorial.

create aws codedeploy application

Next is to select the deployment group name, and the IAM service role. I did a walkthrough on creating AWS IAM role here. Also, select the In-place deployment type. You can read more about the deployment type here

configure environment

Next, in the Environment Configuration, select the AWS EC2 instance checkbox, and provide the key and value (here I chose the Name of the instance which happens to be production.

You should tell AWS CodeDeploy how you will like to install the AWS CodeDeploy agent. You can check out the previous post on configuring SSM and Deploying AWS CodeDeploy with Github to see how you can manually configure the deployment agent.

However, in this walkthrough, we will select the Now and schedule updates method of install the CodeDeploy agent. Choose the CodeDeployDefault.AllAtOnce for the deployment configuration under the deployment settings.

For the Load Balancer, leave it unchecked since we would not be using any load balancer or autoscaling for our deployment.

As the last step, go over the configurations once again to be sure you selected the required method. All looks good? Click the orange Create Deployment button.

You should get the green ribbon Success at the landing page of the AWS CodeDeploy deployment configuration.

And with that, you have successfully created the AWS CodeDeploy for your project.

troubleshooting AWS codedeploy

I have also include some common AWS CodeDeploy errors and solutions you may likely encounter when running the AWS CodeDeploy service.

1. ERROR: The overall deployment failed because too many individual instances failed deployment
   SOLUTION: First make sure codedeploy is installed on the machine. Then make sure the IAM role attached to the EC2 has the permission for Codedeploy and S3.
   Ref: https://stackoverflow.com/questions/38195823/error-the-overall-deployment-failed-because-too-many-individual-instances-faile
2. ERROR: CodeDeployPlugin::CommandPoller: Missing credentials – please check if this instance was started with an IAM instance profile
   SOLUTION: This could be because you attached code deploy IAM Role after installing the CodeDeploy agent on the EC@ instance. Restart the code deploy service in the server to resolve.
   $sudo service codedeploy-agent restart
3. ERROR: CodeDeploy agent was not able to receive the lifecycle event
   SOLUTION: Ensure that you have your scripts for hooks in your sripts directory. And ensure the names are correctly entered in the appspec.yml
4. ERROR: The deployment failed because an invalid version value () was entered in the application specification file. Make sure your AppSpec file specifies \\”0.0
   SOLUTION: Check the appspec file in the code commit and ensure the version is 0.0 and also carefully examine that the version line does not have a full stop (.) added to it.
5. ERROR: Script at specified location: scripts/before_install.sh run as user ubuntu failed with exit code 1\”,\”log\”:\”\”}”}
   SOLUTION: Change the runas user from ubuntu to root inside the appspec.yml file. Do this from inside the code commit repo to be safer with the encoding.