Add lifecycle hooks - Amazon EC2 Auto Scaling
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Add lifecycle hooks

To put your Auto Scaling instances into a wait state and perform custom actions on them, you can add lifecycle hooks to your Auto Scaling group. Custom actions are performed as the instances launch or before they terminate. Instances remain in a wait state until you either complete the lifecycle action, or the timeout period ends.

After you create an Auto Scaling group from the Amazon Web Services Management Console, you can add one or more lifecycle hooks to it, up to a total of 50 lifecycle hooks. You can also use the Amazon CLI, Amazon CloudFormation, or an SDK to add lifecycle hooks to an Auto Scaling group as you are creating it.

By default, when you add a lifecycle hook in the console, Amazon EC2 Auto Scaling sends lifecycle event notifications to Amazon EventBridge. Using EventBridge or a user data script is a recommended best practice. To create a lifecycle hook that sends notifications directly to Amazon SNS or Amazon SQS, you can use the put-lifecycle-hook command, as shown in the examples in this topic.

Add lifecycle hooks (console)

Follow these steps to add a lifecycle hook to your Auto Scaling group. To create lifecycle hooks for scaling out (instances launching) and scaling in (instances terminating), you must create two separate hooks.

Before you begin, confirm that you have set up a custom action, as described in Prepare to add a lifecycle hook to your Auto Scaling group.

To add a lifecycle hook

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/, and choose Auto Scaling Groups from the navigation pane.

  2. Select the check box next to your Auto Scaling group.

    A split pane opens up in the bottom part of the Auto Scaling groups page.

  3. On the Instance management tab, in Lifecycle hooks, choose Create lifecycle hook.

  4. 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. For Heartbeat timeout, specify the amount of time for instances to remain in a wait state when scaling out or scaling in before the hook times out. The range is from 30 to 7200 seconds.

      Note

      By default, the timeout is 3600 seconds (one hour). Setting a long timeout period provides more time for the custom action to complete. If you finish before the timeout period ends, you can send the complete-lifecycle-action command to allow the instance to proceed to the next state.

    4. For Default result, specify the action to take when the lifecycle hook timeout elapses or when an unexpected failure occurs. You can choose to either abandon (default) or continue.

      • If the instance is launching, continue indicates that your actions were successful, and that Amazon EC2 Auto Scaling can put the instance into service. Otherwise, abandon indicates that your custom actions were unsuccessful, and that Amazon EC2 Auto Scaling can terminate the instance.

      • 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 when Amazon EC2 Auto Scaling sends a message to the notification target.

  5. Choose Create.

Add lifecycle hooks (Amazon 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-launch-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-termination-hook \ --auto-scaling-group-name my-asg \ --lifecycle-transition autoscaling:EC2_INSTANCE_TERMINATING

To receive notifications using Amazon SNS or Amazon SQS, add the --notification-target-arn and --role-arn options.

The following example creates a lifecycle hook that specifies an SNS topic named my-sns-topic as the notification target.

aws autoscaling put-lifecycle-hook --lifecycle-hook-name my-termination-hook \ --auto-scaling-group-name my-asg \ --lifecycle-transition autoscaling:EC2_INSTANCE_TERMINATING \ --notification-target-arn arn:aws-cn:sns:region:123456789012:my-sns-topic \ --role-arn arn:aws-cn:iam::123456789012:role/my-notification-role

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

"Event": "autoscaling:TEST_NOTIFICATION"

By default, the put-lifecycle-hook command creates a lifecycle hook with a heartbeat timeout of 3600 seconds (one hour).

To change the heartbeat timeout for an existing lifecycle hook, add the --heartbeat-timeout option, as shown in the following example.

aws autoscaling put-lifecycle-hook --lifecycle-hook-name my-termination-hook \ --auto-scaling-group-name my-asg --heartbeat-timeout 120

If an instance is already in a wait state, you can prevent the lifecycle hook from timing out by recording a heartbeat, using the record-lifecycle-action-heartbeat CLI command. This extends the timeout period by the timeout value specified when you created the lifecycle hook. If you finish before the timeout period ends, you can send the complete-lifecycle-action CLI command to allow the instance to proceed to the next state. For more information and examples, see Complete a lifecycle action.