Step 1: Create an IAM role with permissions to complete lifecycle actions Step 2: Create a launch template and include the IAM role and a user data script Step 3: Create an Auto Scaling group Step 4: Add a lifecycle hook Step 5: Test and verify the functionality Step 6: Clean up Related resources

Tutorial: Configure user data to retrieve the target lifecycle state through instance metadata

A common way to create custom actions for lifecycle hooks is to use notifications that Amazon EC2 Auto Scaling sends to other services, such as Amazon EventBridge. However, you can avoid having to create additional infrastructure by instead using a user data script to move the code that configures instances and completes the lifecycle action into the instances themselves.

The following tutorial shows you how to get started using a user data script and instance metadata. You create a basic Auto Scaling group configuration with a user data script that reads the target lifecycle state of the instances in your group and performs a callback action at a specific phase of an instance's lifecycle to continue the launch process.

The following illustration summarizes the flow for a scale-out event when you use a user data script to perform a custom action. After an instance launches, the lifecycle of the instance is paused until the lifecycle hook is completed, either by timing out or by Amazon EC2 Auto Scaling receiving a signal to continue.

Step 1: Create an IAM role with permissions to complete lifecycle actions
Step 2: Create a launch template and include the IAM role and a user data script
Step 3: Create an Auto Scaling group
Step 4: Add a lifecycle hook
Step 5: Test and verify the functionality
Step 6: Clean up
Related resources

Step 1: Create an IAM role with permissions to complete lifecycle actions

When you use the AWS CLI or an AWS SDK to send a callback to complete lifecycle actions, you must use an IAM role with permissions to complete lifecycle actions.

To create the policy

Open the Policies page of the IAM console, and then choose Create policy.
Choose the JSON tab.
In the Policy Document box, copy and paste the following policy document into the box. Replace the sample text with your account number and the name of the Auto Scaling group that you want to create (TestAutoScalingEvent-group).
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "autoscaling:CompleteLifecycleAction"
      ],
      "Resource": "arn:aws:autoscaling:*:123456789012:autoScalingGroup:*:autoScalingGroupName/TestAutoScalingEvent-group"
    }
  ]
}
```
Choose Next.
For Policy name, enter TestAutoScalingEvent-policy. Choose Create policy.

When you finish creating the policy, you can create a role that uses it.

To create the role

In the navigation pane on the left, choose Roles.
Choose Create role.
For Select trusted entity, choose AWS service.
For your use case, choose EC2 and then choose Next.
Under Add permissions, choose the policy that you created (TestAutoScalingEvent-policy). Then, choose Next.
On the Name, review, and create page, for Role name, enter TestAutoScalingEvent-role and choose Create role.

Step 2: Create a launch template and include the IAM role and a user data script

Create a launch template to use with your Auto Scaling group. Include the IAM role you created and the provided sample user data script.

To create a launch template

Open the Launch templates page of the Amazon EC2 console.
Choose Create launch template.
For Launch template name, enter TestAutoScalingEvent-template.
Under Auto Scaling guidance, select the check box.
For Application and OS Images (Amazon Machine Image), choose Amazon Linux 2 (HVM), SSD Volume Type, 64-bit (x86) from the Quick Start list.
For Instance type, choose a type of Amazon EC2 instance (for example, "t2.micro").
For Advanced details, expand the section to view the fields.
For IAM instance profile, choose the IAM instance profile name of your IAM role (TestAutoScalingEvent-role). An instance profile is a container for an IAM role that allows Amazon EC2 to pass the IAM role to an instance when the instance is launched.

When you used the IAM console to create an IAM role, the console automatically created an instance profile with the same name as its corresponding role.

For User data, copy and paste the following sample user data script into the field. Replace the sample text for group_name with the name of the Auto Scaling group that you want to create and region with the AWS Region you want your Auto Scaling group to use.


#!/bin/bash

function get_target_state {
    echo $(curl -s http://169.254.169.254/latest/meta-data/autoscaling/target-lifecycle-state)
}

function get_instance_id {
    echo $(curl -s http://169.254.169.254/latest/meta-data/instance-id)
}

function complete_lifecycle_action {
    instance_id=$(get_instance_id)
    group_name='TestAutoScalingEvent-group'
    region='us-west-2'
 
    echo $instance_id
    echo $region
    echo $(aws autoscaling complete-lifecycle-action \
      --lifecycle-hook-name TestAutoScalingEvent-hook \
      --auto-scaling-group-name $group_name \
      --lifecycle-action-result CONTINUE \
      --instance-id $instance_id \
      --region $region)
}

function main {
    while true
    do
        target_state=$(get_target_state)
        if [ \"$target_state\" = \"InService\" ]; then
            # Change hostname
            export new_hostname="${group_name}-$instance_id"
            hostname $new_hostname
            # Send callback
            complete_lifecycle_action
            break
        fi
        echo $target_state
        sleep 5
    done
}

main

This simple user data script does the following:

Calls the instance metadata to retrieve the target lifecycle state and instance ID from the instance metadata
Retrieves the target lifecycle state repeatedly until it changes to InService
Changes the hostname of the instance to the instance ID prepended with the name of the Auto Scaling group, if the target lifecycle state is InService
Sends a callback by calling the complete-lifecycle-action CLI command to signal Amazon EC2 Auto Scaling to CONTINUE the EC2 launch process

Choose Create launch template.
On the confirmation page, choose Create Auto Scaling group.

Note

For other examples that you can use as a reference for developing your user data script, see the GitHub repository for Amazon EC2 Auto Scaling.

Step 3: Create an Auto Scaling group

After you create your launch template, create an Auto Scaling group.

To create an Auto Scaling group

On the Choose launch template or configuration page, for Auto Scaling group name, enter a name for your Auto Scaling group (TestAutoScalingEvent-group).
Choose Next to go to the Choose instance launch options page.
For Network, choose a VPC.
For Availability Zones and subnets, choose one or more subnets from one or more Availability Zones.
In the Instance type requirements section, use the default setting to simplify this step. (Do not override the launch template.) For this tutorial, you will launch only one On-Demand Instance using the instance type specified in your launch template.
Choose Skip to review at the bottom of the screen.
On the Review page, review the details of your Auto Scaling group, and then choose Create Auto Scaling group.

Step 4: Add a lifecycle hook

Add a lifecycle hook to hold the instance in a wait state until your lifecycle action is complete.

To add a lifecycle hook

Open the Auto Scaling groups page of the Amazon EC2 console.
Select the check box next to your Auto Scaling group. A split pane opens up in the bottom of the page.
In the lower pane, on the Instance management tab, in Lifecycle hooks, choose Create lifecycle hook.
To define a lifecycle hook for scale out (instances launching), do the following:
1. For Lifecycle hook name, enter TestAutoScalingEvent-hook.
2. For Lifecycle transition, choose Instance launch.
3. For Heartbeat timeout, enter 300 for the number of seconds to wait for a callback from your user data script.
4. For Default result, choose ABANDON. If the hook times out without receiving a callback from your user data script, the Auto Scaling group terminates the new instance.
5. (Optional) Keep Notification metadata blank.
Choose Create.

Step 5: Test and verify the functionality

To test the functionality, update the Auto Scaling group by increasing the desired capacity of the Auto Scaling group by 1. The user data script runs and starts to check the instance's target lifecycle state soon after the instance launches. The script changes the hostname and sends a callback action when the target lifecycle state is InService. This usually takes only a few seconds to finish.

To increase the size of the Auto Scaling group

Open the Auto Scaling groups page of the Amazon EC2 console.
Select the check box next to your Auto Scaling group. View details in a lower pane while still seeing the top rows of the upper pane.
In the lower pane, on the Details tab, choose Group details, Edit.
For Desired capacity, increase the current value by 1.
Choose Update. While the instance is being launched, the Status column in the upper pane displays a status of Updating capacity.

After increasing the desired capacity, you can verify that your instance has successfully launched and is not terminated from the description of scaling activities.

To view the scaling activity

Return to the Auto Scaling groups page and select your group.
On the Activity tab, under Activity history, the Status column shows whether your Auto Scaling group has successfully launched an instance.
If the user data script fails, after the timeout period passes, you see a scaling activity with a status of Canceled and a status message of Instance failed to complete user's Lifecycle Action: Lifecycle Action with token e85eb647-4fe0-4909-b341-a6c42EXAMPLE was abandoned: Lifecycle Action Completed with ABANDON Result.

Step 6: Clean up

If you are done working with the resources that you created for this tutorial, use the following steps to delete them.

To delete the lifecycle hook

Open the Auto Scaling groups page of the Amazon EC2 console.
Select the check box next to your Auto Scaling group.
On the Instance management tab, in Lifecycle hooks, choose the lifecycle hook (TestAutoScalingEvent-hook).
Choose Actions, Delete.
Choose Delete again to confirm.

To delete the launch template

Open the Launch templates page of the Amazon EC2 console.
Select your launch template (TestAutoScalingEvent-template) and then choose Actions, Delete template.
When prompted for confirmation, type Delete to confirm deleting the specified launch template and then choose Delete.

If you are done working with the example Auto Scaling group, delete it. You can also delete the IAM role and permissions policy that you created.

To delete the Auto Scaling group

Open the Auto Scaling groups page of the Amazon EC2 console.
Select the check box next to your Auto Scaling group (TestAutoScalingEvent-group) and choose Delete.
When prompted for confirmation, type delete to confirm deleting the specified Auto Scaling group and then choose Delete.

A loading icon in the Name column indicates that the Auto Scaling group is being deleted. It takes a few minutes to terminate the instances and delete the group.

To delete the IAM role

Open the Roles page of the IAM console.
Select the function's role (TestAutoScalingEvent-role).
Choose Delete.
When prompted for confirmation, type the name of the role and then choose Delete.

To delete the IAM policy

Open the Policies page of the IAM console.
Select the policy that you created (TestAutoScalingEvent-policy).
Choose Actions, Delete.
When prompted for confirmation, type the name of the policy and then choose Delete.

The following related topics can be helpful as you develop code that invokes actions on instances based on data available in the instance metadata.

Retrieve the target lifecycle state through instance metadata. This section describes the lifecycle state for other use cases, such as instance termination.
Add lifecycle hooks (console). This procedure shows you how to add lifecycle hooks for both scale out (instances launching) and scale in (instances terminating or returning to a warm pool).
Instance metadata categories in the Amazon EC2 User Guide for Linux Instances. This topic lists all categories of instance metadata that you can use to invoke actions on EC2 instances.

For a tutorial that shows you how to use Amazon EventBridge to create rules that invoke Lambda functions based on events that happen to the instances in your Auto Scaling group, see Tutorial: Configure a lifecycle hook that invokes a Lambda function.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Complete a lifecycle action

Tutorial: Configure a lifecycle hook that invokes a Lambda function