CreateLifecycleHook - Auto Scaling

Creates a lifecycle hook. A lifecycle hook allows you to execute custom actions such as sending notifications or automating script execution at critical stages (such as startup and termination) in the lifecycle of an instance. Implementing the lifecycle hook feature allows for finer control and management of instances. For example, you can verify configurations, set up custom tasks, or back up data on your instances when lifecycle hooks take effect, thus enhancing the flexibility and reliability of application deployment.

Usage notes

You can create up to six lifecycle hooks for each scaling group. During scaling events, Elastic Compute Service (ECS) instances are not immediately added to or removed from scaling groups that have active lifecycle hooks. Instead, the instances are added to or removed from the scaling groups only after the lifecycle hooks time out. The period for which a lifecycle hook remains active is determined by the value of HeartbeatTimeout. You can execute custom operations, such as initializing the configurations of ECS instances and querying data on ECS instances, before lifecycle hooks time out.
During scale-out events, the private IP addresses of ECS instances are added to the IP address whitelists of the associated ApsaraDB RDS instances. However, the ECS instances are added to the backend server groups of the associated Server Load Balancer (SLB) instances only after lifecycle hooks time out. During scale-in events, ECS instances are removed from the backend server groups of the associated SLB instances. However, the private IP addresses of the ECS instances are removed from the IP address whitelists of the associated ApsaraDB RDS instances only after lifecycle hooks time out.
You must specify a notification recipient for each lifecycle hook. When lifecycle hooks are triggered, notifications can be sent by using Simple Message Queue (SMQ, formerly MNS) topics, SMQ queues, or CloudOps Orchestration Service (OOS) templates. If you want to configure an OOS template, you must create a Resource Access Management (RAM) role for OOS. For more information, see Grant RAM permissions to OOS.

Note

If your scaling group contains existing ECS instances, and you have specified an OOS template to add or remove their private IP addresses to or from the IP address whitelists of cloud databases other than ApsaraDB RDS instances, you must manually add or remove the private IP addresses to or from the whitelists.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter	Type	Required	Example	Description
Action	String	Yes	CreateLifecycleHook	The operation that you want to perform. Set the value to CreateLifecycleHook.
ScalingGroupId	String	Yes	asg-bp1eyv4qn8ssgv43****	The ID of the scaling group.
LifecycleHookName	String	No	lifecyclehook****	The name of the lifecycle hook that you want to create. Each lifecycle hook name must be unique in a scaling group. The name must be 2 to 64 characters in length and can contain letters, digits, underscores (_), hyphens (-), and periods (.). The name must start with a letter or a digit. If you do not specify this parameter, the value of LifecycleHookId is used.
LifecycleTransition	String	Yes	SCALE_OUT	The type of the scaling event to which you want to apply the lifecycle hook. Valid values: SCALE_OUT: the scale-out event. SCALE_IN: the scale-in event.
DefaultResult	String	No	CONTINUE	The action that Auto Scaling performs after the lifecycle hook times out. Valid values: CONTINUE: Auto Scaling continues to respond to scaling requests. ABANDON: Auto Scaling releases ECS instances that are created during scale-out events, or removes ECS instances from the scaling group during scale-in events. ROLLBACK: During scale-in events, Auto Scaling does not release ECS instances, but rolls back the ECS instances. During scale-out events, the ROLLBACK setting functions in the same way as the `ABANDON` setting. If a scaling group has multiple lifecycle hooks in effect and you set `DefaultResult` for one of the lifecycle hooks to `ABANDON` or `ROLLBACK`, the following rule applies to scale-in events: When the lifecycle hook whose DefaultResult is set to ABANDON or ROLLBACK times out, other lifecycle hooks time out ahead of schedule. In other cases, Auto Scaling performs the action only after all lifecycle hooks time out. The action that Auto Scaling performs is determined by the value of DefaultResult that you specify for the lifecycle hook that most recent times out. Default value: CONTINUE.
HeartbeatTimeout	Integer	No	600	The period of time before the lifecycle hook times out. After the lifecycle hook times out, Auto Scaling performs the default action. Valid values: 30 to 21600. Unit: seconds. After you create a lifecycle hook, you can call the RecordLifecycleActionHeartbeat operation to extend the timeout period of the lifecycle hook. You can also call the CompleteLifecycleAction operation to end the timeout period ahead of schedule. Default value: 600.
NotificationMetadata	String	No	Test lifecycle hook.	The notification information that Auto Scaling sends to the recipient specified by `NotificationArn` when the lifecycle hook takes effect. This parameter helps you manage and label notifications of different types. If you specify this parameter, you must specify `NotificationArn`. The value of this parameter cannot exceed 4,096 characters in length. If you use `NotificationArn` to specify a public or custom OOS template, the value of `NotificationMetadata` must be a JSON string that contains the OOS template parameters. For example, if your CloudOps Orchestration Service (OOS) template contains `{"dbInstanceId": "dds-bp17661e0135**", "modifyMode": "Append"}`, `dbInstanceId`, and `modifyMode`, the value of NotificationMetadata must be a JSON string that contains the preceding parameters. When specifying `NotificationMetadata` in your OOS template, make sure to only specify parameters that do not have default values. If you specify parameters that already have default values, those defaults will be overwritten. You must retain the default values of the following parameters to obtain information about ongoing scaling events. regionId: the region ID of the scaling event that is in progress. Default value: ${regionId}. instanceIds: the IDs of the ECS instances that are scaled during the scaling event. Default value: ${instanceIds}. lifecycleHookId: the ID of the lifecycle hook. Default value: ${lifecycleHookId}. lifecycleActionToken: the token of the lifecycle hook. You can use the token to end the timeout period of the lifecycle hook ahead of schedule. Default value: ${lifecycleActionToken} scalingGroupId: the ID of the scaling group in which the scaling event occurs. Default value: ${scalingGroupId}. lifecycleActionResult: the action that Auto Scaling performs after the lifecycle hook times out. If the OOS template fails to be executed, the lifecycle hook times out ahead of schedule. If you set `DefalutResult` to `ROLLBACK`, the default value of this parameter is `ROLLBACK`. If you set `DefaultResult` to other values, the default value of this parameter is ABANDON. Note** You can specify a value for `lifecycleActionResult` to overwrite the default value. Valid values: ABANDON, CONTINUE, ROLLBACK, and ${lifecycleActionResult}. A value of `${lifecycleActionResult}` specifies that the value of lifecycleActionResult is the same as the value of DefaultResult. You can view the details of the OOS template that you specify in the OOS console.
NotificationArn	String	No	acs:mns:cn-beijing:161456884340**:queue/modifyLifecycleHo**	The Alibaba Cloud Resource Name (ARN) of the notification recipient. If you do not specify this parameter, no notification is sent when the lifecycle hook takes effect. If you specify this parameter, the following rules apply: If you specify an SMQ queue as the notification recipient, specify the value in the `acs:mns:{region-id}:{account-id}:queue/{queuename}` format. If you specify an SMQ topic as the notification recipient, specify the value in the `acs:mns:{region-id}:{account-id}:topic/{topicname}` format. If you specify an OOS template as the notification recipient, specify the value in the `acs:oos:{region-id}:{account-id}:template/{templatename}` format. If you specify an event bus provided by EventBridge as the notification recipient, specify the value in the `acs:eventbridge:{region-id}:{account-id}:eventbus/default` format. The variables in the preceding value formats have the following meanings: region-id: the region ID of the scaling group. account-id: the ID of the Alibaba Cloud account. IDs of RAM users are not supported. queuename: the name of the SMQ queue. topicname: the name of the SMQ topic. templatename: the name of the OOS template.

Response parameters

Parameter	Type	Example	Description
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3****	The ID of the request.
LifecycleHookId	String	ash-bp1at9ufhmcf9cmy****	The ID of the lifecycle hook.

Examples

Sample requests

http(s)://ess.aliyuncs.com/?Action=CreateLifecycleHook
&ScalingGroupId=asg-bp1eyv4qn8ssgv43****
&LifecycleHookName=lifecyclehook****
&LifecycleTransition=SCALE_OUT
&DefaultResult=CONTINUE
&HeartbeatTimeout=600
&NotificationMetadata=Test lifecycle hook.
&NotificationArn=acs:mns:cn-beijing:161456884340****:queue/modifyLifecycleHo****
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateLifecycleHookResponse>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3****</RequestId>
    <LifecycleHookId>ash-bp1at9ufhmcf9cmy****</LifecycleHookId>
</CreateLifecycleHookResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****",
  "LifecycleHookId" : "ash-bp1at9ufhmcf9cmy****"
}

Error codes

For a list of error codes, see Service error codes.

HTTP status code	Error code	Description	Description
400	InvalidParamter	The specified value of parameter is not valid.	The value of a parameter is invalid.
400	InvalidNotificationArn	The specified parameter notificationArn is invalid.	The value of NotificationArn is invalid.
400	UnsupportedNotificationType.CurrentRegion	The notificationType is not supported in the special region which scalingGroup belongs to.	The notification recipient is not supported in the current region.
400	QueueNotExist	The specified queue does not exist.	The specified SMQ queue does not exist.
400	TopicNotExist	The specified topic does not exist.	The MNS topic does not exist.
400	InvalidLifecycleHookName.Duplicate	The specified value of parameter lifecycleHookName is duplicated.	The name of the lifecycle hook already exists.
400	QuotaExceeded.LifecycleHook	Lifecycle hook quota exceeded in the specified scaling group.	The maximum number of lifecycle hooks that you can create has been reached.