CreateLifecycleHook - Auto Scaling - Alibaba Cloud Documentation Center

Operation description

A scaling group can have a maximum of 6 lifecycle hooks. When a scaling activity occurs in a scaling group that has lifecycle hooks, the lifecycle hooks pause the scaling activity for an epoch. You can specify the wait epoch by using the HeartbeatTimeout parameter. During the wait epoch, you can perform operations such as initialization of ECS instance configurations and retrieving ECS instance data.
During a scale-out activity, ECS instances enter the wait state after they are added to the RDS instance whitelist, and are added to the backend server group of the SLB instance after the wait state ends. During a scale-down activity, ECS instances enter the wait state after they are removed from the backend server group of the SLB instance, and are removed from the RDS instance whitelist after the wait state ends.
You can configure notification methods for lifecycle hooks. The supported notification methods include MNS topics, MNS queues, and OOS templates. If you configure an OOS template, create a RAM role for the OOS service. For more information, see Settings RAM permissions for OOS.

Note

If the scaling group has existing ECS instances and the configured OOS template is used to add or remove instances from the whitelist of a database other than RDS, you must manually add the existing ECS instances to the whitelist of the database.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ess:CreateLifecycleHook

create

*ScalingGroup

acs:ess:{#regionId}:{#accountId}:scalinggroup/{#ScalingGroupId}

None

Request parameters

Parameter	Type	Required	Description	Example
ScalingGroupId	string	Yes	The ID of the scaling group.	asg-bp1eyv4qn8ssgv43****
LifecycleHookName	string	No	The name of the lifecycle hook. The name must be unique within the 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, digit, or Chinese character. Default value: the value of LifecycleHookId.	lifecyclehook****
LifecycleTransition	string	Yes	The type of scaling activity to which the lifecycle hook applies. Valid values: SCALE_OUT: scale-out activity of the scaling group. SCALE_IN: scale-down activity of the scaling group.	SCALE_OUT
DefaultResult	string	No	The action to take after the wait state ends. Valid values: CONTINUE: continues to response to the scale-out or scale-down activity. ABANDON: releases the ECS instances that are created during the scale-out activity, or removes the ECS instances from the scaling group during the scale-down activity. ROLLBACK: for a scale-down activity, the system deny the release of ECS instances and performs a rollback. For a scale-out activity, the system releases the created ECS instances, which has the same effect as ABANDON. When a scale-down activity (SCALE_IN) triggers multiple lifecycle hooks in a scaling group, if the DefaultResult of one lifecycle hook is set to ABANDON or ROLLBACK and the wait state of that hook ends, the wait states of the other lifecycle hooks end early. In other cases, the action to take is determined by the last lifecycle hook whose wait state ends. Default value: CONTINUE.	CONTINUE
HeartbeatTimeout	integer	No	The wait period that the lifecycle hook sets for the scaling group activity. After the wait state times out, the next action is performed. Valid values: 30 to 21600. Unit: seconds. After a lifecycle hook is created, you can call RecordLifecycleActionHeartbeat to extend the wait period of an ECS instance, or call CompleteLifecycleAction to end the wait state of a scaling activity early. Default value: 600.	600
NotificationMetadata	string	No	The notification information that is pushed to NotificationArn (the notification recipient) when the lifecycle hook suspends a scaling activity. This parameter helps you manage and tag notification information of different categories. You must also specify NotificationArn. The value can be up to 4,096 characters in length. If NotificationArn is set to an OOS template, including a public template or a custom template, NotificationMetadata must be set to a JSON string that matches the parameters of the OOS template. For example, `{"dbInstanceId": "dds-bp17661e0135**", "modifyMode": "Append"}`, where `dbInstanceId` and `modifyMode` are parameters defined in the OOS template. Some parameters of the OOS template have default values. NotificationMetadata must specify parameters that do not have default values. If you specify parameters that have default values, the specified values overwrite the original default values. However, keep the default values for the following parameters, which are used to retrieve relevant information during scaling activities: regionId: the region where the scaling activity is performed. Default value: ${regionId}. instanceIds: the list of instances associated with the scaling activity. Default value: ${instanceIds}. lifecycleHookId: the lifecycle hook ID. Default value: ${lifecycleHookId}. lifecycleActionToken: the identifier of the wait state for the scaling activity, which is used to end the current suspended activity early. Default value: ${lifecycleActionToken}. scalingGroupId: the ID of the scaling group to which the scaling activity belongs. Default value: ${scalingGroupId}. lifecycleActionResult: the action to take after the lifecycle hook wait state ends, which is used to end the current suspended activity early when the OOS template fails. When DefaultResult is set to ROLLBACK, the default value is ROLLBACK. In other cases, the default value is ABANDON. Note** You can set the value of lifecycleActionResult to overwrite the current default value. Valid values: ABANDON, CONTINUE, ROLLBACK, and ${lifecycleActionResult}. ${lifecycleActionResult} indicates that the value of lifecycleActionResult is consistent with the value of DefaultResult. You can obtain detailed information about the parameters of the corresponding template in the OOS console.	Test lifecycle hook.
NotificationArn	string	No	The Alibaba Cloud Resource Name (ARN) of the notification recipient of the lifecycle hook. If this parameter is not set, no notification is sent. The following notification methods are supported when you set this parameter: MNS queue. The value is in the format of `acs:mns:{region-id}:{account-id}:queue/{queuename}`. MNS topic. The value is in the format of `acs:mns:{region-id}:{account-id}:topic/{topicname}`. OOS template. The value is in the format of `acs:oos:{region-id}:{account-id}:template/{templatename}`. EventBridge. The value is in the format of `acs:eventbridge:{region-id}:{account-id}:eventbus/default`. The variables in the format have the following meanings: region-id: the region ID of the scaling group. account-id: the Alibaba Cloud account ID. The account ID of a Resource Access Management (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.	acs:mns:cn-beijing:161456884340**:queue/modifyLifecycleHo**

Response elements

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

Examples

Success response

JSON format

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

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.