All Products
Search

This Product

    VPN Gateway:Configure destination-based routes

    Document Center

    VPN Gateway:Configure destination-based routes

    Last Updated:Mar 01, 2026

    After you create a destination-based route, the VPN gateway forwards traffic by matching the traffic's destination IP address against configured routes.

    Prerequisites

    Create an IPsec-VPN connection for the VPN gateway before you configure a destination-based route. For more information, see Create and manage an IPsec-VPN connection in single-tunnel mode or Create and manage an IPsec-VPN connection in dual-tunnel mode.

    Limitations

    • You cannot add a destination-based routewith the destination CIDR block set to 0.0.0.0/0.

    • Do not add a destination-based route whose destination CIDR block is 100.64.0.0/10, a subnet of 100.64.0.0/10, or a CIDR block that contains 100.64.0.0/10. Such a route entry can prevent the console from displaying the status of the IPsec-VPN connection or cause IPsec negotiation failures.

    Route matching principles

    By default, a VPN gateway uses the longest prefix match principle to forward traffic.

    If you configure a VPN Gateway with both active and standby destination-based routes, only the effective route is used in the matching process. The effective route is determined as follows:

    • If the system detects that the IPsec-VPN connection associated with the active destination-based route is up (IPsec negotiation is successful and the health check is normal), the active destination-based route is effective.

    • If the system detects that the IPsec-VPN connection for the active destination-based route is down (either IPsec negotiation failed, or the negotiation succeeded but the health check is abnormal), but the IPsec-VPN connection for the standby route is up, the standby destination-based route becomes effective.

    • If the system detects that the IPsec-VPN connections for both the active and standby destination-based routes are down, the active destination-based route is effective by default.

    For example, a VPN gateway has the following two destination-based routes. When the VPN gateway receives a packet destined for an IP address within the 10.10.10.0/24 range, the packet matches both routes. However, Route 2 has a prefix length of /16, which is longer than the /8 prefix of Route 1. According to the longest prefix match principle, the VPN gateway forwards the packet based on Route 2.

    Route name

    Destination CIDR block

    Next hop

    Weight

    Route 1

    10.0.0.0/8

    IPsec-VPN Connection 1

    100

    Route 2

    10.10.0.0/16

    IPsec-VPN Connection 2

    100

    Add a destination-based route

    1. Log on to the VPN Gateway console.

    2. In the top navigation bar, select the region where the VPN gateway is deployed.

    3. On the VPN Gateways page, click the ID of the target VPN gateway.

    4. On the Destination-based Route Table tab, click Add Route Entry.

    5. In the Add Route Entry panel, configure the destination-based route and click OK.

      Configuration

      Description

      Destination CIDR Block

      Enter the CIDR block of the data center that you want to access.

      Next Hop Type

      Select IPsec-VPN Connection.

      Next Hop

      Select the IPsec-VPN connection to use.

      Advertise to VPC

      Select whether to propogate the new route to the VPC.

      • Yes (Recommended): The system automatically propogates the new route to the VPC. The route is propogated only to the system route table of the VPC, not to any custom route tables.

        If you need to include this route in a custom route table, you must add it manually. For more information, see Add a custom route entry to a custom route table.

      • No: The system does not propogate the new route to the VPC.

        If you select No, you must manually add a route entry for the data center's CIDR block to both the system route table and any custom route tables in the VPC. The next hop for this route entry must point to the VPN gateway. Otherwise, the VPC cannot access resources in that CIDR block through the IPsec-VPN connection.

      Important

      If you create routes with the same destination CIDR block in both a policy-based route table and a destination-based route table, and both routes are propogated to the same VPC, withdrawing the route from the destination-based route table also withdraws the corresponding route in the policy-based route table.

      Weight

      Select a weight for the destination-based route.

      In a scenario where you use the same VPN gateway to build active/standby IPsec-VPN connections, you can configure route weights to specify the active and standby links. A route with a weight of 100 is the active link by default. A route with a weight of 0 is the standby link by default.

      You can configure health checks for the IPsec-VPN connection to automatically detect link connectivity. If the active link fails, the system automatically switches traffic to the standby link to ensure high availability. For more information about health checks for IPsec-VPN connections, see Health check.

      • 100 (Active) (Default): The IPsec-VPN connection associated with this route is the active link.

      • 0 (Standby): The IPsec-VPN connection associated with this route is the standby link.

      Note

      • When you specify active and standby links, the active and standby routes must have the same destination CIDR block but different next hops and weights.

      • To modify an active link's weight, you must first delete the standby link. After modifying the weight, re-create the standby link. To modify a standby link's weight, you must first delete the active link. After modifying the weight, re-create the active link.

      If you encounter a route conflict error when adding a destination-based route, see What do I do if I receive an error message, such as a duplicate route, when adding a route to a VPN Gateway instance?.

    Propogate a destination-based route

    If you did not propogate the route to the VPC during creation, you can do so later using this procedure. The route is propogated only to the VPC system route table, not to any custom route tables.

    If you need to include this route in a custom route table, you must add it manually. For more information, see Add a custom route entry to a custom route table.

    1. Log on to the VPN Gateway console.

    2. In the top navigation bar, select the region where the VPN gateway is deployed.

    3. On the VPN Gateways page, click the ID of the target VPN gateway.

    4. On the Destination-based Route Table tab, find the target route entry and click Advertise in the Actions column.

    5. In the Advertise Route dialog box, click OK.

      After the route is published, you can click Withdraw to withdraw it.

      Important

      If you create routes with the same destination CIDR block in both a policy-based route table and a destination-based route table, and both routes are propogated to the same VPC, withdrawing the route from the destination-based route table also withdraws the corresponding route in the policy-based route table.

    Delete a destination-based route

    1. Log on to the VPN Gateway console.

    2. In the top navigation bar, select the region where the VPN gateway is deployed.

    3. On the VPN Gateways page, click the ID of the VPN gateway that you want to manage.

    4. On the Destination-based Route Table tab, find the target route entry and click Delete in the Actions column.

    5. In the Delete Route Entry dialog box, click OK.

    Configure destination-based routes by calling API operations

    You can call API operations using tools such as Alibaba Cloud SDK (recommended), Alibaba Cloud CLI, Terraform, and Resource Orchestration Service to configure and manage destination-based routes. For more information about the API operations, see the following topics: