AppSpec 'hooks' section

The content in the 'hooks' section of the AppSpec file varies, depending on the compute platform for your deployment. The 'hooks' section for an EC2/On-Premises deployment contains mappings that link deployment lifecycle event hooks to one or more scripts. The 'hooks' section for a Lambda or an Amazon ECS deployment specifies Lambda validation functions to run during a deployment lifecycle event. If an event hook is not present, no operation is executed for that event. This section is required only if you are running scripts or Lambda validation functions as part of the deployment.

AppSpec 'hooks' section for an Amazon ECS deployment

List of lifecycle event hooks for an Amazon ECS deployment

An AWS Lambda hook is one Lambda function specified with a string on a new line after the name of the lifecycle event. Each hook is executed once per deployment. Following are descriptions of the lifecycle events where you can run a hook during an Amazon ECS deployment.

For more information, see What happens during an Amazon ECS deployment and Tutorial: Deploy an Amazon ECS service with a validation test.

Run order of hooks in an Amazon ECS deployment.

In an Amazon ECS deployment, event hooks run in the following order:

Structure of 'hooks' section

The following are examples of the structure of the 'hooks' section.

Using YAML:

Hooks:
  - BeforeInstall: "BeforeInstallHookFunctionName"
  - AfterInstall: "AfterInstallHookFunctionName"
  - AfterAllowTestTraffic: "AfterAllowTestTrafficHookFunctionName"
  - BeforeAllowTraffic: "BeforeAllowTrafficHookFunctionName"
  - AfterAllowTraffic: "AfterAllowTrafficHookFunctionName"

Using JSON:

"Hooks": [
		{
			"BeforeInstall": "BeforeInstallHookFunctionName"
		},
		{
			"AfterInstall": "AfterInstallHookFunctionName"
		},
		{
			"AfterAllowTestTraffic": "AfterAllowTestTrafficHookFunctionName"
		},
		{
			"BeforeAllowTraffic": "BeforeAllowTrafficHookFunctionName"
		},
		{
			"AfterAllowTraffic": "AfterAllowTrafficHookFunctionName"
		}
	]
}

Sample Lambda 'hooks' function

Use the 'hooks' section to specify a Lambda function that CodeDeploy can call to validate an Amazon ECS deployment. You can use the same function or a different one for the BeforeInstall, AfterInstall, AfterAllowTestTraffic, BeforeAllowTraffic, and AfterAllowTraffic deployment lifecycle events. Following completion of the validation tests, the Lambda AfterAllowTraffic function calls back CodeDeploy and delivers a result of Succeeded or Failed.

Before invoking a Lambda hook function, the server must be notified of the deployment ID and the lifecycle event hook execution ID using the putLifecycleEventHookExecutionStatus command.

The following is a sample Lambda hook function written in Node.js.

'use strict';

const aws = require('aws-sdk');
const codedeploy = new aws.CodeDeploy({apiVersion: '2014-10-06'});

exports.handler = (event, context, callback) => {
    //Read the DeploymentId from the event payload.
    var deploymentId = event.DeploymentId;

    //Read the LifecycleEventHookExecutionId from the event payload
    var lifecycleEventHookExecutionId = event.LifecycleEventHookExecutionId;

    /*
     Enter validation tests here.
    */

    // Prepare the validation test results with the deploymentId and
    // the lifecycleEventHookExecutionId for CodeDeploy.
    var params = {
        deploymentId: deploymentId,
        lifecycleEventHookExecutionId: lifecycleEventHookExecutionId,
        status: 'Succeeded' // status can be 'Succeeded' or 'Failed'
    };
    
    // Pass CodeDeploy the prepared validation test results.
    codedeploy.putLifecycleEventHookExecutionStatus(params, function(err, data) {
        if (err) {
            // Validation failed.
            callback('Validation test failed');
        } else {
            // Validation succeeded.
            callback(null, 'Validation test succeeded');
        }
    });
};

AppSpec 'hooks' section for an AWS Lambda deployment

List of lifecycle event hooks for an AWS Lambda deployment

An AWS Lambda hook is one Lambda function specified with a string on a new line after the name of the lifecycle event. Each hook is executed once per deployment. Here are descriptions of the hooks available for use in your AppSpec file.

Run order of hooks in a Lambda function version deployment

In a serverless Lambda function version deployment, event hooks run in the following order:

Structure of 'hooks' section

The following are examples of the structure of the 'hooks' section.

Using YAML:

hooks:
   - BeforeAllowTraffic: BeforeAllowTrafficHookFunctionName
   - AfterAllowTraffic: AfterAllowTrafficHookFunctionName

Using JSON:

"hooks": [{
    "BeforeAllowTraffic": "BeforeAllowTrafficHookFunctionName"
    },
    {
    "AfterAllowTraffic": "AfterAllowTrafficHookFunctionName"
}]

Sample Lambda 'hooks' function

Use the 'hooks' section to specify a Lambda function that CodeDeploy can call to validate a Lambda deployment. You can use the same function or a different one for the BeforeAllowTraffic and AfterAllowTraffic deployment lifecycle events. Following completion of the validation tests, the Lambda validation function calls back CodeDeploy and delivers a result of Succeeded or Failed.

Before invoking a Lambda hook function, the server must be notified of the deployment ID and the lifecycle event hook execution ID using the putLifecycleEventHookExecutionStatus command.

The following is a sample Lambda hook function written in Node.js.

'use strict';

const aws = require('aws-sdk');
const codedeploy = new aws.CodeDeploy({apiVersion: '2014-10-06'});

exports.handler = (event, context, callback) => {
    //Read the DeploymentId from the event payload.
    var deploymentId = event.DeploymentId;

    //Read the LifecycleEventHookExecutionId from the event payload
    var lifecycleEventHookExecutionId = event.LifecycleEventHookExecutionId;

    /*
     Enter validation tests here.
    */

    // Prepare the validation test results with the deploymentId and
    // the lifecycleEventHookExecutionId for CodeDeploy.
    var params = {
        deploymentId: deploymentId,
        lifecycleEventHookExecutionId: lifecycleEventHookExecutionId,
        status: 'Succeeded' // status can be 'Succeeded' or 'Failed'
    };
    
    // Pass CodeDeploy the prepared validation test results.
    codedeploy.putLifecycleEventHookExecutionStatus(params, function(err, data) {
        if (err) {
            // Validation failed.
            callback('Validation test failed');
        } else {
            // Validation succeeded.
            callback(null, 'Validation test succeeded');
        }
    });
};

AppSpec 'hooks' section for an EC2/On-Premises deployment

List of lifecycle event hooks

An EC2/On-Premises deployment hook is executed once per deployment to an instance. You can specify one or more scripts to run in a hook. Each hook for a lifecycle event is specified with a string on a separate line. Here are descriptions of the hooks available for use in your AppSpec file.

For information about which lifecycle event hooks are valid for which deployment and rollback types, see Lifecycle event hook availability.

Lifecycle event hook availability

The following table lists the lifecycle event hooks available for each deployment and rollback scenario.

Run order of hooks in a deployment

Auto Scaling launch deployments

During an Auto Scaling launch deployment, CodeDeploy runs event hooks in the following order.

For more information about Auto Scaling launch deployments, see How Amazon EC2 Auto Scaling works with CodeDeploy.

Auto Scaling termination deployments

During an Auto Scaling termination deployment, CodeDeploy runs event hooks in the following order.

For more information about Auto Scaling termination deployments, see Enabling termination deployments during Auto Scaling scale-in events.

In-place deployments

In an in-place deployment, including the rollback of an in-place deployment, event hooks are run in the following order:

Blue/green deployments

In a blue/green deployment, event hooks are run in the following order:

Structure of 'hooks' section

The 'hooks' section has the following structure:

hooks:
   deployment-lifecycle-event-name:
     - location: script-location
       timeout: timeout-in-seconds
       runas: user-name

You can include the following elements in a hook entry after the deployment lifecycle event name:

Referencing files in your hook scripts

If you are hooking up a script to a CodeDeploy lifecycle event as described in AppSpec 'hooks' section, and you want to reference a file (for example, helper.sh) in your script, then you will need to specify helper.sh using:

Using absolute paths

To reference a file using its absolute path, you can either:

Deployment archive location

During the DownloadBundle lifecycle event, the CodeDeploy agent extracts the revision for the deployment to a directory that has the following format:

root-directory/deployment-group-id/deployment-id/deployment-archive

The root-directory portion of the path is always set to either the default shown in the following table, or is controlled by the :root_dir configuration setting. For more information about configuration settings, see CodeDeploy agent configuration reference.

From your hook scripts, you could access the current deployment archive using the the root directory path and the DEPLOYMENT_ID and DEPLOYMENT_GROUP_ID environment variables. For more information about variables you can use, see Environment variable availability for hooks.

For example, here is how you could access a data.json file that resides at the root of your revision on Linux:

#!/bin/bash

rootDirectory="/opt/codedeploy-agent/deployment-root" # note: this will be different if you
                                                      # customize the :root_dir configuration
dataFile="$rootDirectory/$DEPLOYMENT_GROUP_ID/$DEPLOYMENT_ID/deployment-archive/data.json"
data=$(cat dataFile)

As another example, here is how you could access a data.json file that resides at the root of your revision using Powershell on Windows:

$rootDirectory="$env:ProgramData\Amazon\CodeDeploy" # note: this will be different if you
                                                    # customize the :root_dir configuration
$dataFile="$rootDirectory\$env:DEPLOYMENT_GROUP_ID\$env:DEPLOYMENT_ID\deployment-archive\data.json"
$data=(Get-Content $dataFile)

Using relative paths

To reference a file using its relative path, you'll need to know the CodeDeploy agent's working directory. File paths are relative to this directory.

The following table shows the working directory for each supported platform of the CodeDeploy agent.

Environment variable availability for hooks

During each deployment lifecycle event, hook scripts can access the following environment variables:

These environment variables are local to each deployment lifecycle event.

There are additional environment variables available to hook scripts depending on the source of the deployment bundle:

Bundle from Amazon S3

Bundle from GitHub

The following script changes the listening port on an Apache HTTP server to 9090 instead of 80 if the value of DEPLOYMENT_GROUP_NAME is equal to Staging. This script must be invoked during the BeforeInstall deployment lifecycle event:

if [ "$DEPLOYMENT_GROUP_NAME" == "Staging" ]
then
    sed -i -e 's/Listen 80/Listen 9090/g' /etc/httpd/conf/httpd.conf
fi

The following script example changes the verbosity level of messages recorded in its error log from warning to debug if the value of the DEPLOYMENT_GROUP_NAME environment variable is equal to Staging. This script must be invoked during the BeforeInstall deployment lifecycle event:

if [ "$DEPLOYMENT_GROUP_NAME" == "Staging" ]
then
    sed -i -e 's/LogLevel warn/LogLevel debug/g' /etc/httpd/conf/httpd.conf
fi

The following script example replaces the text in the specified webpage with text that displays the value of these environment variables. This script must be invoked during the AfterInstall deployment lifecycle event:

#!/usr/bin/python

import os
 
strToSearch="<h2>This application was deployed using CodeDeploy.</h2>"
strToReplace="<h2>This page for "+os.environ['APPLICATION_NAME']+" application and "+os.environ['DEPLOYMENT_GROUP_NAME']+" deployment group with "+os.environ['DEPLOYMENT_GROUP_ID']+" deployment group ID was generated by a "+os.environ['LIFECYCLE_EVENT']+" script during "+os.environ['DEPLOYMENT_ID']+" deployment.</h2>"
 
fp=open("/var/www/html/index.html","r")
buffer=fp.read()
fp.close()
 
fp=open("/var/www/html/index.html","w")
fp.write(buffer.replace(strToSearch,strToReplace))
fp.close()

Hooks example

Here is an example of a hooks entry that specifies two hooks for the AfterInstall lifecycle event:

hooks:
   AfterInstall:
     - location: Scripts/RunResourceTests.sh
       timeout: 180
     - location: Scripts/PostDeploy.sh
       timeout: 180

The Scripts/RunResourceTests.sh script runs during the AfterInstall stage of the deployment process. The deployment is unsuccessful if it takes the script more than 180 seconds (3 minutes) to run.

The location of scripts you specify in the 'hooks' section is relative to the root of the application revision bundle. In the preceding example, a file named RunResourceTests.sh is in a directory named Scripts. The Scripts directory is at the root level of the bundle. For more information, see Plan a revision for CodeDeploy.