Tutorial: Configure a lifecycle hook that invokes a Lambda function

Open the Policies page of the IAM console, and then choose Create policy.

Choose the JSON tab.

In the Policy Document box, paste the following policy document into the box, replacing the text in italics with your account number and the name of your Auto Scaling group.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "autoscaling:CompleteLifecycleAction"
      ],
      "Resource": "arn:aws:autoscaling:*:123456789012:autoScalingGroup:*:autoScalingGroupName/my-asg"
    }
  ]
}

Choose Next.

For Policy name, enter LogAutoScalingEvent-policy. Choose Create policy.

In the navigation pane on the left, choose Roles.

Choose Create role.

For Select trusted entity, choose AWS service.

For your use case, choose Lambda and then choose Next.

Under Add permissions, choose the policy that you created (LogAutoScalingEvent-policy) and the policy named AWSLambdaBasicExecutionRole. Then, choose Next.

On the Name, review, and create page, for Role name, enter LogAutoScalingEvent-role and choose Create role.

Open the Functions page on the Lambda console.

Choose Create function, Author from scratch.

Under Basic information, for Function name, enter LogAutoScalingEvent.

For Runtime, choose Node.js 18.x.

Scroll down and choose Change default execution role, and then for Execution role, choose Use an existing role.

For Existing role, choose LogAutoScalingEvent-role.

Leave the other default values.

Choose Create function. You are returned to the function's code and configuration.

With your LogAutoScalingEvent function still open in the console, under Code source, in the editor, paste the following sample code into the file named index.mjs.

import { AutoScalingClient, CompleteLifecycleActionCommand } from "@aws-sdk/client-auto-scaling";
export const handler = async(event) => {
  console.log('LogAutoScalingEvent');
  console.log('Received event:', JSON.stringify(event, null, 2));
  var autoscaling = new AutoScalingClient({ region: event.region });
  var eventDetail = event.detail;
  var params = {
    AutoScalingGroupName: eventDetail['AutoScalingGroupName'], /* required */
    LifecycleActionResult: 'CONTINUE', /* required */
    LifecycleHookName: eventDetail['LifecycleHookName'], /* required */
    InstanceId: eventDetail['EC2InstanceId'],
    LifecycleActionToken: eventDetail['LifecycleActionToken']
  };
  var response;
  const command = new CompleteLifecycleActionCommand(params);
  try {
    var data = await autoscaling.send(command);
    console.log(data); // successful response
    response = {
      statusCode: 200,
      body: JSON.stringify('SUCCESS'),
    };
  } catch (err) {
    console.log(err, err.stack); // an error occurred
    response = {
      statusCode: 500,
      body: JSON.stringify('ERROR'),
    };
  }
  return response;
};

This code simply logs the event so that, at the end of this tutorial, you can see an event appear in the CloudWatch Logs log stream that's associated with this Lambda function.

Choose Deploy.

Open the EventBridge console.

In the navigation pane, choose Rules.

Choose Create rule.

For Define rule detail, do the following:

1. For Name, enter LogAutoScalingEvent-rule.

2. For Event bus, choose default. When an AWS service in your account generates an event, it always goes to your account's default event bus.

3. For Rule type, choose Rule with an event pattern.

4. Choose Next.

For Build event pattern, do the following:

1. For Event source, choose AWS events or EventBridge partner events.

2. Scroll down to Event pattern, and do the following:

3. 1. For Event source, choose AWS services.

   2. For AWS service, choose Auto Scaling.

   3. For Event type, choose Instance Launch and Terminate.

   4. By default, the rule matches any scale-in or scale-out event. To create a rule that notifies you when there is a scale-out event and an instance is put into a wait state due to a lifecycle hook, choose Specific instance event(s) and select EC2 Instance-launch Lifecycle Action.

   5. By default, the rule matches any Auto Scaling group in the Region. To make the rule match a specific Auto Scaling group, choose Specific group name(s) and select the group.

   6. Choose Next.

For Select target(s), do the following:

1. For Target types, choose AWS service.

2. For Select a target, choose Lambda function.

3. For Function, choose LogAutoScalingEvent.

4. Choose Next twice.

On the Review and create page, choose Create rule.

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 LogAutoScalingEvent-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 Lambda function.

4. For Default result, choose ABANDON. This means that the Auto Scaling group will terminate a new instance if the hook times out without receiving a callback from your Lambda function.

5. (Optional) Leave Notification metadata empty. The event data that we pass to EventBridge contains all of the necessary information to invoke the Lambda function.

Choose Create.

Open the Auto Scaling groups page of the Amazon EC2 console.

Select the check box next to your Auto Scaling group to view details in a lower pane and still see 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.

Open the Log groups page of the CloudWatch console.

Select the name of the log group for your Lambda function (/aws/lambda/LogAutoScalingEvent).

Select the name of the log stream to view the data provided by the function for the lifecycle action.

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.

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 (LogAutoScalingEvent-hook).

Choose Actions, Delete.

Choose Delete again to confirm.

Open the Rules page in the Amazon EventBridge console.

Under Event bus, choose the event bus that is associated with the rule (Default).

Select the check box next to your rule (LogAutoScalingEvent-rule).

Choose Delete.

When prompted for confirmation, type the name of the rule and then choose Delete.

Open the Functions page on the Lambda console.

Choose the function (LogAutoScalingEvent).

Choose Actions, Delete.

When prompted for confirmation, type delete to confirm deleting the specified function and then choose Delete.

Open the Log groups page of the CloudWatch console.

Select the function's log group (/aws/lambda/LogAutoScalingEvent).

Choose Actions, Delete log group(s).

In the Delete log group(s) dialog box, choose Delete.

Open the Roles page of the IAM console.

Select the function's role (LogAutoScalingEvent-role).

Choose Delete.

When prompted for confirmation, type the name of the role and then choose Delete.

Open the Policies page of the IAM console.

Select the policy that you created (LogAutoScalingEvent-policy).

Choose Actions, Delete.

When prompted for confirmation, type the name of the policy and then choose Delete.