About AWS CodeDeploy

As AWS describes: “AWS CodeDeploy is a service that automates code deployments to any instance, including Amazon EC2 instances and instances running on-premises. AWS CodeDeploy makes it easier for you to rapidly release new features, helps you avoid downtime during application deployment, and handles the complexity of updating your applications. You can use AWS CodeDeploy to automate software deployments, eliminating the need for error-prone manual operations, and the service scales with your infrastructure so you can easily deploy to one instance or thousands.” Below, I describe the core components that make up CodeDeploy.

AppSpec – The appspec.yml must be in the root directory of an AWS CodeDeploy deployment bundle. Here’s an example appspec.yml file from AWS.

Application – The application is the container for the deployment and deployment configuration. The application uses the appspec.yml to define how the lifecycle events behave.

Deployment Group – Define how the deployment behaves. In the deployment group, you set the previously-defined Application, Deployment Configuration, on which EC2 instances to run the deployment and any AutoScaling configuration.

Deployment Configuration – There are three default configurations provided by CodeDeploy: CodeDeployDefault.OneAtATime, CodeDeployDefault.AllAtOnce and CodeDeployDefault.HalfAtATime. You can describe custom configurations as well.

Lifecycle Events – Each deployment triggers certain events that run in a pre-defined sequence. The actual code that is run is defined in the appspec.yml using hooks section of the file. Here are the events that get triggered as part of a typical CodeDeploy deployment.

ApplicationStop

DownloadBundle

BeforeInstall

Install

AfterInstall

ApplicationStart

ValidateService

In order for CodeDeploy to work, you need to install the CodeDeploy agent on each EC2 instance on which you’re running CodeDeploy. CodeDeploy communicates with the agents via HTTPS over port 443. The agent contains code that has CodeDeploy domain-specific knowledge and uses the defined configuration to run through its lifecycle events.

Executing the CloudFormation Template

Below, you see an example of running the template that I’ve defined. You’ll need to define your own stack name and EC2KeyPairName. From your AWS CLI, run a command to launch the CloudFormation stack. You can also launch the same using the CloudFormation console.

It’ll take about 10-15 minutes to launch the stacks that launch the EC2 instance, install the CodeDeploy agent, configure and run a deployment of the application. You can visually verify the application works by going to the CodeDeploy console (shown in Figure 1), select an application, then a deployment and click on the link under the Instance ID column. From the EC2 console, find the Public IP and prepend http:// to it from your web browser.

Figure 1: AWS CodeDeploy deployment status

Architecture

There are two CloudFormation templates to define the EC2 instances, S3 Distribution Location, IAM and CodeDeploy resources along with its overall orchestration via nested stacks. They are:

codedeploy-master.json – The master template orchestrates the execution of the other CloudFormation templates using nested CloudFormation stacks and the DependsOn attribute. It uses the Outputs from one stack as input parameters to the next calling template. Using the DependsOn attribute ensures that the resources have been provisioned prior to calling the next template.

Implementation

There are several parts to automating the process of downloading the sample application, provisioning EC2 instances with the CodeDeploy agent, provisioning CodeDeploy to create an application and to run a deployment for that application using CodeDeploy. The first example snippet below can be found in the codedeploy-master.json CloudFormation template. This launches a new stack from the AWS CloudFormation template that provisions EC2 instances and installs the CodeDeploy agent.

The next snippet from the same codedeploy-master.json template uses the EC2 tag value that was set in the first stack as a way for this template to determine on which EC2 instances it will run the CodeDeploy deployment. It also uses the DependsOn attribute to ensure that the stack has been created before attempting to launch this stack – since it requires resources from the first stack.

Troubleshooting

As you’re experimenting with CodeDeploy and automating the provisioning of CodeDeploy in CloudFormation, you’ll likely experience a few problems along the way. There were a couple of useful suggestions provided to me by AWS Support.

Get the logs – SSH into the EC2 instances on which the CodeDeploy agent was installed and view the contents of the /opt/codedeploy-agent/deployment-root and /var/log/ directories. You might choose to zip up the directories and download them for easy viewing as demonstrated below.

Turn off Auto Rollback in CloudFormation – When you’re using the AWS CloudFormation Console and you accept all the default options, it will auto rollback all the stacks. This makes it more difficult to troubleshoot when something does go wrong. Instead, you might choose to call from the command line as shown in the example below. You can still turn off auto rollback using the console, but it’s easier to forget.