VPC integration instance optimizes networking between API Gateway and your VPC, enabling direct private IP access to backend services without per-resource authorization.
Use cases
A VPC integration instance is a dedicated API Gateway instance that optimizes the network between API Gateway and your VPC. Typical scenarios:
-
Accessing multiple backend resources in a single VPC. Typical for microservices or service discovery (such as Nacos), where APIs connect to multiple services (ECS, SLB) in the same VPC.
-
Hybrid cloud connectivity. Backend services in a hybrid cloud often require requests from a private IP within their VPC.
API GatewayVPC integration instances meet this requirement. For more information, see Scenario 3: API Gateway accesses a backend service in an on-premises data center over an internal network.
Differences from conventional dedicated instances
The following table compares the two instance types.
|
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. |
|
Forwarding to multiple resources in the same VPC |
Recommended. Example: service registration and discovery. |
Supported, but requires configuring a |
|
Forwarding to resources in multiple VPCs |
Not supported. You must manually establish network connectivity between the VPCs. |
Recommended. You can configure multiple |
|
Configuration process |
Specify the target VPC during instance creation. No additional API configuration is required. |
Requires configuring a |
-
The egress IP address is the source IP that a backend service sees when it receives a request from
API Gateway. -
VPC access authorization: Conventional dedicated instances require a
VPC access authorizationto access VPC resources. For more information, see Use a resource in a VPC as the backend service of an API. -
VPC integration instances do not support DataWorks integration. Only conventional dedicated instances support DataWorks.
Purchase a VPC integration instance
On the API Gateway purchase page, set Type to VPC integration instance.
Configure the following settings for a VPC integration instance:
-
VPC ID: The VPC to connect to. This cannot be changed after creation.
-
CIDR Block: A CIDR block for the
API Gatewayinstance. This block must not conflict with your selectedvSwitchCIDR block. A conflict causes instance creation to fail. -
Zone and security group:
API Gatewaycreates an ENI in thevSwitchandSecurity Groupof the specified zone and binds it to theAPI Gatewayinstance. Your VPC resources must be within the specifiedvSwitchCIDR block and in the same security group. The security group outbound rules must allow traffic to the destination IP range.ImportantAPI Gatewayuses an internal resource CIDR block. ThevSwitchyou specify must not overlap with this internal CIDR block. For a list of CIDR blocks reserved byVPC integration instancesin each region, see Reserved CIDR blocks by region. -
Service-linked role:
API Gatewayrequires a service-linked role to manage ENI resources in your VPC. For more details about this role, see AliyunServiceRoleForApiGatewayConnectUserVpc.
About the ENI created by API Gateway in your VPC:
-
The ENI resides in your VPC and is subject to your VPC's network configurations and security rules, such as security groups.
-
If the backend is an ECS instance in the same security group as the ENI, and intra-group communication is enabled, no additional outbound rules are needed.
-
If the backend is a CLB instance, the security group outbound rules must allow traffic to the destination IP range, regardless of whether the CLB instance is in the same
vSwitch.
-
-
The ENI created by
API Gatewaydoes not incur additional charges.
Usage
Add accessible CIDR blocks
By default, a VPC integration instance can only access services within the vSwitch CIDR block specified at creation. To access other CIDR blocks, add them in the VPC network access section of the instance details page in the API Gateway console:
-
Log on to the
176API Gatewayconsole. In the left-side navigation pane, click Instances. 177 - 178
Find the target
VPC integration instanceand click Add in the Access Allowed From column. -
Add a CIDR block by selecting one from the drop-down list or entering one manually.
NoteA manually entered CIDR block must be within or connected to the VPC you specified when creating the instance.
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 connects to the VPC access authorization target through the ENI in your VPC.
Before configuring a VPC access authorization for an API or plug-in on a VPC integration instance, verify the following:
-
The VPC ID in the
VPC access authorizationdefinition is the same as the ID of the VPC connected to the instance. -
The private IP address of the service in the
VPC access authorizationfalls within the accessible CIDR block of the VPC integration instance.NoteWhen you publish an API or modify a
plug-in, if you receive an error message such asinstance 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 migrate an API Group to a VPC integration instance, change its bound instance from a Serverless or conventional dedicated instance to a VPC integration instance.
-
Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > API Groups.
-
Find the group that you want to migrate and click its name to go to the group details page.
-
Click Modify Instance for API Group Deployment and select the VPC integration instance that you created.
-
API Gatewayvalidates theVPC access authorizationsused by APIs andplug-insin theAPI Group. If validation succeeds, the migration completes. If it fails, the system rolls back and displays the failure reason.Important-
Before migration, the system validates the following for VPC-based APIs and
plug-ins:-
The VPC ID in the
VPC access authorizationdefinition is the same as the ID of the VPC connected to the instance. -
The private IP address of the service in the
VPC access authorizationfalls within the accessible CIDR block of the VPC integration instance.
-
-
If your
API Groupuses aVPC access authorization, ensure that the security group of the corresponding ECS/SLB service is the same as the security group specified when you created theVPC integration instance. -
After migration, the egress IP address changes. If your backend uses an allowlist, add the new egress IP before migrating.
-
Reserved CIDR blocks by 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 |