Creates one or more lifecycle hooks in a scaling group.

Description

You can create a maximum of six lifecycle hooks for each scaling group. After a lifecycle hook is created for a scaling group, Elastic Compute Service (ECS) instances in the scaling group are put into the wait state during scaling activities. You can use the HeartbeatTimeout parameter to specify the timeout period of the lifecycle hook. While an ECS instance is in the wait state, you can perform operations on the instance, such as downloading data and initializing the configurations of the instance.

During a scale-out event, ECS instances enter the wait state after their IP addresses are added to the whitelist of the associated ApsaraDB RDS instance. When the wait state ends, the ECS instances are added to the associated Server Load Balancer (SLB) backend server group. During a scale-in event, ECS instances enter the wait state after they are removed from the associated SLB backend server group. When the wait state ends, their IP addresses are removed from the whitelist of the associated RDS instance.

You can configure a notification method for a lifecycle hook. When the lifecycle hook is triggered, a notification can be sent to the specified Message Service (MNS) topic or queue, or an operation can be performed based on the specified Operation Orchestration Service (OOS) template. 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 a scaling group has existing ECS instances and has OOS templates configured to add ECS instances to or remove ECS instances from the whitelist of an ApsaraDB service other than RDS, you must manually add the existing ECS instances to the whitelist of the ApsaraDB service.

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.

LifecycleTransition String Yes SCALE_OUT

The type of the scaling activity to which the lifecycle hook applies. Valid values:

  • SCALE_OUT: scale-out events
  • SCALE_IN: scale-in events
ScalingGroupId String Yes asg-bp1eyv4qn8ssgv43****

The ID of the scaling group.

LifecycleHookName String No lifecyclehook****

The name of the lifecycle hook. Each lifecycle hook name must be unique within a scaling group. The name must be 2 to 64 characters in length and can contain letters, digits, underscores (_), hyphens (-), and periods (.). It must start with a letter or a digit.

The default value is the value of LifecycleHookId.

DefaultResult String No CONTINUE

The action to take when the lifecycle hook times out. Valid values:

  • CONTINUE: Auto Scaling continues to respond to a scale-in or scale-out event.
  • ABANDON: Auto Scaling releases the created ECS instances if the scaling activity type is scale-out or removes the ECS instances to be scaled in if the scaling activity type is scale-in.

When multiple lifecycle hooks are triggered in a scaling group during a scale-in event, the remaining lifecycle hooks in the scaling group are terminated ahead of schedule if a lifecycle hook whose DefaultResult is set to ABANDON times out. In other cases, the action to take is subject to the action specified for the last lifecycle hook.

Default value: CONTINUE.

HeartbeatTimeout Integer No 600

The period of time before the lifecycle hook times out. When 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 and keep the instances in the wait state. You can also call the CompleteLifecycleAction operation to terminate the wait state of a scaling activity.

Default value: 600.

NotificationMetadata String No Test lifecycle hook.

The notification information that is pushed to a notification object (NotificationArn) when the lifecycle hook suspends a scaling activity. This helps you manage and identify different types of notification information. You must also specify NotificationArn. The parameter value cannot exceed 4,096 characters in length.

If NotificationArn is specified as an OOS template such as a public OOS template or a custom OOS template, NotificationMetadata must be specified as a JSON string that contains the parameters specified in the OOS template. For example, {"dbInstanceId": "dds-bp17661e0135****", "modifyMode": "Append"}, dbInstanceId, and modifyMode are parameters defined in an OOS template. Some parameters in OOS templates have default values. You must specify parameters that do not have default values in NotificationMetadata. If you specify parameters that have default values in NotificationMetadata, the original default values are overwritten. However, you must maintain the default values for the following parameters to obtain related information when a scaling activity is triggered:

  • regionId: the region where the scaling activity is executed. Default value: ${regionId}.
  • instanceIds: the list of instances that are involved in the scaling activity. Default value: ${instanceIds}.
  • lifecycleHookId: the ID of the lifecycle hook. Default value: ${lifecycleHookId}.
  • lifecycleActionToken: the wait state token of the scaling activity, which is used to terminate the current scaling activity ahead of schedule. Default value: ${lifecycleActionToken}.
  • scalingGroupId: the ID of the scaling group to which the scaling activity belongs. Default value: ${scalingGroupId}.
Note You can also obtain the parameter information of the corresponding template in the OOS console.
NotificationArn String No acs:mns:cn-beijing:161456884340****:queue/modifyLifecycleHo****

The Alibaba Cloud Resource Name (ARN) of the notification object that Auto Scaling uses to notify you when ECS instances are put into the wait state by the lifecycle hook. If you do not set this parameter, Auto Scaling does not send you notifications. If you set this parameter, Auto Scaling sends you notifications of the following types:

  • MNS queue. The format of the parameter value is acs:mns:{region-id}:{account-id}:queue/{queuename}.
  • MNS topic. The format of the parameter value is acs:mns:{region-id}:{account-id}:topic/{topicname}.
  • OOS template. The format of the parameter value is acs:oos:{region-id}:{account-id}:template/{templatename}.

The variables in the preceding parameter formats have the following meanings:

  • region-id: the region ID of the scaling group.
  • account-id: the ID of the Alibaba Cloud account. The ID of the RAM user is not supported.
  • queuename: the name of the MNS queue.
  • topicname: the name of the MNS topic.
  • templatename: the name of the OOS template.

Response parameters

Parameter Type Example Description
LifecycleHookId String ash-bp1at9ufhmcf9cmy****

The ID of the lifecycle hook.

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

Examples

Sample requests

https://ess.aliyuncs.com/?Action=CreateLifecycleHook
&ScalingGroupId=asg-bp1eyv4qn8ssgv43****
&LifecycleHookName=lifecyclehook****
&LifecycleTransition=SCALE_OUT
&NotificationArn=acs:mns:cn-beijing:161456884340****:queue/modifyLifecycleHo****
&NotificationMetadata=Test lifecycle hook.
&<Common request parameters>|

Sample success responses

XML format

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

JSON format

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

Error codes

For a list of error codes, visit the API Error Center.

HTTP status code

Error code

Error message

Description

400

InvalidParamter

The specified value of parameter is not valid.

The error message returned because a specified parameter is invalid.

400

InvalidNotificationArn

The specified parameter notificationArn is invalid.

The error message returned because the specified NotificationArn parameter is invalid.

400

UnsupportedNotificationType.CurrentRegion

The notificationType is not supported in the special region which scalingGroup belongs to.

The error message returned because the notification type is not supported in the region to which the scaling group belongs.

400

QueueNotExist

The specified queue does not exist.

The error message returned because the specified MNS queue does not exist.

400

TopicNotExist

The specified topic does not exist.

The error message returned because the specified MNS topic does not exist.

400

InvalidLifecycleHookName.Duplicate

The specified value of parameter lifecycleHookName is duplicated.

The error message returned because the specified lifecycle hook name already exists.

400

QuotaExceeded.LifecycleHook

Lifecycle hook quota exceeded in the specified scaling group.

The error message returned because the maximum number of lifecycle hooks that can be created for the scaling group has been reached. A maximum of six lifecycle hooks can be created for each scaling group.