All Products
Search
Document Center

Auto Scaling:CreateLifecycleHook

Last Updated:Jun 18, 2024

Creates one or more lifecycle hooks in a scaling group. A lifecycle hook allows you to execute custom actions like sending notifications or automating script execution at critical stages (such as instance 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.

Operation description

You can create up to 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 waits to be added to or removed from the scaling group during scaling activities. You can use the HeartbeatTimeout parameter to specify the timeout period of the lifecycle hook. During the timeout period of a lifecycle hook, you can perform custom operations such as initialize ECS instance configurations and download ECS instance data on the ECS instances for which the lifecycle hook is applied.

During a scale-out activity and the timeout period of a lifecycle hook, the private IP addresses of ECS instances wait to be added to the associated whitelist that manages access to the ApsaraDB RDS instance. The ECS instances also wait to be added to the backend server group of the associated Classic Load Balancer (CLB) instance. After the lifecycle hook times out, the private IP addresses of the ECS instances are added to the whitelist that manages access to the associated ApsaraDB RDS instance. The ECS instances are also added to the backend server group of the associated CLB instance. During a scale-in activity and the timeout period of a lifecycle hook, the private IP addresses of ECS instances wait to be removed from the whitelist that manages access to the associated ApsaraDB RDS instance. The ECS instances also wait to be removed from the backend server group of the associated CLB instance. After the lifecycle hook times out, the private IP addresses of the ECS instances are removed from the whitelist that manages access to the associated ApsaraDB RDS instance. The ECS instances are also removed from the backend server group of the associated CLB 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 your scaling group has existing ECS instances and you configured an OOS template that is used to add the private IP addresses of ECS instances to or remove the private IP addresses of ECS instances from the whitelists that manage access to cloud databases that are not ApsaraDB RDS databases, you must manually add the private IP addresses of the ECS instances to or remove the private IP addresses of the ECS instances from the whitelists that manage access to the cloud databases.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
ess:CreateLifecycleHookWrite
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
ScalingGroupIdstringYes

The ID of the scaling group.

asg-bp1eyv4qn8ssgv43****
LifecycleHookNamestringNo

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.

If you do not specify this parameter, the value of the LifecycleHookId parameter is used.

lifecyclehook****
LifecycleTransitionstringYes

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

  • SCALE_OUT
  • SCALE_IN
SCALE_OUT
DefaultResultstringNo

The action that you want Auto Scaling to perform after the lifecycle hook times out. Valid values:

  • CONTINUE: Auto Scaling continues to respond to scale-in or scale-out requests.
  • ABANDON: Auto Scaling releases Elastic Compute Service (ECS) instances that are created during scale-out activities, or removes ECS instances from the scaling group during scale-in activities.

If multiple lifecycle hooks in a scaling group are triggered during scale-in activities and you set the DefaultResult parameter to ABANDON for one of the lifecycle hooks, Auto Scaling immediately performs the action after the lifecycle hook whose DefaultResult is set to ABANDON times out. As a result, other lifecycle hooks time out ahead of schedule. In other cases, Auto Scaling performs the action only after all lifecycle hooks time out.

Default value: CONTINUE.

CONTINUE
HeartbeatTimeoutintegerNo

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 prolong the timeout period of the lifecycle hook. You can also call the CompleteLifecycleAction operation to end the timeout period of the lifecycle hook ahead of schedule.

Default value: 600.

600
NotificationMetadatastringNo

The notification metadata that is sent when the lifecycle hook takes effect. This helps you manage and categorize notifications in an efficient manner. If you specify this parameter, you must specify the NotificationArn parameter. The parameter value cannot exceed 4,096 characters in length.

If you use the NotificationArn parameter to specify a public or customOOS template, the value of the NotificationMetadata parameter must be a JSON string that contains the OOS template parameters. For example, your OOS template includes the following parameters: {"dbInstanceId": "dds-bp17661e0135****", "modifyMode": "Append"}, dbInstanceId, and modifyMode. Some parameters defined in your OOS template have default values. When you specify the NotificationMetadata parameter, specify parameters that do not have default values. If you specify parameters that have default values, the default values are overwritten. However, the default values of the following parameters must be retained to obtain information about scaling activities that are in progress:

  • regionId: the region ID of the scaling activity that is in progress. Default value: ${regionId}.
  • instanceIds: the IDs of ECS instances that are scaled in in the scaling activity. Default value: ${instanceIds}.
  • lifecycleHookId: the ID of the lifecycle hook. Default value: ${lifecycleHookId}.
  • lifecycleActionToken: the token of the lifecycle action. 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 activity is executed. Default value: ${scalingGroupId}.
Note You can obtain template parameter information in the OOS console.
Test lifecycle hook.
NotificationArnstringNo

The Alibaba Cloud Resource Name (ARN) of the notification method that is used by Auto Scaling to send notifications when the lifecycle hook takes effect. 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 a Message Service (MNS) queue as the notification method, specify the value in the acs:mns:{region-id}:{account-id}:queue/{queuename} format.
  • If you use an MNS topic as the notification method, specify the value in the acs:mns:{region-id}:{account-id}:topic/{topicname} format.
  • If you use an OOS template as the notification method, specify the value in the acs:oos:{region-id}:{account-id}:template/{templatename} format.

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.
acs:mns:cn-beijing:161456884340****:queue/modifyLifecycleHo****

Response parameters

ParameterTypeDescriptionExample
object
RequestIdstring

The ID of the request.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
LifecycleHookIdstring

The ID of the lifecycle hook.

ash-bp1at9ufhmcf9cmy****

Examples

Sample success responses

JSONformat

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

Error codes

For a list of error codes, visit the Service error codes.