When you manage multiple PolarDB for PostgreSQL clusters, maintaining separate IP whitelists for each cluster is repetitive and error-prone. Global IP whitelist templates let you define a reusable set of allowed IP addresses once and apply it to multiple clusters simultaneously. When you update a template, the change propagates automatically to every associated cluster.
Prerequisites
Before you begin, make sure you have:
A PolarDB for PostgreSQL cluster
Access to the PolarDB console
Limits
| Limit | Value |
|---|---|
| IP addresses per template | 1,000 |
| Templates per cluster | Multiple |
| Clusters per template | Multiple |
| Cross-region association | Not supported — a cluster can only be associated with templates in the same region |
Workflow overview
A typical workflow follows this sequence:
Create an IP whitelist template with the IP addresses you want to allow.
Associate the template with one or more clusters.
To change allowed IPs, modify the template — changes take effect on all associated clusters.
Before deleting a template, disassociate it from all clusters to avoid breaking database connections.
Create an IP whitelist template
Log on to the PolarDB console.
In the upper-left corner, select the region where the cluster is deployed.
In the left-side navigation pane, click IP Whitelist Templates.
In the upper-left corner of the page, click Create IP Whitelist Template.
In the Create IP Whitelist Template dialog box, configure the following:
IP Whitelist Template Name: The name must meet these requirements:
Contains only lowercase letters, digits, and underscores (
_)Starts with a letter; ends with a letter or digit
Is 2–120 characters long
IP Addresses in Whitelist: Enter the IP addresses to allow.
Click OK.
Modify an IP whitelist template
Changes apply to all clusters associated with this template. Review the impact before proceeding.
Log on to the PolarDB console.
In the upper-left corner, select the region where the cluster is deployed.
In the left-side navigation pane, click IP Whitelist Templates.
Find the template to modify and click Modify in the Actions column.
In the Modify IP Whitelist Template panel, add or remove IP addresses, then click OK.
In the confirmation dialog box, click OK.
Delete an IP whitelist template
Deleting a template removes the whitelist configurations from all associated clusters, which causes database connection errors. Disassociate the template from all clusters before deleting it.
Log on to the PolarDB console.
In the upper-left corner, select the region where the cluster is deployed.
In the left-side navigation pane, click IP Whitelist Templates.
Find the template to delete and click Delete in the Actions column.
In the confirmation dialog box, click Delete.
Associate an IP whitelist template with a cluster
Log on to the PolarDB console.
In the upper-left corner, select the region where the cluster is deployed.
Find the cluster and click its ID.
In the left-side navigation pane, choose Settings and Management > Whitelists.
On the Whitelists page, click Associate IP Whitelist Template.
In the Associate IP Whitelist Template panel, select a template from the drop-down list and click OK.
To verify the association, return to the Whitelists page and confirm the template appears in the list.
Disassociate an IP whitelist template from a cluster
Log on to the PolarDB console.
In the upper-left corner, select the region where the cluster is deployed.
Find the cluster and click its ID.
In the left-side navigation pane, choose Settings and Management > Whitelists.
On the Whitelists page, find the template to disassociate and click Disassociate.
In the confirmation dialog box, click OK.
Common issues
The cluster cannot connect after I modified a template.
Modifying a template takes effect on all associated clusters. If a connection fails after modification, check whether the client IP address is still included in the updated whitelist.
I deleted a template and now the cluster has connection errors.
Deleting a template removes its whitelist entries from all associated clusters. To restore access, create a new template with the required IP addresses and associate it with the affected cluster.
I cannot associate a template with a cluster in another region.
Templates can only be associated with clusters in the same region. Create a separate template in the target region.