A whitelist template lets you define a set of IP addresses once and apply them to multiple ApsaraDB RDS for MySQL instances simultaneously. When you modify the template, the change propagates to all associated instances within about 1 minute — no per-instance updates required.
Limits
| Constraint | Value |
|---|---|
| Maximum IP addresses per RDS instance (directly added + from templates) | 1,000 |
| Maximum RDS instances a template can be associated with | 500 |
| Maximum instances associatable in a single Modify operation | 20 |
An IP address entry can be a single IP address or a CIDR block.
Behavior and risks
Propagation delay: Changes to a template take effect on associated instances within about 1 minute.
Blast radius: Modifying a template affects all associated instances. Review the associated instance list before making changes.
Deletion impact: Deleting a template removes its IP addresses from all associated instances and disconnects clients using those addresses. If the template is associated with only a few instances, disassociate it from each instance before deleting it.
Billing
This feature is free of charge.
Prerequisites
Before you begin, ensure that you have:
An ApsaraDB RDS for MySQL instance
Access to the ApsaraDB RDS console
Configure a whitelist template
Use this workflow when you need to create and centrally manage an IP whitelist — for example, to grant a set of application servers access to 10 or more RDS instances without configuring each instance individually.
Create a whitelist template
Log on to the ApsaraDB RDS console. In the left-side navigation pane, click Whitelist Template.
Click Create Whitelist Template.
In the panel that appears, enter a template name and the IP addresses to include. Click OK.
Template names must be unique within the same account. After a template is created, its name cannot be modified.
Special IP address behavior:
| Entry | Effect |
|---|---|
0.0.0.0/0 | Allows all IP addresses to access associated instances over the Internet. Use only for temporary testing, then restrict the entry immediately. |
127.0.0.1 (alone) | Blocks all IP addresses from accessing associated instances. |
127.0.0.1 combined with other addresses | The 127.0.0.1 entry is ignored; the other addresses apply. |
The IP addresses in the template take effect within 1 minute.
Modify a whitelist template
Modifying a template affects all instances associated with it. Review the list of associated instances before making changes.
Log on to the ApsaraDB RDS console. In the left-side navigation pane, click Whitelist Template.
Find the template and click Modify in the Actions column.
In the panel that appears, make the following changes as needed, then click OK: Associate or disassociate instances: In the left-side All Instances section, search for or select instances. Click
to move selected instances to Selected Instances, or click 
to remove instances you want to disassociate. Update IP addresses: Add or modify IP addresses based on your requirements. Changes apply to all associated instances.You can associate up to 20 instances at a time in this panel.
Delete a whitelist template
Deleting a template removes its IP addresses from all associated instances. Connections from those addresses are disconnected.
Log on to the ApsaraDB RDS console. In the left-side navigation pane, click Whitelist Template.
Find the template and click Delete in the Actions column.
In the dialog box that appears, click OK.
Associate a whitelist template with an instance
Use this workflow to link an existing whitelist template to a specific RDS instance, or to remove a template from an instance.
Associate a template
Log on to the ApsaraDB RDS console. In the left-side navigation pane, click Instances. In the upper part of the page, select a region.
Click the ID of the target instance. In the left-side navigation pane, click Whitelist and SecGroup.
Click the Whitelist Template tab, then click Associate Whitelist Template.
In the panel that appears, select the template and click OK.
After the association completes, the template's IP addresses appear on the Whitelist Settings tab.
Disassociate a template
On the Whitelist Template tab of the target instance, find the template.
Click Unassociate in the Actions column, then click OK in the confirmation message.
Troubleshooting
Changes are not reflected after modification
Template changes take up to 1 minute to propagate to associated instances. If the change has not taken effect after 1 minute, verify that the template is associated with the correct instances by checking the Whitelist Template tab on each instance.
IP address limit exceeded
The total number of IP addresses on an RDS instance — including those from all associated templates and directly added entries — cannot exceed 1,000. To stay within the limit, remove unused entries or consolidate overlapping CIDR blocks before adding new addresses.
What's next
Configure an IP address whitelist — manage IP addresses directly on a single instance without using a template.
Errors and FAQ about IP address whitelist settings in ApsaraDB RDS for MySQL — diagnose common whitelist configuration issues.
API reference
| Operation | Description | Key parameters |
|---|---|---|
| ModifyWhitelistTemplate | Creates, modifies, or deletes a whitelist template | Create: IpWhitelist, TemplateName; Modify: IpWhitelist, TemplateId; Delete: IpWhitelist (empty string), TemplateId |
| DescribeWhitelistTemplate | Queries a specific whitelist template | TemplateId |
| DescribeAllWhitelistTemplate | Lists or searches whitelist templates | TemplateName (set to the template ID or a keyword in the template name), FuzzySearch, MaxRecordsPerPage, PageNumbers |
| AttachWhitelistTemplateToInstance | Associates a template with an instance | TemplateId, InsName |
| DetachWhitelistTemplateToInstance | Disassociates a template from an instance | TemplateId, InsName |
| DescribeWhitelistTemplateLinkedInstance | Lists instances associated with a template | TemplateId |
| DescribeInstanceLinkedWhitelistTemplate | Lists templates associated with an instance | InsName |