AWS CDK AutoScaling Lifecycle Hook Targets (v1)

Common errors

• ModuleNotFoundError: No module named 'aws_cdk.aws_autoscaling_hooktargets'

  cause Attempting to use this CDK v1-specific package in a CDK v2 project, or the package was not installed in a v1 project.
  fix If using CDK v2, remove this package and use `aws_cdk.aws_autoscaling` directly. If using CDK v1, ensure `pip install aws-cdk.aws-autoscaling-hooktargets` has been run.

• TypeError: Argument 'notification_target' must be of type aws_cdk.aws_autoscaling.ILifecycleHookTarget. Got <class 'aws_cdk.aws_autoscaling_hooktargets.TopicHookTarget'>

  cause Passing a CDK v1 hook target object to a CDK v2 `LifecycleHook` construct, which expects a v2-compatible target interface.
  fix Refactor your code for CDK v2. Instead of `TopicHookTarget(topic)`, you'll directly configure the `notification_target` property of the `LifecycleHook` (e.g., using `aws_cdk.aws_autoscaling.NotificationConfigurationProperty` or a custom v2 `ILifecycleHookTarget` implementation).

• The service-linked role for EC2 Auto Scaling does not have permissions to publish to the SNS topic.

  cause The IAM permissions of the Auto Scaling Service-Linked Role are insufficient to perform actions on the specified lifecycle hook target.
  fix Verify that the Auto Scaling Service-Linked Role (`AWSServiceRoleForAutoScaling`) has the necessary permissions for the target resource. For an SNS topic, this means `sns:Publish` permission on the topic's ARN.

Warnings

• breaking This library (`aws-cdk.aws-autoscaling-hooktargets`) is specific to AWS CDK v1. It is not compatible with AWS CDK v2.
  Fix: For AWS CDK v2, do not install this package. Its functionality is integrated directly into `aws-cdk-lib.aws_autoscaling`. You should use `aws_cdk.aws_autoscaling.LifecycleHook` and pass appropriate `notification_target` properties or implement `aws_cdk.aws_autoscaling.ILifecycleHookTarget` directly.
• deprecated As of CDK v2, dedicated `*-hooktargets` modules are deprecated in favor of direct integration into `aws-cdk-lib`'s primary service modules.
  Fix: Migrate your CDK application to v2. Install `aws-cdk-lib` and `constructs`, then refactor your lifecycle hook definitions to use the v2 API within `aws_cdk.aws_autoscaling`.
• gotcha AWS Auto Scaling lifecycle hooks require proper IAM permissions for the Auto Scaling Service-Linked Role to interact with the specified targets (SNS, SQS, Lambda).
  Fix: Ensure the Auto Scaling Service-Linked Role (`AWSServiceRoleForAutoScaling`) has the necessary permissions (e.g., `sns:Publish` for SNS, `sqs:SendMessage` for SQS, `lambda:InvokeFunction` for Lambda) on the target resources. While CDK often attempts to add these, explicit policies may be needed in complex scenarios or if default permissions are overridden.
• gotcha Incorrectly configured `heartbeat_timeout` or `default_result` for a lifecycle hook can lead to instances hanging or prematurely continuing/abandoning the lifecycle action.
  Fix: Carefully consider the expected duration of custom actions performed during the hook and set `heartbeat_timeout` accordingly. Use `default_result=autoscaling.DefaultResult.ABANDON` if you want instances to terminate without completing the action, or `default_result=autoscaling.DefaultResult.CONTINUE` if you want them to proceed even if the hook action fails or times out.

Install

• pip install aws-cdk.aws-autoscaling-hooktargets Install for CDK v1

Imports

• TopicHookTarget
  wrong:

  from aws_cdk.aws_autoscaling.TopicHookTarget import ...

  correct:

  from aws_cdk.aws_autoscaling_hooktargets import TopicHookTarget

  This specific construct resides in the hooktargets module, not directly under aws_autoscaling.
• QueueHookTarget

  from aws_cdk.aws_autoscaling_hooktargets import QueueHookTarget

• LambdaFunctionHookTarget

  from aws_cdk.aws_autoscaling_hooktargets import LambdaFunctionHookTarget

Quickstart

This quickstart demonstrates how to create an AWS Auto Scaling Group with a lifecycle hook configured to publish notifications to an SNS Topic upon instance launch, using the `TopicHookTarget` from this library. This example is for CDK v1. Make sure to replace `os.environ.get('CDK_DEFAULT_REGION')` with a concrete region if not set.

import os
from aws_cdk import (
    Stack,
    App,
    Duration,
    aws_ec2 as ec2,
    aws_autoscaling as autoscaling,
    aws_sns as sns,
)
from aws_cdk.aws_autoscaling_hooktargets import TopicHookTarget
from constructs import Construct

class AutoScalingHookStack(Stack):
    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        vpc = ec2.Vpc(self, "VPC", max_azs=2)

        # Create an SNS Topic to receive notifications
        topic = sns.Topic(self, "LifecycleHookTopic")

        # Create an Auto Scaling Group
        asg = autoscaling.AutoScalingGroup(self, "ASG",
            vpc=vpc,
            instance_type=ec2.InstanceType.of(ec2.InstanceClass.T2, ec2.InstanceSize.MICRO),
            machine_image=ec2.AmazonLinuxImage(),
            min_capacity=0,
            max_capacity=1,
            desired_capacity=0 # Start at 0 to see hooks fire on scale-out
        )

        # Add a lifecycle hook targeting the SNS Topic
        asg.add_lifecycle_hook("ScalingOutHook",
            lifecycle_transition=autoscaling.LifecycleTransition.AUTO_SCALING_LAUNCH,
            notification_target=TopicHookTarget(topic),
            default_result=autoscaling.DefaultResult.CONTINUE,
            heartbeat_timeout=Duration.minutes(5)
        )

# Example of how to synthesize the stack
# app = App()
# AutoScalingHookStack(app, "AutoScalingHookExampleStack",
#   env={'region': os.environ.get('CDK_DEFAULT_REGION', 'us-east-1')})
# app.synth()