All Products
Search
Document Center

Auto Scaling:Automatically add and remove ECS instances from a PolarDB cluster whitelist

Last Updated:Apr 16, 2026

Auto Scaling natively integrates with Server Load Balancer (SLB) and ApsaraDB RDS, but not with PolarDB. If your application data is stored in a PolarDB cluster, use lifecycle hooks together with a CloudOps Orchestration Service (OOS) public template to automatically add or remove Elastic Compute Service (ECS) instance private IP addresses from your PolarDB cluster's IP address whitelist whenever your scaling group scales out or in.

How it works

When Auto Scaling adds an ECS instance during a scale-out event, the lifecycle hook puts the instance into Pending Add state before it goes into service. During this window, Auto Scaling notifies OOS to run the ACS-ESS-LifeCycleModifyPolarDBIPWhitelist template, which adds the instance's private IP address to your PolarDB cluster's IP address whitelist. Once OOS completes the task, the instance transitions to InService.

The same mechanism works for scale-in: a lifecycle hook on a scale-in event puts the instance into a wait state, OOS removes the private IP address from the whitelist, and then the instance is released.

Prerequisites

Before you begin, make sure you have:

  • A scaling group in the Enabled state

  • A PolarDB cluster

  • A RAM role for OOS, with Alibaba Cloud Service as the trusted entity and CloudOps Orchestration Service as the trusted service

Note: This tutorial uses OOSServiceRole as the RAM role name. You can use any RAM role that meets the requirements.

Step 1: Grant the RAM role permissions

The ACS-ESS-LifeCycleModifyPolarDBIPWhitelist template needs permissions to query ECS instances, update the PolarDB cluster whitelist, and complete the lifecycle action. Create a policy with those permissions and attach it to the OOS RAM role.

Create a policy

  1. Log on to the RAM console.

  2. In the left-side navigation pane, choose Permissions > Policies.

  3. Click Create Policy.

  4. On the Create Policy page, click the JSON tab, enter the following policy document, and click OK. Set the policy name to ESSHookPolicyForPolarDBWhitelist.

    {
        "Version": "1",
        "Statement": [
            {
                "Action": [
                    "ecs:DescribeInstances"
                ],
                "Resource": "*",
                "Effect": "Allow"
            },
            {
                "Action": [
                    "polardb:DescribeDBClusterAccessWhitelist",
                    "polardb:ModifyDBClusterAccessWhitelist"
                ],
                "Resource": "*",
                "Effect": "Allow"
            },
            {
                "Action": [
                    "ess:CompleteLifecycleAction"
                ],
                "Resource": "*",
                "Effect": "Allow"
            }
        ]
    }

Attach the policy to the OOS RAM role

  1. In the left-side navigation pane, choose Identities > Roles.

  2. Find OOSServiceRole and click Grant Permission in the Actions column.

  3. In the Grant Permission panel, configure the following settings and click Grant permissions.

    Parameter Value
    Resource Scope Account
    Policies ESSHookPolicyForPolarDBWhitelist

Step 2: Create a lifecycle hook and trigger a scale-out event

This step creates a lifecycle hook that fires on scale-out events and invokes the OOS template to update the PolarDB whitelist.

Create the lifecycle hook

  1. Log on to the Auto Scaling console.

  2. In the left-side navigation pane, click Scaling Groups.

  3. In the top navigation bar, select the region where your scaling group is located.

  4. Click the ID of the scaling group, or click Details in the Actions column.

  5. On the scaling group details page, click the Lifecycle Hook tab.

  6. Click Create Lifecycle Hook.

  7. Configure the following settings and click OK.

    Parameter Value
    Name ESSHookForAddPolarDBWhitelist
    Scaling Activity Scale-out Event
    Timeout Period 300 (seconds). Set this to a value long enough for the OOS template to complete. If the OOS task does not finish before the timeout expires, the default execution policy takes effect.
    Default Execution Policy Select Continue.
    Send Notification When Lifecycle Hook Takes Effect Select OOS Template, then select Public Templates, and select ACS-ESS-LifeCycleModifyPolarDBIPWhitelist.
  8. In the ACS-ESS-LifeCycleModifyPolarDBIPWhitelist template parameters, configure the following:

    Parameter Value
    dbClusterId The ID of your PolarDB cluster
    modifyMode Append (adds private IP addresses to the whitelist during scale-out)
    OOSAssumeRole OOSServiceRole

Trigger a scale-out event

Trigger a scale-out event by executing a scaling rule. You can also use scheduled tasks or event-triggered tasks to trigger scale-out events.

Note: Lifecycle hooks take effect only when scaling events are triggered by scaling rules, scheduled tasks, or event-triggered tasks. They do not take effect when you manually add or remove ECS instances from a scaling group.
  1. On the scaling group details page, click the Scaling Rules and Event-triggered Tasks tab.

  2. On the Scaling Rules tab, click Create Scaling Rule.

  3. Configure the following settings and click OK.

    Parameter Value
    Rule Name Add1
    Rule Type Simple Scaling Rule
    Operation Add 1 Instances
  4. Find the Add1 scaling rule and click Execute in the Actions column.

  5. In the confirmation dialog, click OK.

After the scaling rule executes, Auto Scaling adds one ECS instance to the scaling group. The instance enters Pending Add state because the lifecycle hook is in effect. During the timeout period, OOS runs the ACS-ESS-LifeCycleModifyPolarDBIPWhitelist template to add the instance's private IP address to the PolarDB cluster's IP address whitelist.

Step 3: Verify the whitelist update

Check the PolarDB cluster whitelist to confirm the instance's private IP address was added.

  1. Log on to the PolarDB console.

  2. In the left-side navigation pane, click Clusters.

  3. Find your cluster and click its ID in the Cluster ID/Name column.

  4. In the left-side navigation pane, choose Settings and Management > Cluster Whitelists.

If the private IP address appears in the whitelist: The OOS template ran successfully. The setup is complete.

If the private IP address is missing: The OOS template may not have completed successfully. Go to Step 4 to investigate.

Step 4: (Optional) View the OOS execution details

If the whitelist was not updated, check the OOS execution details to identify the cause.

  1. Log on to the OOS console.

  2. In the left-side navigation pane, choose Automated Tasks > Task Execution Management.

  3. Find the execution entry by time and click Details in the Actions column.

  4. On the execution details page:

    • In the Basic Information section, check the execution ID and status.

    • In the Execution Steps and Results section, click a task node to view step-level details.

    For more information, see View the details of an execution.

Note: If the execution failed, an error message is displayed on the execution details page. See the troubleshooting section below.

FAQ

If an Operation and Maintenance (O&M) task fails, find the cause based on the error message in the execution result. For more information, see FAQ.

Common error messages are as follows:

Error message

Cause

Solution

Forbidden.Unauthorized message: A required authorization for the specified action is not supplied.

Auto Scaling is not authorized to perform the specified action.

Verify that the required permissions are granted to the OOSServiceRole RAM role.

Forbidden.RAM message: User not authorized to operate on the specified resource, or this API doesn't support RAM.

The RAM user or RAM role does not have the permissions to operate on the corresponding resource.

Verify that the OOSServiceRole RAM role has the required permissions. For example, you can grant the sample permissions for the OOS service to the RAM role. You must add operation permissions to the RAM role to ensure that the OOS service can manage the resources specified in the OOS template.

LifecycleHookIdAndLifecycleActionToken.Invalid message: The specified lifecycleActionToken and lifecycleActionId you provided does not match any in process lifecycle action.

The ongoing lifecycle action has expired or has been aborted.

Evaluate the timeout period of the lifecycle hook to ensure that the O&M tasks defined in the OOS template can be completed within the timeout period.

Troubleshooting

Error Cause Solution
Forbidden.Unauthorized: A required authorization for the specified action is not supplied The OOS RAM role is missing required permissions. Verify that OOSServiceRole has the ESSHookPolicyForPolarDBWhitelist policy attached, as described in Step 1.
Forbidden.RAM: User not authorized to operate on the specified resource, or this API doesn't support RAM The OOS RAM role is missing required permissions. Verify that OOSServiceRole has the ESSHookPolicyForPolarDBWhitelist policy attached, as described in Step 1.
LifecycleHookIdAndLifecycleActionToken.Invalid: The specified lifecycleActionToken and lifecycleActionId you provided does not match any in process lifecycle action The lifecycle hook timed out before the OOS template completed. Increase the Timeout Period of the lifecycle hook to give the OOS template enough time to complete.

What's next

  • To automate IP address removal during scale-in, create a separate lifecycle hook for Scale-in Event and configure the OOS template parameters accordingly.

  • To use a custom RAM role instead of OOSServiceRole, create a RAM role with Alibaba Cloud Service as the trusted entity and CloudOps Orchestration Service as the trusted service, attach the same policy, and specify the role name in the OOSAssumeRole parameter.