All Products
Search

This Product

    PolarDB:Create a global domain name

    Document Center

    PolarDB:Create a global domain name

    Last Updated:Apr 17, 2026

    When your business applications are distributed across multiple regions and need to connect to PolarDB clusters in different regions, managing multiple cluster endpoints is complex and error-prone. The global domain name feature of a Global Database Network (GDN) provides a single endpoint that spans multiple regions. Your applications, regardless of where they are deployed, can use this domain name to access the nearest local cluster. After a primary/secondary switchover, applications automatically connect to the new primary cluster, enabling application-transparent disaster recovery and simplifying multi-region deployment architectures.

    How it works

    The global domain name feature is built on the Private Hosted Zone service to provide intelligent DNS resolution within a Virtual Private Cloud (VPC).

    • Mechanism: When you enable the global domain name, the system automatically creates a domain name in the format [gdnid].gdn.rds.aliyuncs.com and associates it with the VPCs of all clusters in the GDN.

    • Primary/secondary switchover:

      • Normal primary/secondary switchover: The primary cluster in the China (Beijing) region becomes a secondary cluster, and the secondary cluster in the China (Shanghai) region is promoted to the primary cluster. Applications in the China (Beijing) region that connect through the global domain name are still routed to the local cluster endpoint for nearest access. Because the Beijing cluster is now a secondary cluster, read requests are served locally, while write requests are automatically forwarded to the new primary cluster in Shanghai.

      • Forced primary/secondary switchover: The global domain name configuration is updated synchronously to ensure that you can still access the new primary cluster. For example, if the original primary cluster is removed from the GDN and the new primary cluster is in the China (Shanghai) region, applications in the China (Beijing) region that connect through the global domain name are automatically routed to the Shanghai cluster's endpoint through cross-VPC access. In this case, all read and write requests are sent to the new primary cluster in Shanghai.

    Considerations

    • If you change the Virtual Private Cloud (VPC) and vSwitch of a cluster after you enable the global domain name, you must re-establish network connectivity between the new VPC and the VPCs of the other clusters in the GDN.

    • The global domain name provides traffic distribution only at the region level. If multiple clusters exist in the same region, requests are randomly routed to one of the clusters.

    Billing

    Enabling and using the global domain name feature incurs the following fees:

    • Private DNS resolution fees: The global domain name uses Private Hosted Zone. For detailed billing rules, see Private Hosted Zone pricing.

    • Cross-region traffic fees: After a forced primary/secondary switchover, if the original primary cluster and the new primary cluster are in different regions, cross-region data transfer fees apply. These fees are charged by VPC Peering Connection. For detailed billing rules, see VPC Peering Connection billing.

    Prerequisites

    Before you create a global domain name, ensure that network connectivity and access permissions are correctly configured across all clusters in the GDN.

    Important

    We recommend that the CIDR blocks of the VPCs that host clusters in the GDN do not overlap. If they overlap, ensure that the vSwitch CIDR blocks do not overlap.

    1. Enable the Private DNS service: Log on to the Alibaba Cloud DNS PrivateZone console, and click Enable Now.

    2. Establish network connectivity between VPCs: Create a VPC Peering Connection between each pair of VPCs hosting clusters in your GDN. For example, if you have clusters in the China (Beijing), China (Shanghai), and China (Shenzhen) regions, you must create three peering connections: China (Beijing)–China (Shanghai), China (Beijing)–China (Shenzhen), and China (Shanghai)–China (Shenzhen).

    3. Configure the cluster whitelist: For each cluster in the GDN, add the CIDR blocks of the VPCs hosting all other clusters to its cluster whitelist.

    Enable the global domain name

    You can enable the global domain name when you create a GDN or for an existing GDN.

    • When you create a GDN:

      1. Log on to the PolarDB console. In the left-side navigation pane, click Global Database Network.

      2. On the Global Database Network page, click Create GDN.

      3. In the Create GDN dialog box, turn on the Global Domain Name switch.

    • For an existing GDN:

      1. Log on to the PolarDB console. In the left-side navigation pane, click Global Database Network (GDN).

      2. On the Global Database Network (GDN) page, find the target GDN and click its GDN ID to go to the details page.

      3. Find Global Domain Name and click Enable on the right.

    Note

    When you enable the global domain name, the system automatically creates a Service-Linked Role named AliyunServiceRoleForPolarDB to grant PolarDB permission to access cloud resources like Private Hosted Zone.

    Verify the global domain name

    After the configuration is complete, you must verify the domain name resolution and connectivity within the VPCs in different regions.

    1. (Optional) Verify the VPC Peering Connection:

      Assume that the primary cluster is in the China (Beijing) region and the secondary cluster is in the China (Shanghai) region. On an ECS instance in the China (Beijing) region, use a MySQL client to connect to the internal endpoint of the China (Shanghai) cluster. If the connection succeeds, connectivity between the China (Beijing) VPC and the China (Shanghai) VPC works as expected. Similarly, verify connectivity from China (Shanghai) to China (Beijing).

      mysql -hpc-xxxxxxxx.rwlb.rds.aliyuncs.com  -P3306 -uxxxx -pxxxx

    2. Verify nearest access: Confirm that within the VPC in each region, the global domain name resolves to the local cluster endpoint.

      1. Log on to an ECS instance in the VPC where the primary cluster is deployed (for example, China (Beijing)).

      2. Run ping <global_domain_name> and ping <primary_cluster_internal_endpoint>.

      3. Expected result: The IP addresses returned by both commands are identical. This confirms that the global domain name resolves to the local cluster.

      4. Repeat the same verification for the secondary cluster.

    3. Verify failover (run a drill): Test whether your application can automatically connect to the new primary cluster through the global domain name after a primary/secondary switchover.

      1. Go to the details page of the target GDN. In the Clusters section, find the target secondary cluster and click Switch to Primary Cluster in the Operation column. For more information, see Switch the primary cluster.

      2. After the switchover, try reconnecting through the global domain name and observe the recovery time.

    Manage the global domain name

    You can enable or disable the global domain name at any time as needed.

    1. Log on to the PolarDB console. In the left-side navigation pane, click Global Database Network (GDN).

    2. On the Global Database Network (GDN) page, find the target GDN and click its GDN ID to go to the details page.

    3. Find Global Domain Name and click Close on the right.

    4. Carefully read the notes in the dialog box, then click OK to confirm.

    Note

    After you disable the GDN global domain name, you can re-enable it at any time as needed.