EC2 Auto Scaling Lifecycle Hooks Cheat Sheet

Lifecycle hooks are a powerful feature of Amazon EC2 Auto Scaling that allow you to pause an instance's state transition and perform custom actions before it is fully launched or terminated.

Core Concepts

• What they are: A mechanism to pause an EC2 instance as it is being launched or terminated by an Auto Scaling group (ASG).
• Why use them: They give you a window of time to run custom scripts or perform actions on an instance before it is put into service or fully terminated.
• How it works: When a lifecycle event occurs, the ASG puts the instance into a wait state and sends a notification. Your custom action is triggered by this notification. Once your action is complete, you signal the ASG to continue the instance's state transition.

Lifecycle Hook States

You can add a lifecycle hook for two main instance transitions:

1. Instance Launch (autoscaling:EC2_INSTANCE_LAUNCHING)

• Purpose: To perform initialization tasks on a new instance before it is registered with a load balancer and put into the InService state.
• Wait State: The instance enters the Pending:Wait state.
• Common Use Cases:
  • Installing or configuring software.
  • Downloading necessary data, files, or machine learning models.
  • Running security checks or compliance validation scripts.
  • Registering the instance with a configuration management tool like Chef or Puppet.

2. Instance Termination (autoscaling:EC2_INSTANCE_TERMINATING)

• Purpose: To perform cleanup tasks on an instance before it is terminated.
• Wait State: The instance enters the Terminating:Wait state.
• Common Use Cases:
  • Connection Draining: Safely draining connections from a load balancer beyond the default connection draining timeout.
  • Data Backup: Copying logs or state data from the instance to a persistent storage location like Amazon S3.
  • Deregistration: Notifying an external system or control plane that the instance is going offline.

Lifecycle Hook Workflow

1. Trigger: An Auto Scaling event occurs (e.g., a scale-out or scale-in event).
2. Pause: The Auto Scaling group pauses the instance launch or termination, putting the instance into the corresponding Wait state (Pending:Wait or Terminating:Wait).
3. Notify: The lifecycle hook sends a notification about the event. This is typically configured to send a message to one of the following services:
   • Amazon EventBridge: The recommended and most flexible option.
   • Amazon Simple Notification Service (SNS): Pushes notifications to subscribers (e.g., an AWS Lambda function).
   • Amazon Simple Queue Service (SQS): Sends messages to a queue for reliable, asynchronous processing.
4. Custom Action: The notification triggers your custom logic. For example, an EventBridge rule could invoke a Lambda function or an AWS Systems Manager Run Command document. This script performs the necessary setup or cleanup tasks.
5. Complete: Your script must signal to the lifecycle hook that its action is complete. There are two ways to end the wait state:
   • Explicitly Complete: Your script makes an API call (complete-lifecycle-action) to tell the ASG to proceed. You can specify whether the next action should be CONTINUE (proceed with launch/termination) or ABANDON (cancel the action and terminate the instance). This is the recommended approach.
   • Timeout: The instance waits for a configured amount of time (the "Heartbeat Timeout"). If no completion signal is sent before the timeout expires, the ASG proceeds based on the "Default Result".

Key Configuration Parameters

• LifecycleHookName: A name for your hook.
• LifecycleTransition: The state to apply the hook (EC2_INSTANCE_LAUNCHING or EC2_INSTANCE_TERMINATING).
• HeartbeatTimeout: The maximum amount of time (in seconds) that the instance can remain in the wait state. The default is 3600 seconds (1 hour). If your script needs more time, it can send a record-lifecycle-action-heartbeat call to extend the timeout.
• DefaultResult: The action to take if the heartbeat timeout is reached before the hook is completed.
  • CONTINUE: The instance proceeds to the next state (InService or Terminated). This is often used for launch hooks.
  • ABANDON: The instance launch or termination action is canceled. For a launch hook, this means the new instance is terminated. For a termination hook, the instance is immediately terminated.