All Products
Search
Document Center

Auto Scaling:CreateLifecycleHook

更新時間:Jul 09, 2024

Creates lifecycle hooks. A lifecycle hook allows you to execute custom actions like 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 HeartbeatTimeout setting. 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, the private IP addresses of ECS instances are removed from the IP address whitelists of the associated ApsaraDB RDS instances. However, the ECS instances are only removed from the backend server groups of the associated SLB instances after lifecycle hooks time out.

  • You must specify a notification receiver for each lifecycle hook. When lifecycle hooks are triggered, notifications can be sent by using Message Service (MNS) topics, MNS 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 Use RAM to grant 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 non-ApsaraDB RDS cloud databases, 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. 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 scaling events to which you want to apply the lifecycle hook. Valid values:

  • SCALE_OUT: scale-out events

  • SCALE_IN: scale-in events

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 a scale-in or scale-out request.

  • 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.

When 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: If the lifecycle hook with DefaultResult 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 recently times out.

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 action that is specified by DefaultResult. 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 receiver 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 also 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 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 activities.

  • regionId: the region ID of the scaling activity that is in progress. Default value: ${regionId}.

  • instanceIds: the IDs of the ECS instances that are scaled in the scaling activity. 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 to which the scaling activity belongs. 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 receiver. 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 use an MNS queue as the notification receiver, specify the value in the acs:mns:{region-id}:{account-id}:queue/{queuename} format.

  • If you use an MNS topic as the notification receiver, specify the value in the acs:mns:{region-id}:{account-id}:topic/{topicname} format.

  • If you use an OOS template as the notification receiver, specify the value in the acs:oos:{region-id}:{account-id}:template/{templatename} format.

  • If you use an event bus provided by EventBridge as the notification receiver, 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 MNS queue.

  • topicname: the name of the MNS topic.

  • templatename: the name of the OOS template.

Response parameters

Parameter

Type

Example

Description

RequestId

String

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

The request ID.

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

Error message

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 type is not supported in the region where the scaling group resides.

400

QueueNotExist

The specified queue does not exist.

The specified MNS 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.