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 termination 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 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 only remain in a wait state for a finite period of time. The default length of time 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 AWS CLI, use the --heartbeat-timeout parameter. With the API, 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.

You can only keep an instance in a wait state for a maximum of 48 hours, regardless of how often you increment the heartbeat timeout.

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).

Adding Lifecycle Hooks

When you add a lifecycle hook, you have the option to be notified when the instance enters a wait state so that you can perform the corresponding custom action. You can use Amazon CloudWatch Events, Amazon SNS, or Amazon SQS to receive the notifications.

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.

Use the following procedure to add a lifecycle hook.

Note

The first three steps are mutually exclusive, so they are listed as optional. Choose the step that meets your needs.

To add a lifecycle hook to an Auto Scaling group

  1. (Optional) If you would like to use CloudWatch Events to set up a target to invoke a Lambda function when a lifecycle action occurs, do the following:

    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
  2. (Optional) If you would like to use a notification target to receive notifications when a lifecycle action occurs, do the following:

    1. Create the target using Amazon SNS or Amazon SQS. For more information, see Create a Topic in the Amazon Simple Notification Service Developer Guide or Creating a Queue in the Amazon Simple Queue Service Getting Started 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. (Optional) 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.

  4. 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-auto-scaling-role
  5. 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, your custom action is initiated as follows:

    • If you defined a CloudWatch Events target for the lifecycle hook, the Lambda function is invoked. For more information about the event data, see Auto Scaling Events.

    • If you defined a notification target for the lifecycle hook, Auto Scaling publishes a message to the notification target. For more information about the message data, see SNS Notifications.

    • If you created a script that executes at instance launch, it is executed when Auto Scaling responds to a scale out event.

  6. 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
  7. 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