Menu
Auto Scaling
User Guide

Auto Scaling Lifecycle Hooks

Auto Scaling lifecycle hooks enable you to perform custom actions as Auto Scaling launches or terminates instances. For example, you could install or configure software on newly launched instances, or download log files from an instance before it terminates.

How Lifecycle Hooks Work

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

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

  2. Auto Scaling puts the instance into a wait state (Pending:Wait or Terminating:Wait). The instance remains in this state until either you tell Auto Scaling to 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 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. 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 Auto Scaling 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 When Using Lifecycle Hooks

Adding lifecycle hooks to your Auto Scaling group gives you greater control over how instances launch and terminate. Here are some things to consider when adding a lifecycle hook to your Auto Scaling, 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 1 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.

  • Restart the timeout period by recording a heartbeat, using the record-lifecycle-action-heartbeat command or the RecordLifecycleActionHeartbeat operation. This increments the heartbeat timeout by the timeout value specified when you created the lifecycle hook. For example, if the timeout value is 1 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 Custom Actions

When Auto Scaling 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.

Consider an Auto Scaling group with a lifecycle hook that supports a custom action at instance launch. When the application experiences an increase in demand, Auto Scaling launches instances to add capacity. Because there is a lifecycle hook, the instance is put into the Pending:Wait state, which means that it is not available to handle traffic yet. When the instance enters the wait state, scaling actions due to simple scaling policies are suspended. When the instance enter the InService state, the cooldown period starts. When the cooldown period expires, any suspended scaling actions resume.

Health Check Grace Period

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

Lifecycle Action Result

At the conclusion of a lifecycle hook, the result is either ABANDON or CONTINUE.

If the instance is launching, CONTINUE indicates that your actions were successful, and that Auto Scaling can put the instance into service. Otherwise, ABANDON indicates that your custom actions were unsuccessful, and that 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, while CONTINUE allows any other lifecycle hooks to complete.

Spot Instances

You can use lifecycle hooks with Spot Instances. However, a lifecycle hook does not prevent an instance from terminating due to a change in the Spot Price, which can happen at any time. 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 optionally configure notifications when the instance enters a wait state, which enables you to perform a custom action. You can use Amazon CloudWatch Events, Amazon SNS, or Amazon SQS to receive the notifications. Choose whichever option you prefer.

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.

Receive Notification Using CloudWatch Events

You can use CloudWatch Events to set up a target to invoke a Lambda function when a lifecycle action occurs.

To set up notifications using CloudWatch Events

  1. Create a Lambda function using the steps in Create a Lambda Function and note its Amazon Resource Name (ARN). For example, arn:aws:lambda:us-west-2:123456789012:function:my-function.

  2. Create a CloudWatch Events rule that matches the lifecycle action using the following put-rule command:

    aws events put-rule --name my-rule --event-pattern file://pattern.json --state ENABLED

    The pattern.json for an instance launch lifecycle action is:

    {
      "source": [ "aws.autoscaling" ],
      "detail-type": [ "EC2 Instance-launch Lifecycle Action" ]
    }

    The pattern.json for an instance terminate lifecycle action is:

    {
      "source": [ "aws.autoscaling" ],
      "detail-type": [ "EC2 Instance-terminate Lifecycle Action" ]
    }
  3. Create a target that invokes your Lambda function when the lifecycle action occurs, using the following put-targets command:

    aws events put-targets --rule my-rule --targets Id=1,Arn=arn:aws:lambda:us-west-2:123456789012:function:my-function
  4. When Auto Scaling responds to a scale out or scale in event, it puts the instance in a wait state. While the instance is in a wait state, the Lambda function is invoked. For more information about the event data, see Auto Scaling Events.

Receive Notification Using Amazon SNS

You can use Amazon SNS to set up a notification target to receive notifications when a lifecycle action occurs.

To set up notifications using Amazon SNS

  1. Create the target using Amazon SNS. For more information, see Create a Topic in the Amazon Simple Notification Service Developer Guide. Note the ARN of the target (for example, arn:aws:sns:us-west-2:123456789012:my-sns-topic).

  2. Create an IAM role to grant Auto Scaling permission to access your notification target, using the steps in Creating a Role to Delegate Permissions to an AWS Service in the IAM User Guide. When prompted to select a role type, select AWS Service Roles, AutoScaling Notification Access. Note the ARN of the role. For example, arn:aws:iam::123456789012:role/my-notification-role.

  3. When Auto Scaling responds to a scale out or scale in event, it puts the instance in a wait state. While the instance is in a wait state, Auto Scaling publishes a message to the notification target. The message includes the following event data:

    • LifecycleActionToken — The lifecycle action token.

    • AccountId — The AWS account ID.

    • AutoScalingGroupName — The name of the Auto Scaling group.

    • LifecycleHookName — The name of the lifecycle hook.

    • EC2InstanceId — The ID of the EC2 instance.

    • LifecycleTransition — The lifecycle hook type.

    For example:

    Service: AWS Auto Scaling
    Time: 2016-09-30T20:42:11.305Z
    RequestId: 18b2ec17-3e9b-4c15-8024-ff2e8ce8786a
    LifecycleActionToken: 71514b9d-6a40-4b26-8523-05e7ee35fa40
    AccountId: 123456789012
    AutoScalingGroupName: my-asg
    LifecycleHookName: my-hook
    EC2InstanceId: i-0598c7d356eba48d7
    LifecycleTransition: autoscaling:EC2_INSTANCE_LAUNCHING
    NotificationMetadata: null

Receive Notification Using Amazon SQS

You can use Amazon SQS to set up a notification target to receive notifications when a lifecycle action occurs.

To set up notifications using Amazon SQS

  1. Create the target using Amazon SQS. For more information, see Creating a Queue in the Amazon Simple Queue Service Getting Started Guide. Note the ARN of the target.

  2. Create an IAM role to grant Auto Scaling permission to access your notification target, using the steps in Creating a Role to Delegate Permissions to an AWS Service in the IAM User Guide. When prompted to select a role type, select AWS Service Roles, AutoScaling Notification Access. Note the ARN of the role. For example, arn:aws:iam::123456789012:role/my-notification-role.

  3. When Auto Scaling responds to a scale out or scale in event, it puts the instance in a wait state. While the instance is in a wait state, Auto Scaling publishes a message to the notification target.

Add Lifecycle Hooks

Create one or more lifecycle hooks using the put-lifecycle-hook command:

aws autoscaling put-lifecycle-hook --lifecycle-hook-name my-hook --auto-scaling-group-name my-asg

To perform an action on scale out, add the following option:

--lifecycle-transition autoscaling:EC2_INSTANCE_LAUNCHING

To perform an action on scale in, add the following option instead:

--lifecycle-transition autoscaling:EC2_INSTANCE_TERMINATING

(Optional) If you are using a notification, add the following options:

--notification-target-arn arn:aws:sns:us-west-2:123456789012:my-sns-topic \
--role-arn arn:aws:iam::123456789012:role/my-notification-role

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 Auto Scaling Account Limits.

Complete the Lifecycle Hook

When Auto Scaling responds to a scale out or scale in event, it puts the instance in a wait state and sends any notifications. Auto Scaling continues the launch or terminate process after you complete the lifecycle hook.

To complete a lifecycle hook

  1. While the instance is in a wait state, you can perform a custom action. For more information, see Prepare for Notifications.

  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 you received in the previous step, as shown in the following command:

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

    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 --instance-id i-1a2b3c4d --lifecycle-hook-name my-launch-hook --auto-scaling-group-name my-asg
  3. If you finish the custom action before the timeout period ends, use the complete-lifecycle-action command so that Auto Scaling can continue launching or terminating the instance. Note that you can specify the lifecycle action token, as shown in the following command:

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

    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. Auto Scaling launches the EC2 instance, and you'll receive a notification within a few minutes.

To change the desired capacity using the 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. Note that 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.