AWS CodeDeploy Lifecycle Event Hooks Cheat Sheet

What are Lifecycle Event Hooks?

In AWS CodeDeploy, Lifecycle Event Hooks are a mechanism that allows you to run custom code (scripts or Lambda functions) at specific points, or "hooks," during the deployment process. These hooks give you granular control to perform tasks like stopping services, running integration tests, checking application health, or managing traffic shifts.

The hooks you can use, and the order in which they run, depend on the compute platform of your deployment (EC2/On-Premises, AWS Lambda, or Amazon ECS).

The AppSpec.yml File

Lifecycle hooks are defined in the hooks section of the AppSpec.yml file. This YAML file is the primary configuration for a deployment and must be placed in the root of your application source code directory. It tells the CodeDeploy agent what files to deploy and which scripts to run at each lifecycle event.

Example AppSpec.yml for EC2:

version: 0.0
os: linux
files:
  - source: /index.html
    destination: /var/www/html/
hooks:
  ApplicationStop:
    - location: scripts/stop_server.sh
      timeout: 300
  BeforeInstall:
    - location: scripts/backup_data.sh
      timeout: 300
  AfterInstall:
    - location: scripts/change_permissions.sh
      timeout: 300
  ApplicationStart:
    - location: scripts/start_server.sh
      timeout: 300
  ValidateService:
    - location: scripts/validate_health.sh
      timeout: 300

Hooks for EC2/On-Premises Deployments

For deployments to servers, the CodeDeploy agent executes shell scripts at each hook. The hooks run in the following order:

In-Place Deployment Hooks

1. ApplicationStop: Stop the existing application on the instance. This is the last chance to gracefully shut down services before the new version is installed.
2. DownloadBundle: The CodeDeploy agent downloads the application revision files to a temporary location on the instance.
3. BeforeInstall: Run pre-installation tasks, such as creating backups, removing old files, or configuring prerequisites.
4. Install: The agent copies the revision files from the temporary location to their final destination.
5. AfterInstall: Run post-installation tasks, such as setting file permissions, configuring the application, or installing dependencies.
6. ApplicationStart: Start the new application version.
7. ValidateService: (Most Critical Hook) Run tests to verify that the new application version is working correctly. A script that fails (exits with a non-zero code) in this phase will cause the deployment to fail and can trigger an automatic rollback.

Blue/Green Deployment Hooks

Blue/green deployments use the same hooks as in-place deployments on the new (green) instances. Additionally, they have hooks related to shifting production traffic:

• BeforeAllowTraffic: Run tasks on the green instances before they are registered with the load balancer and start receiving production traffic.
• AllowTraffic: The load balancer starts routing traffic to the new instances.
• AfterAllowTraffic: Run tasks on the green instances after they have started receiving production traffic. This is often used for final health checks or sending notifications.

Hooks for AWS Lambda Deployments

For Lambda deployments, the hooks do not run scripts. Instead, they invoke a specific version of your Lambda function to perform validation.

• BeforeAllowTraffic: This hook invokes the new version of your Lambda function. You can write logic within the function to perform sanity checks or run integration tests. If the function returns a failure, the deployment is rolled back.
• AfterAllowTraffic: This hook runs after traffic has been completely shifted to the new Lambda version. It can be used for post-deployment validation or notifications.

Hooks for Amazon ECS Deployments

Similar to Lambda, ECS deployment hooks invoke a Lambda function for validation at different stages of the process.

• BeforeInstall: Runs before the new task set (representing the new application version) is created.
• AfterInstall: Runs after the new task set is created and the containers have started. Useful for running initial health checks on the new containers.
• BeforeAllowTestTraffic: Runs before a "test listener" routes a small amount of traffic to the new task set. This is your chance to run integration tests with live test traffic.
• AfterAllowTestTraffic: Runs after the test traffic has been routed for a specified time.
• BeforeAllowTraffic: Runs before production traffic is fully shifted to the new task set.
• AfterAllowTraffic: Runs after all production traffic is routed to the new task set.

Key Concepts & Best Practices

• Error Handling: Any script that exits with a non-zero exit code is considered a failure. This will immediately stop the deployment at that hook.
• Automatic Rollback: If a deployment fails, CodeDeploy can be configured to automatically roll back to the last known good version.
• Timeouts: Each hook has a configurable timeout (default is 1 hour). If a script does not complete within the timeout, the deployment will fail.
• Idempotency: Whenever possible, make your hook scripts idempotent, meaning they can be run multiple times with the same outcome. This is important for retries and rollbacks.
• ValidateService is Key: For EC2 deployments, ValidateService is the most important hook for ensuring a deployment is successful and preventing a bad deployment from affecting users.