All Products
Search
Document Center

Auto Scaling:CreateLifecycleHook

Last Updated:Nov 02, 2026

Creates one or more lifecycle hooks for a scaling group.

Operation description

Operation description

  • You can create up to six lifecycle hooks for a scaling group. When a scaling activity occurs in a scaling group that has lifecycle hooks, the lifecycle hooks pause the scaling activity for a period of time. You can specify the wait time by using the HeartbeatTimeout parameter. During the wait time, you can perform operations such as initializing ECS instance configurations and obtaining ECS instance data.

  • During a scale-out activity, ECS instances enter the wait state after they are added to the whitelist of an ApsaraDB RDS instance. After the wait state ends, the ECS instances are added to the backend server group of a Server Load Balancer (SLB) instance. During a scale-in activity, ECS instances enter the wait state after they are removed from the backend server group of an SLB instance. After the wait state ends, the ECS instances are removed from the whitelist of the ApsaraDB RDS instance.

  • You can configure a notification method for a lifecycle hook. Supported notification methods include Message Service (MNS) topics, MNS queues, and Operation Orchestration Service (OOS) templates. If you 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 the scaling group contains existing ECS instances and the configured OOS template is used to add the instances to or remove the instances from the whitelist of a cloud database other than ApsaraDB RDS, you must manually add the existing ECS instances to the whitelist of the cloud 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 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 among all lifecycle hooks in the current scaling group. It must be 2 to 64 characters in length, start with a digit, a letter, or a Chinese character, and can contain digits, underscores (_), hyphens (-), and periods (.).

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 activities of the scaling group.

  • SCALE_IN: scale-in activities of the scaling group.

SCALE_OUT

DefaultResult

string

No

The action to be performed after the wait state ends. Valid values:

  • CONTINUE: continues the response to the scale-out or scale-in activity.

  • ABANDON: releases the ECS instances created during the scale-out activity or removes the ECS instances from the scaling group during the scale-in activity.

  • ROLLBACK: rejects the release of ECS instances and rolls back the scale-in activity. For a scale-out activity, this value releases the created ECS instances, which has the same effect as ABANDON.

When a scale-in activity (SCALE_IN) occurs in the scaling group and multiple lifecycle hooks are triggered, if the DefaultResult of a lifecycle hook is set to ABANDON or ROLLBACK and the wait state of the hook ends, the wait states of other lifecycle hooks are ended in advance. In other cases, the next action is determined by the next action of the lifecycle hook whose wait state ends last.

Default value: CONTINUE.

CONTINUE

HeartbeatTimeout

integer

No

The wait time set by the lifecycle hook for the scaling activity. After the wait state times out, the next action is performed. Valid values: 30 to 21600. Unit: seconds.

After you create a lifecycle hook, you can call RecordLifecycleActionHeartbeat to extend the wait time of ECS instances, or call CompleteLifecycleAction to end the wait state of the scaling activity in advance.

Default value: 600.

600

NotificationMetadata

string

No

The notification message that is pushed to the NotificationArn (notification recipient) when the lifecycle hook pauses the scaling activity. This parameter is used to manage and mark different types of notification messages. You must specify NotificationArn together with this parameter. 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"}. dbInstanceId and modifyMode are parameters defined in the OOS template. Some parameters of the OOS template have default values. You must specify the parameters that do not have default values in NotificationMetadata. If you specify a parameter that has a default value, the original default value is overwritten. However, keep the default values for the following parameters to obtain relevant information when the scaling activity is running:

  • regionId: the region where the scaling activity is executed. Default value: ${regionId}.

  • instanceIds: the list of instances associated with the scaling activity. Default value: ${instanceIds}.

  • lifecycleHookId: the ID of the lifecycle hook. Default value: ${lifecycleHookId}.

  • lifecycleActionToken: the identifier of the wait state for the scaling activity, which is used to end the current pending activity in advance. Default value: ${lifecycleActionToken}.

  • scalingGroupId: the ID of the scaling group to which the scaling activity belongs. Default value: ${scalingGroupId}.

  • lifecycleActionResult: the next action after the wait state of the lifecycle hook ends. This parameter is used to end the current pending activity in advance when the OOS template fails to be executed. When DefaultResult is set to ROLLBACK, the default value of this parameter is ROLLBACK. In other cases, the default value is ABANDON.

Note
  • You can set the value of lifecycleActionResult to overwrite the current default value as needed. Valid values: ABANDON, CONTINUE, ROLLBACK, and ${lifecycleActionResult}. ${lifecycleActionResult} indicates that the value of lifecycleActionResult is the same as the value of DefaultResult.

  • You can obtain the detailed information about the parameters of the corresponding template in the OOS console.

Test lifecycle hook.

NotificationArn

string

No

The identifier of the notification recipient for the lifecycle hook. If you do not specify this parameter, no notifications are sent. If you specify this parameter, the following notification methods are supported:

  • MNS queue. Format: acs:mns:{region-id}:{account-id}:queue/{queuename}.

  • MNS topic. Format: acs:mns:{region-id}:{account-id}:topic/{topicname}.

  • OOS template. Format: acs:oos:{region-id}:{account-id}:template/{templatename}.

  • EventBridge. Format: acs:eventbridge:{region-id}:{account-id}:eventbus/default.

The variables in the formats have the following meanings:

  • region-id: the ID of the region where the scaling group resides.

  • account-id: the Alibaba Cloud account ID. The ID of a 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

LifecycleHookId

string

The ID of the lifecycle hook.

ash-bp1at9ufhmcf9cmy****

RequestId

string

The ID of the request.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3****

Examples

Success response

JSON format

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

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.