All Products
Search

This Product

    API Gateway:VPC integration instances

    Document Center

    API Gateway:VPC integration instances

    Last Updated:Jan 09, 2026

    This topic describes the new VPC integration instance for API Gateway, its use cases, and key purchasing considerations.

    Use cases

    The VPC integration instance is a new dedicated instance for API Gateway that optimizes the network architecture between API Gateway and your virtual private clouds (VPCs). It is suitable for the following scenarios:

    • Accessing multiple backend resources within a single VPC. This is a common requirement for microservices or service discovery architectures (for example, using Nacos), where APIs hosted on the gateway need to connect to various services, such as Elastic Compute Serive (ECS) and Server Load Balancer (SLB), within the same VPC.

    • Hybrid cloud connectivity. When API Gateway forwards requests to backend services in a hybrid cloud setup, those services often expect the request to originate from a private IP address within their VPC. For more information, see Scenario 3: API Gateway accesses a backend service in an on-premises data center over an internal network.

      image.png

    Differences from conventional dedicated instances

    The following table summarizes their advantages and limitations.

    Type

    VPC integration instance

    Conventional dedicated instance

    Egress IP address* of the gateway instance

    A private IP address from the VPC to which the instance is connected.

    An IP address in the 100.*.*.* range.

    An instance forwarding API requests to multiple resources within the same VPC

    Recommended.

    Example: service registration and discovery.

    Supported, but requires configuring a VPC access authorization for each backend resource. Dynamic configuration is not supported.

    An instance forwarding API requests to resources in multiple VPCs

    Not supported. You must manually establish network connectivity between the VPCs.

    Recommended. You can configure multiple VPC access authorizations.

    Configuration process

    Specify the target VPC during instance creation. No additional API configuration is required.

    Requires configuring a VPC access authorization.

    Important

    • The Egress IP address of the gateway instance is the source TCP IP address that a backend service sees when receiving a request from API Gateway.

    • VPC access authorization: In the conventional approach, you must first create a VPC access authorization to access resources in a VPC. For more information, see Use a resource in a VPC as the backend service of an API.

    • Due to network architecture limitations, only conventional dedicated instances support DataWorks integration. DataWorks does not currently support VPC integration instances.

    Purchase a VPC integration instance

    The following image shows the purchase page for an API Gateway dedicated instance. After you set Type to VPC integration instance, you can configure the instance.

    image..png

    To create a VPC integration instance, specify the following settings:

    • VPC ID: Specify the VPC to which the instance will connect. You cannot change this setting after the instance is created.

    • CIDR Block: Specify a CIDR block for the API Gateway instance. The system validates that this CIDR block does not conflict with the one used by your selected vSwitch. If a conflict is found, instance creation fails.

    • Zone and security group: API Gateway creates an Elastic Network Interface (ENI) in the vSwitch and Security Group of the specified zone and binds it to the new API Gateway instance. Ensure that your VPC resources are within the CIDR block of the specified vSwitch and in the same security group. To prevent request failures, the outbound rules of the security group must allow traffic to the destination IP range.

      Important

      API Gateway uses an internal resource CIDR block. The vSwitch you specify must not overlap with this internal CIDR block. For a list of CIDR blocks reserved by VPC integration instances in each region, see CIDR blocks reserved by VPC integration instances in each region.

    • Service-linked role: API Gateway requires a service-linked role to manage ENI resources in your VPC. For more details about this role, see AliyunServiceRoleForApiGatewayConnectUserVpc.

    Note

    Notes on the Elastic Network Interface (ENI) created by API Gateway in your VPC:

    1. The ENI instance resides in your VPC and is subject to your VPC's network configurations and security rules, such as security groups.

      1. If the backend service is an ECS instance in the same security group as the ENI, and intra-group communication is enabled for that security group, you do not need to configure specific outbound rules.

      2. If the backend service is a CLB instance, you must ensure that the outbound rules of the security group allow traffic to the destination IP range, regardless of whether the CLB instance is in the same vSwitch.

    2. The ENI created by API Gateway in your VPC does not incur additional charges.

    How to use

    Add accessible CIDR blocks

    By default, a new VPC integration instance can only access services within the CIDR block of the vSwitch specified at creation. You can view the default accessible CIDR block in the VPC network access section of the instance details page in the API Gateway console. To allow the instance to access services in other CIDR blocks, you must add those blocks manually. Follow these steps:

    1. Log on to the API Gateway console. In the left-side navigation pane, click Instances.

    2. Find the target VPC integration instance and click Add in the Access Allowed From column.

    3. Add a CIDR block in two ways: Select a CIDR block from the drop-down list or manually specify a CIDR block.

      Note

      If you enter a CIDR block manually, ensure that it is within the VPC you specified when creating the instance or is connected to that VPC.

    Compatibility with VPC access authorization

    Use VPC access authorization as a backend service

    VPC integration instances can use existing VPC access authorizations as backend services. The instance uses the ENI in your VPC to directly connect to the service defined in the VPC access authorization.

    Ensure the following conditions are met before you configure a VPC access authorization for an API or a plug-in on a VPC integration instance:

    • The VPC ID in the VPC access authorization definition is the same as the ID of the VPC connected to the instance.

    • The private IP address of the service in the VPC access authorization falls within the accessible CIDR block of the VPC integration instance.

      Note

      When you publish an API or modify a plug-in, if you receive an error message such as instance cannot connect to the backend xxx.xxx.xxx.xxx., check whether the instance's accessible CIDR block includes the private IP address mentioned in the error.

    Change the instance for an API group

    To help you migrate your services to a VPC integration instance, you can directly change the instance for an API Group from a Serverless or conventional dedicated instance to a VPC integration instance.

    1. Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups.

    2. Find the group that you want to migrate and click its name to go to the group details page.

    3. Click Modify Instance for API Group Deployment and select the VPC integration instance that you created.

    4. API Gateway validates the VPC access authorizations used by the APIs and their associated plug-ins in the original API Group. If the validation succeeds, the change is successful. If it fails, the system rolls back the change and displays the reason for the failure.

      Important

      • Before migration, the system validates the following for VPC-based services (APIs and plug-ins):

        • The VPC ID in the VPC access authorization definition is the same as the ID of the VPC connected to the instance.

        • The private IP address of the service in the VPC access authorization falls within the accessible CIDR block of the VPC integration instance.

      • If your API Group uses a VPC access authorization, ensure that the security group of the corresponding ECS/SLB service is the same as the security group specified when you created the VPC integration instance.

      • After migration, the egress IP address changes to that of the target instance. If your backend service uses an allowlist, add the new egress IP address to the allowlist before migrating to prevent connectivity failures.

    CIDR blocks reserved by VPC integration instances in each region

    China (Hangzhou)

    Zone

    Reserved CIDR block

    cn-hangzhou-b

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    cn-hangzhou-d

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    cn-hangzhou-e

    192.168.32.0/20, 172.19.32.0/20, and 172.20.0.0/16

    cn-hangzhou-f

    192.168.48.0/20, 172.19.48.0/20, and 172.20.0.0/16

    cn-hangzhou-g

    192.168.64.0/20, 172.19.64.0/20, and 172.20.0.0/16

    cn-hangzhou-h

    192.168.80.0/20, 172.19.80.0/20, and 172.20.0.0/16

    cn-hangzhou-i

    192.168.96.0/20, 172.19.96.0/20, and 172.20.0.0/16

    cn-hangzhou-j

    192.168.112.0/20, 172.19.112.0/20, and 172.20.0.0/16

    cn-hangzhou-k

    192.168.128.0/20, 172.19.128.0/20, and 172.20.0.0/16

    China (Shanghai)

    Zone

    Reserved CIDR block

    cn-shanghai-a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    cn-shanghai-b

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    cn-shanghai-c

    192.168.32.0/20, 172.19.32.0/20, and 172.20.0.0/16

    cn-shanghai-d

    192.168.48.0/20, 172.19.48.0/20, and 172.20.0.0/16

    cn-shanghai-e

    192.168.64.0/20, 172.19.64.0/20, and 172.20.0.0/16

    cn-shanghai-f

    192.168.80.0/20, 172.19.80.0/20, and 172.20.0.0/16

    cn-shanghai-g

    192.168.96.0/20, 172.19.96.0/20, and 172.20.0.0/16

    cn-shanghai-k

    192.168.112.0/20, 172.19.112.0/20, and 172.20.0.0/16

    cn-shanghai-l

    192.168.128.0/20, 172.19.128.0/20, and 172.20.0.0/16

    cn-shanghai-m

    192.168.144.0/20, 172.19.144.0/20, and 172.20.0.0/16

    cn-shanghai-n

    192.168.160.0/20, 172.19.160.0/20, and 172.20.0.0/16

    China East 2 Finance

    Zone

    Reserved CIDR block

    cn-shanghai-finance-1a

    192.168.0.0/20, 172.19.0.0/20, and 172.21.0.0/16

    cn-shanghai-finance-1b

    192.168.16.0/20, 172.19.16.0/20, and 172.21.0.0/16

    cn-shanghai-finance-1f

    192.168.32.0/20, 172.19.32.0/20, and 172.21.0.0/16

    cn-shanghai-finance-1g

    192.168.48.0/20, 172.19.48.0/20, and 172.21.0.0/16

    cn-shanghai-finance-1k

    192.168.64.0/20, 172.19.64.0/20, and 172.21.0.0/16

    cn-shanghai-finance-1z

    192.168.80.0/20, 172.19.80.0/20, and 172.21.0.0/16

    China (Beijing)

    Zone

    Reserved CIDR block

    cn-beijing-a

    192.168.0.0/20, 172.19.0.0/20, and 172.22.0.0/16

    cn-beijing-b

    192.168.16.0/20, 172.19.16.0/20, and 172.22.0.0/16

    cn-beijing-c

    192.168.32.0/20, 172.19.32.0/20, and 172.22.0.0/16

    cn-beijing-d

    192.168.48.0/20, 172.19.48.0/20, and 172.22.0.0/16

    cn-beijing-e

    192.168.64.0/20, 172.19.64.0/20, and 172.22.0.0/16

    cn-beijing-f

    192.168.80.0/20, 172.19.80.0/20, and 172.22.0.0/16

    cn-beijing-g

    192.168.96.0/20, 172.19.96.0/20, and 172.22.0.0/16

    cn-beijing-h

    192.168.112.0/20, 172.19.112.0/20, and 172.22.0.0/16

    cn-beijing-i

    192.168.128.0/20, 172.19.128.0/20, and 172.22.0.0/16

    cn-beijing-j

    192.168.144.0/20, 172.19.144.0/20, and 172.22.0.0/16

    cn-beijing-k

    192.168.160.0/20, 172.19.160.0/20, and 172.22.0.0/16

    cn-beijing-l

    192.168.176.0/20, 172.19.176.0/20, and 172.22.0.0/16

    China North 2 Finance

    Zone

    Reserved CIDR block

    cn-beijing-finance-1k

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    cn-beijing-finance-1l

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    China (Shenzhen)

    Zone

    Reserved CIDR block

    cn-shenzhen-a

    192.168.0.0/20, 172.19.0.0/20, and 172.23.0.0/16

    cn-shenzhen-b

    192.168.16.0/20, 172.19.16.0/20, and 172.23.0.0/16

    cn-shenzhen-c

    192.168.32.0/20, 172.19.32.0/20, and 172.23.0.0/16

    cn-shenzhen-d

    192.168.48.0/20, 172.19.48.0/20, and 172.23.0.0/16

    cn-shenzhen-e

    192.168.64.0/20, 172.19.64.0/20, and 172.23.0.0/16

    cn-shenzhen-f

    192.168.80.0/20, 172.19.80.0/20, and 172.23.0.0/16

    China South 1 Finance

    Zone

    Reserved CIDR block

    cn-shenzhen-finance-1a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    cn-shenzhen-finance-1b

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    cn-shenzhen-finance-1d

    192.168.32.0/20, 172.19.32.0/20, and 172.20.0.0/16

    cn-shenzhen-finance-1e

    192.168.48.0/20, 172.19.48.0/20, and 172.20.0.0/16

    Heyuan ACDR Auto

    Zone

    Reserved CIDR block

    cn-heyuan-acdr-1a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    cn-heyuan-acdr-1b

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    China (Zhangjiakou)

    Zone

    Reserved CIDR block

    cn-zhangjiakou-a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    cn-zhangjiakou-b

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    cn-zhangjiakou-c

    192.168.32.0/20, 172.19.32.0/20, and 172.20.0.0/16

    China (Chengdu)

    Zone

    Reserved CIDR block

    cn-chengdu-a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    cn-chengdu-b

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    China (Qingdao)

    Zone

    Reserved CIDR block

    cn-qingdao-b

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    cn-qingdao-c

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    China (Hong Kong)

    Zone

    Reserved CIDR block

    cn-hongkong-b

    192.168.0.0/20, 172.19.0.0/20, and 172.21.0.0/16

    cn-hongkong-c

    192.168.16.0/20, 172.19.16.0/20, and 172.21.0.0/16

    cn-hongkong-d

    192.168.32.0/20, 172.19.32.0/20, and 172.21.0.0/16

    Singapore

    Zone

    Reserved CIDR block

    ap-southeast-1a

    192.168.0.0/20, 172.19.0.0/20, and 172.21.0.0/16

    ap-southeast-1b

    192.168.16.0/20, 172.19.16.0/20, and 172.21.0.0/16

    ap-southeast-1c

    192.168.32.0/20, 172.19.32.0/20, and 172.21.0.0/16

    Indonesia (Jakarta)

    Zone

    Reserved CIDR block

    ap-southeast-5a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    ap-southeast-5b

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    ap-southeast-5c

    192.168.32.0/20, 172.19.32.0/20, and 172.20.0.0/16

    Malaysia (Kuala Lumpur)

    Zone

    Reserved CIDR block

    ap-southeast-3a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    ap-southeast-3b

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    Japan (Tokyo)

    Zone

    Reserved CIDR block

    ap-northeast-1a

    192.168.0.0/20, 172.19.0.0/20, and 172.21.0.0/16

    ap-northeast-1b

    192.168.16.0/20, 172.19.16.0/20, and 172.21.0.0/16

    ap-northeast-1c

    192.168.32.0/20, 172.19.32.0/20, and 172.21.0.0/16

    South Korea (Seoul)

    Zone

    Reserved CIDR block

    ap-northeast-2a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    Germany (Frankfurt)

    Zone

    Reserved CIDR block

    eu-central-1a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    eu-central-1b

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    eu-central-1c

    192.168.32.0/20, 172.19.32.0/20, and 172.20.0.0/16

    UK (London)

    Zone

    Reserved CIDR block

    eu-west-1a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    eu-west-1b

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    US (Silicon Valley)

    Zone

    Reserved CIDR block

    us-west-1a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    us-west-1b

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    US (Virginia)

    Zone

    Reserved CIDR block

    us-east-1a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    us-east-1b

    192.168.16.0/20, 172.19.16.0/20, and 172.20.0.0/16

    UAE (Dubai)

    Zone

    Reserved CIDR block

    me-east-1a

    192.168.0.0/20, 172.19.0.0/20, and 172.20.0.0/16

    SAU (Riyadh - Partner Region)

    Zone

    Reserved CIDR block

    me-central-1a

    192.168.0.0/20, 172.19.0.0/20, and 172.16.20.0/24

    me-central-1b

    192.168.16.0/20, 172.19.16.0/20, and 172.16.20.0/24