Menu
AWS CodeDeploy
User Guide (API Version 2014-10-06)

AppSpec 'hooks' Section

The hooks section of the AppSpec file contains mappings that link deployment lifecycle event hooks to one or more scripts. If an event hook is not present, then no operation is executed for that event. This section is required only if you will be running scripts as part of the deployment.

Some hooks are valid only for blue/green deployments. See the following table for which lifecycle event hooks are valid for which deployment and rollback types.

The available event hooks are:

  1. ApplicationStop – This deployment lifecycle event occurs even before the application revision is downloaded. You can use this event if you want to gracefully stop the application or remove currently installed packages in preparation of a deployment. The AppSpec file and scripts used for this deployment lifecycle event are from the last successfully deployed application revision.

    Note

    An AppSpec file does not exist on an instance before you deploy to it. For this reason, the ApplicationStop hook will not run the first time you deploy to the instance. You can use the ApplicationStop hook the second time you deploy to an instance.

    To determine the location of the last successfully deployed application revision, the AWS CodeDeploy agent looks up the location listed in the deployment-group-id_last_successful_install file. This file is located in:

    /opt/codedeploy-agent/deployment-root/deployment-instructions folder on Amazon Linux, Ubuntu Server, and RHEL Amazon EC2 instances.

    C:\ProgramData\Amazon\CodeDeploy\deployment-instructions folder on Windows Server Amazon EC2 instances.

    To troubleshoot a deployment that fails during the ApplicationStop deployment lifecycle event, see Troubleshooting a failed ApplicationStop deployment lifecycle event.

  2. DownloadBundle – During this deployment lifecycle event, the AWS CodeDeploy agent copies the application revision files to a temporary location:

    /opt/codedeploy-agent/deployment-root/deployment-group-id/deployment-id/deployment-archive folder on Amazon Linux, Ubuntu Server, and RHEL Amazon EC2 instances.

    C:\ProgramData\Amazon\CodeDeploy\deployment-group-id\deployment-id\deployment-archive folder on Windows Server Amazon EC2 instances.

    This event is reserved for the AWS CodeDeploy agent and cannot be used to run scripts.

    To troubleshoot a deployment that fails during the DownloadBundle deployment lifecycle event, see Troubleshooting a failed DownloadBundle deployment lifecycle event with "UnknownError: not opened for reading".

  3. BeforeInstall – You can use this deployment lifecycle event for preinstall tasks, such as decrypting files and creating a backup of the current version.

  4. Install – During this deployment lifecycle event, the AWS CodeDeploy agent copies the revision files from the temporary location to the final destination folder. This event is reserved for the AWS CodeDeploy agent and cannot be used to run scripts.

  5. AfterInstall – You can use this deployment lifecycle event for tasks such as configuring your application or changing file permissions.

  6. ApplicationStart – You typically use this deployment lifecycle event to restart services that were stopped during ApplicationStop.

  7. BeforeBlockTraffic – You can use this deployment lifecycle event to run tasks on instances in an original environment before they are deregistered from a load balancer. Valid for blue/green deployments only.

  8. BlockTraffic – During this deployment lifecycle event, internet traffic is blocked from accessing instances in the original environment. This event is reserved for the AWS CodeDeploy agent and cannot be used to run scripts. Valid for blue/green deployments only.

  9. AfterBlockTraffic – You can use this deployment lifecycle event to run tasks on instances in an original environment after they are deregistered from a load balancer. Valid for blue/green deployments only.

  10. BeforeAllowTraffic – You can use this deployment lifecycle event to run tasks on instances in a replacement environment before they are registered with a load balancer. Valid for blue/green deployments only.

  11. AllowTraffic – During this deployment lifecycle event, internet traffic is allowed to access instances in the replacement environment. This event is reserved for the AWS CodeDeploy agent and cannot be used to run scripts. Valid for blue/green deployments only.

  12. AfterAllowTraffic – You can use this deployment lifecycle event to run tasks on instances in a replacement environment after they are registered with a load balancer. Valid for blue/green deployments only.

  13. ValidateService – This is the last deployment lifecycle event. It is used to verify the deployment was completed successfully.

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

Lifecycle event name In-place deployment¹ Blue/green deployment: Original instances Blue/green deployment: Replacement instances Blue/green deployment rollback: Original instances Blue/green deployment rollback: Replacement instances
ApplicationStop
DownloadBundle²
BeforeInstall
Install²
AfterInstall
ApplicationStart
BeforeBlockTraffic
BlockTraffic²
AfterBlockTraffic
BeforeAllowTraffic
AllowTraffic²
AfterAllowTraffic
ValidateService

¹Also applies to the rollback of an in-place deployment.

² Reserved for AWS CodeDeploy operations. Cannot be used to run scripts.

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

Note

The Start, DownloadBundle, Install, and End events in the deployment cannot be scripted, which is why they appear in gray in this diagram. However, you can edit the files section of the AppSpec file to specify what's installed during the Install event.

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

Note

The Start, DownloadBundle, Install, BlockTraffic, AllowTraffic, and End events in the deployment cannot be scripted, which is why they appear in gray in this diagram. However, you can edit the files section of the AppSpec file to specify what's installed during the Install event.

The hooks section has the following structure:

Copy
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:

location

Required. The location of the script file for the revision.

timeout

Optional. The number of seconds to allow the script to execute before it is considered to have failed. The default is 3600 seconds (1 hour).

Note

3600 seconds (1 hour) is the maximum amount of time allowed for script execution for each deployment lifecycle event. If scripts exceed this limit, the deployment will stop and the deployment to the instance will fail. Make sure the total number of seconds specified in timeout for all scripts in each deployment lifecycle event do not exceed this limit.

runas

Optional. The user to impersonate when running the script. By default, this is the AWS CodeDeploy agent running on the instance. AWS CodeDeploy does not store passwords, so the user cannot be impersonated if the runas user needs a password. This element applies to Amazon Linux and Ubuntu Server instances only.

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

APPLICATION_NAME

The name of the application in AWS CodeDeploy that is part of the current deployment (for example, WordPress_App).

DEPLOYMENT_ID

The ID AWS CodeDeploy has assigned to the current deployment (for example, d-AB1CDEF23).

DEPLOYMENT_GROUP_NAME

The name of the deployment group in AWS CodeDeploy that is part of the current deployment (for example, WordPress_DepGroup).

DEPLOYMENT_GROUP_ID

The ID of the deployment group in AWS CodeDeploy that is part of the current deployment (for example, b1a2189b-dd90-4ef5-8f40-4c1c5EXAMPLE).

LIFECYCLE_EVENT

The name of the current deployment lifecycle event (for example, AfterInstall).

These environment variables are local to each deployment lifecycle event.

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:

Copy
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:

Copy
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 web page with text that displays the value of these environment variables. This script must be invoked during the AfterInstall deployment lifecycle event:

Copy
#!/usr/bin/python import os strToSearch="<h2>This application was deployed using AWS 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:

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

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

On this page: