Amazon EC2 Auto Scaling
User Guide

Amazon EC2 Auto Scaling Lifecycle Hooks

Lifecycle hooks enable you to perform custom actions by pausing instances as an Auto Scaling group launches or terminates them. When an instance is paused, it remains in a wait state until either you complete the lifecycle action using the complete-lifecycle-action command or the CompleteLifecycleAction operation, or the timeout period ends (one hour by default).

For example, your newly launched instance completes its startup sequence and a lifecycle hook pauses the instance. While the instance is in a wait state, you can install or configure software on it, making sure that your instance is fully ready before it starts receiving traffic. For another example of the use of lifecycle hooks, when a scale-in event occurs, the terminating instance is first deregistered from the load balancer (if the Auto Scaling group is being used with Elastic Load Balancing). Then, a lifecycle hook pauses the instance before it is terminated. While the instance is in the wait state, you can, for example, connect to the instance and download logs or other data before the instance is fully terminated.

Each Auto Scaling group can have multiple lifecycle hooks. However, there is a limit on the number of hooks per Auto Scaling group. For more information, see Amazon EC2 Auto Scaling Limits.

How Lifecycle Hooks Work

After you add lifecycle hooks to your Auto Scaling group, they work as follows:

  1. The Auto Scaling group responds to scale-out events by launching instances and scale-in events by terminating instances.

  2. The lifecycle hook puts the instance into a wait state (Pending:Wait or Terminating:Wait). The instance is paused until you continue or the timeout period ends.

  3. You can perform a custom action using one or more of the following options:

    • Define a CloudWatch Events target to invoke a Lambda function when a lifecycle action occurs. The Lambda function is invoked when Amazon EC2 Auto Scaling submits an event for a lifecycle action to CloudWatch Events. The event contains information about the instance that is launching or terminating, and a token that you can use to control the lifecycle action.

    • Define a notification target for the lifecycle hook. Amazon EC2 Auto Scaling sends a message to the notification target. The message contains information about the instance that is launching or terminating, and a token that you can use to control the lifecycle action.

    • Create a script that runs on the instance as the instance starts. The script can control the lifecycle action using the ID of the instance on which it runs.

  4. By default, the instance remains in a wait state for one hour, and then the Auto Scaling group continues the launch or terminate process (Pending:Proceed or Terminating:Proceed). If you need more time, you can restart the timeout period by recording a heartbeat. If you finish before the timeout period ends, you can complete the lifecycle action, which continues the launch or termination process.

The following illustration shows the transitions between instance states in this process:


                    The lifecycle of instances using lifecycle hooks.

For more information about the complete lifecycle of instances in an Auto Scaling group, see Auto Scaling Lifecycle.

Considerations

Adding lifecycle hooks to your Auto Scaling group gives you greater control over how instances launch and terminate. The following are things to consider when adding a lifecycle hook to your Auto Scaling group, to help ensure that the group continues to perform as expected.

Keeping Instances in a Wait State

Instances can remain in a wait state for a finite period of time. The default is one hour (3600 seconds). You can adjust this time in the following ways:

  • Set the heartbeat timeout for the lifecycle hook when you create the lifecycle hook. With the put-lifecycle-hook command, use the --heartbeat-timeout parameter. With the PutLifecycleHook operation, use the HeartbeatTimeout parameter.

  • Continue to the next state if you finish before the timeout period ends, using the complete-lifecycle-action command or the CompleteLifecycleAction operation.

  • Postpone the end of the timeout period by recording a heartbeat, using the record-lifecycle-action-heartbeat command or the RecordLifecycleActionHeartbeat operation. This extends the timeout period by the timeout value specified when you created the lifecycle hook. For example, if the timeout value is one hour, and you call this command after 30 minutes, the instance remains in a wait state for an additional hour, or a total of 90 minutes.

The maximum amount of time that you can keep an instance in a wait state is 48 hours or 100 times the heartbeat timeout, whichever is smaller.

Cooldowns and Simple Scaling

When an Auto Scaling group launches or terminates an instance due to a simple scaling policy, a cooldown takes effect. The cooldown period helps ensure that the Auto Scaling group does not launch or terminate more instances than needed. When a lifecycle action occurs, and an instance enters the wait state, scaling activities due to simple scaling policies are paused. When the instance enters the InService state, the cooldown period starts. When the cooldown period expires, any paused scaling activities resume.

Health Check Grace Period

If you add a lifecycle hook, the health check grace period does not start until the lifecycle hook actions complete and the instance enters the InService state.

Spot Instances

You can use lifecycle hooks with Spot Instances. However, a lifecycle hook does not prevent an instance from terminating in the event that capacity is no longer available. In addition, when a Spot Instance terminates, you must still complete the lifecycle action (using the complete-lifecycle-action command or the CompleteLifecycleAction operation).

Prepare for Notifications

You can configure notifications for when an instance enters a wait state. You can use Amazon CloudWatch Events, Amazon SNS, or Amazon SQS to receive the notifications. For more information, see Configuring Lifecycle Hook Notifications.

Alternatively, if you have a script that configures your instances when they launch, you do not need to receive notification when the lifecycle action occurs. If you are not doing so already, update your script to retrieve the instance ID of the instance from the instance metadata. For more information, see Retrieving Instance Metadata in the Amazon EC2 User Guide for Linux Instances.

Add Lifecycle Hooks

When you add a lifecycle hook to your Auto Scaling group, you can specify whether it should be run when instances launch or terminate in the Auto Scaling group.

Add Lifecycle Hooks (Console)

Follow these steps to add a lifecycle hook to an existing Auto Scaling group. You can specify whether the hook is used when the instances launch or terminate and how long to wait until the lifecycle hook is completed before abandoning or continuing.

To add a lifecycle hook

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. On the navigation pane, under Auto Scaling, choose Auto Scaling Groups.

  3. Select your Auto Scaling group.

  4. On the Lifecycle Hooks tab, choose Create Lifecycle Hook.

  5. To define a lifecycle hook, do the following:

    1. For Lifecycle Hook Name, specify a name for the lifecycle hook.

    2. For Lifecycle Transition, choose Instance Launch or Instance Terminate.

    3. Specify a timeout value for Heartbeat Timeout, which allows you to control the amount of time for the instances to remain in a wait state. The value must be from 30 to 7200 seconds. During the timeout period, you can, for example, log on to a newly launched instance, and install applications or perform custom actions.

    4. For Default Result, specify the action the Auto Scaling group takes when the lifecycle hook timeout elapses or if an unexpected failure occurs. You can choose to either ABANDON or CONTINUE.

      If the instance is launching, CONTINUE indicates that your actions were successful, and that the Auto Scaling group can put the instance into service. Otherwise, ABANDON indicates that your custom actions were unsuccessful, and that the instance can be terminated. If the instance is terminating, both ABANDON and CONTINUE allow the instance to terminate. However, ABANDON stops any remaining actions, such as other lifecycle hooks, and CONTINUE allows any other lifecycle hooks to complete.

    5. (Optional) For Notification Metadata, specify additional information that you want to include any time Amazon EC2 Auto Scaling sends a message to the notification target.

  6. Choose Create.

Add Lifecycle Hooks (AWS CLI)

Create and update lifecycle hooks using the put-lifecycle-hook command.

To perform an action on scale out, use the following command.

aws autoscaling put-lifecycle-hook --lifecycle-hook-name my-hook --auto-scaling-group-name my-asg \ --lifecycle-transition autoscaling:EC2_INSTANCE_LAUNCHING

To perform an action on scale in, use the following command instead.

aws autoscaling put-lifecycle-hook --lifecycle-hook-name my-hook --auto-scaling-group-name my-asg \ --lifecycle-transition autoscaling:EC2_INSTANCE_TERMINATING

To receive notifications using Amazon SNS or Amazon SQS, you must specify a notification target and an IAM role. For more information, see Configuring Lifecycle Hook Notifications.

For example, add the following options to specify an SNS topic as the notification target.

--notification-target-arn arn:aws:sns:region:123456789012:my-sns-topic --role-arn arn:aws:iam::123456789012:role/my-notification-role

The topic receives a test notification with the following key-value pair.

"Event": "autoscaling:TEST_NOTIFICATION"

Complete a Lifecycle Hook Custom Action

When an Auto Scaling group responds to a scale-out or scale-in event, it puts the instance in a wait state and, depending on how the lifecycle hook is configured, sends a notification.

To complete a lifecycle hook custom action

  1. After receiving a notification, you can perform a custom action while the instance is in a wait state.

  2. If you need more time to complete the custom action, use the record-lifecycle-action-heartbeat command to restart the timeout period and keep the instance in a wait state. You can specify the lifecycle action token that you received with the notification, as shown in the following command.

    aws autoscaling record-lifecycle-action-heartbeat --lifecycle-hook-name my-launch-hook \ --auto-scaling-group-name my-asg --lifecycle-action-token bcd2f1b8-9a78-44d3-8a7a-4dd07d7cf635

    Alternatively, you can specify the ID of the instance you retrieved in the previous step, as shown in the following command.

    aws autoscaling record-lifecycle-action-heartbeat --lifecycle-hook-name my-launch-hook \ --auto-scaling-group-name my-asg --instance-id i-1a2b3c4d
  3. If you finish the custom action before the timeout period ends, use the complete-lifecycle-action command so that the Auto Scaling group can continue launching or terminating the instance. You can specify the lifecycle action token, as shown in the following command.

    aws autoscaling complete-lifecycle-action --lifecycle-action-result CONTINUE \ --lifecycle-hook-name my-launch-hook --auto-scaling-group-name my-asg \ --lifecycle-action-token bcd2f1b8-9a78-44d3-8a7a-4dd07d7cf635

    Alternatively, you can specify the ID of the instance, as shown in the following command.

    aws autoscaling complete-lifecycle-action --lifecycle-action-result CONTINUE \ --instance-id i-1a2b3c4d --lifecycle-hook-name my-launch-hook \ --auto-scaling-group-name my-asg

Test the Notification

To generate a notification for a launch event, update the Auto Scaling group by increasing the desired capacity of the Auto Scaling group by 1. You receive a notification within a few minutes after instance launch.

To change the desired capacity (console)

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. On the navigation pane, under Auto Scaling, choose Auto Scaling Groups.

  3. Select your Auto Scaling group.

  4. On the Details tab, choose Edit.

  5. For Desired, increase the current value by 1. If this value exceeds Max, you must also increase the value of Max by 1.

  6. Choose Save.

  7. After a few minutes, you'll receive notification for the event. If you do not need the additional instance that you launched for this test, you can decrease Desired by 1. After a few minutes, you'll receive notification for the event.