Skip to content

Commit cdad507

Browse files
seligj95seligj95
committed
copilot
1 parent 875a86f commit cdad507

File tree

1 file changed

+249
-29
lines changed

1 file changed

+249
-29
lines changed

‎articles/app-service/migrate-gateway-based-vnet-integration.md

Lines changed: 249 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,268 @@
11
---
2-
title: Migrate from gateway-based virtual network integration
3-
description: Migrate your virtual network integration from gateway-based integration to regional integration.
2+
title: Migrate from gateway-based to regional virtual network integration
3+
description: Learn how to migrate your App Service virtual network integration from legacy gateway-based integration to modern regional virtual network integration for improved performance and capabilities.
44
author: seligj95
55
ms.topic: how-to
66
ms.date: 06/19/2025
77
ms.author: jordanselig
8+
ms.custom: devx-track-azurecli, devx-track-azurepowershell
89
---
9-
# Migrate from gateway-based virtual network integration
10+
# Migrate from gateway-based to regional virtual network integration
1011

11-
There are two ways in App Service to integrate with a virtual network. One way is gateway-based integration using a virtual network gateway that establishes a point-to-site VPN connection from the app to the virtual network. The other way is known as virtual network integration since more than 99% of all integrations are using this method. Virtual network integration has several advantages over gateway-based integration. The only edge case scenario where gateway-based integration is preferred is when you need to connect directly to a virtual network in a different region and aren't able to set up peerings.
12+
App Service supports two types of virtual network integration: **regional virtual network integration** (recommended) and **gateway-based virtual network integration** (legacy). This article guides you through migrating from the legacy gateway-based approach to the modern regional integration method.
13+
14+
## Overview
15+
16+
Regional virtual network integration is the recommended approach for connecting your App Service apps to Azure virtual networks. Unlike gateway-based integration, regional integration doesn't require a VPN gateway and provides superior performance, broader feature support, and enhanced security capabilities.
17+
18+
**Why migrate?** More than 99% of App Service virtual network integrations use the regional method due to its advantages. Gateway-based integration should only be considered when you need to connect directly to a virtual network in a different region and you can't establish virtual network peering.
19+
20+
## Key differences and benefits
21+
22+
Gateway-based integration has significant limitations that regional integration addresses:
23+
24+
### Gateway-based integration limitations
1225

1326
Gateway-based integration can't be used in the following scenarios:
1427

15-
* With a virtual network connected with ExpressRoute.
16-
* From a Linux app.
17-
* From a Windows container.
18-
* To access service endpoint-secured resources.
19-
* To resolve App Settings referencing a network protected Key Vault.
20-
* With a coexistence gateway that supports both ExpressRoute and point-to-site or site-to-site VPNs.
28+
* With virtual networks connected to ExpressRoute
29+
* From Linux apps
30+
* From Windows container apps
31+
* To access service endpoint-secured resources
32+
* To resolve App Settings referencing a network-protected Key Vault
33+
* With coexistence gateways supporting both ExpressRoute and point-to-site/site-to-site VPNs
34+
35+
### Feature comparison
36+
37+
| Feature | Regional virtual network integration | Gateway-based integration |
38+
|:--------|:-------------------------------------|:--------------------------|
39+
| **Gateway requirement** | None | Virtual network gateway required |
40+
| **Bandwidth** | No VPN limitations | Limited by SSTP point-to-site VPN |
41+
| **Connectivity** | Two subnets per App Service plan | Five virtual networks per plan |
42+
| **Network features** | Route tables, NSGs, NAT gateway | Not supported |
43+
| **Platform support** | Windows, Linux, Windows containers | Windows only |
44+
| **Service endpoints** | Full support | Not supported |
45+
| **Key Vault integration** | Network-protected Key Vault app setting support | Not supported |
46+
| **ExpressRoute compatibility** | Full support | Not supported |
47+
| **Cross-region connectivity** | Through global peering only | Direct connection supported |
48+
| **Performance** | Native virtual network performance | VPN overhead |
49+
| **Scaling** | Better resource utilization | Limited by gateway capacity |
50+
51+
## Prerequisites
52+
53+
Before beginning the migration, ensure you have:
54+
55+
* **App Service plan**: A Basic, Standard, Premium, PremiumV2, PremiumV3, or Elastic Premium plan
56+
* **Virtual network**: An Azure Resource Manager virtual network in the same region as your app
57+
* **Subnet**: An empty subnet or a new subnet dedicated for virtual network integration
58+
* **Permissions**: Appropriate RBAC permissions to configure virtual network integration
59+
* **Planning**: Understanding of your current networking requirements and dependencies
60+
61+
## Migration planning and preparation
62+
63+
The migration process is a disconnect/connect operation that might cause brief downtime. Proper planning minimizes issues with your applications.
64+
65+
### Step 1: Assess your current setup
66+
67+
1. **Document existing connections**: Note which apps use gateway-based integration
68+
2. **Identify dependencies**: Catalog resources accessed through the current integration
69+
3. **Review networking rules**: Document any NSGs, route tables, or firewall rules
70+
4. **Plan downtime**: Schedule migration during maintenance windows
71+
72+
### Step 2: Subnet planning and requirements
73+
74+
The subnet used for regional virtual network integration must meet [specific requirements](./overview-vnet-integration.md#subnet-requirements). You can either have one subnet per plan or take advantage of the [multi-plan subnet join feature](./overview-vnet-integration.md#subnet-requirements) to connect apps from different plans to the same subnet.
75+
76+
* **Size**: Minimum `/28` (16 addresses), recommended `/26` (64 addresses) for production
77+
* **Delegation**: Must be delegated to `Microsoft.Web/serverFarms`
78+
* **Availability**: Can't be used by other services simultaneously
79+
* **Location**: Must be in the same virtual network you want to integrate with
80+
81+
> [!TIP]
82+
> Always provision double the IP addresses of your expected maximum scale to accommodate platform upgrades and scaling operations.
83+
84+
### Step 3: Create or prepare the integration subnet
85+
86+
# [Azure portal](#tab/portal)
87+
88+
1. Navigate to your virtual network in the Azure portal
89+
2. Select **Subnets** > **+ Subnet**
90+
3. Configure the subnet:
91+
- **Name**: Choose a descriptive name (for example `app-service-integration`)
92+
- **Address range**: Select appropriate CIDR block
93+
- **Subnet delegation**: Select `Microsoft.Web/serverFarms`
94+
4. Select **Save**
95+
96+
# [Azure CLI](#tab/cli)
97+
98+
```azurecli-interactive
99+
# Create a new subnet for App Service integration
100+
az network vnet subnet create \
101+
--resource-group <resource-group-name> \
102+
--vnet-name <vnet-name> \
103+
--name <subnet-name> \
104+
--address-prefixes <cidr-block> \
105+
--delegations Microsoft.Web/serverFarms
106+
```
107+
108+
# [Azure PowerShell](#tab/powershell)
109+
110+
```azurepowershell-interactive
111+
# Create a new subnet for App Service integration
112+
$vnet = Get-AzVirtualNetwork -ResourceGroupName <resource-group-name> -Name <vnet-name>
113+
Add-AzVirtualNetworkSubnetConfig -Name <subnet-name> -VirtualNetwork $vnet -AddressPrefix <cidr-block> -Delegation "Microsoft.Web/serverFarms"
114+
Set-AzVirtualNetwork -VirtualNetwork $vnet
115+
```
116+
117+
---
118+
119+
## Migration procedure
120+
121+
### Same-region migration (most common)
122+
123+
When migrating from gateway-based integration to regional integration within the same region:
124+
125+
![Diagram showing migration from gateway-based to regional virtual network integration](media/migrate-gateway-based-vnet-integration/same-region-migration.png)
126+
127+
#### Step 1: Disconnect gateway-based integration
128+
129+
# [Azure portal](#tab/portal)
130+
131+
1. Go to your app in the Azure portal
132+
2. Select **Settings** > **Networking**
133+
3. Under **VNet Integration**, select **Disconnect**
134+
4. Confirm the disconnection
135+
136+
# [Azure CLI](#tab/cli)
137+
138+
```azurecli-interactive
139+
# Disconnect gateway-based virtual network integration
140+
az webapp vnet-integration remove \
141+
--resource-group <resource-group-name> \
142+
--name <app-name>
143+
```
144+
145+
# [Azure PowerShell](#tab/powershell)
146+
147+
```azurepowershell-interactive
148+
# Disconnect gateway-based virtual network integration
149+
$webApp = Get-AzWebApp -ResourceGroupName <resource-group-name> -Name <app-name>
150+
$webApp.VirtualNetworkSubnetId = $null
151+
Set-AzWebApp -WebApp $webApp
152+
```
153+
154+
---
155+
156+
#### Step 2: Configure regional virtual network integration
157+
158+
# [Azure portal](#tab/portal)
159+
160+
1. In your app, select **Settings** > **Networking**
161+
2. Under **Outbound traffic configuration**, select **Not configured** next to Virtual network integration
162+
3. Select **Add virtual network integration**
163+
4. Choose your virtual network and the prepared subnet
164+
5. Select **Connect**
165+
166+
# [Azure CLI](#tab/cli)
167+
168+
```azurecli-interactive
169+
# Configure regional virtual network integration
170+
az webapp vnet-integration add \
171+
--resource-group <resource-group-name> \
172+
--name <app-name> \
173+
--vnet <vnet-name> \
174+
--subnet <subnet-name>
175+
```
176+
177+
# [Azure PowerShell](#tab/powershell)
178+
179+
```azurepowershell-interactive
180+
# Configure regional virtual network integration
181+
$subnetResourceId = "/subscriptions/<subscription-id>/resourceGroups/<vnet-resource-group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>/subnets/<subnet-name>"
182+
$webApp = Get-AzResource -ResourceType Microsoft.Web/sites -ResourceGroupName <resource-group-name> -ResourceName <app-name>
183+
$webApp.Properties.virtualNetworkSubnetId = $subnetResourceId
184+
$webApp.Properties.vnetRouteAllEnabled = 'true'
185+
$webApp | Set-AzResource -Force
186+
```
187+
188+
---
189+
190+
#### Step 3: Verify connectivity
191+
192+
After integration is complete, test your app's connectivity to virtual network resources:
193+
194+
1. **Application testing**: Verify your app can access databases, storage, and other resources
195+
2. **DNS resolution**: Confirm DNS queries resolve correctly for private resources
196+
3. **Performance testing**: Monitor application performance after the migration
197+
198+
### Cross-region migration considerations
199+
200+
If you're currently using gateway-based integration to connect to a virtual network in a different region, you can set up [virtual network peering](../virtual-network/virtual-network-peering-overview.md):
201+
202+
1. Create a virtual network in your app's region
203+
2. Establish virtual network peering between regions
204+
3. Set up regional virtual network integration with the local virtual network
205+
4. Configure routing to access cross-region resources through peering
206+
207+
## Post-migration configuration and optimization
208+
209+
After successfully migrating to regional virtual network integration, you can take advantage of other features and optimizations:
210+
211+
* Enhance routing capabilities with [advanced traffic routing configurations](./overview-vnet-integration.md#routes)
212+
* Control outbound traffic with [Network Security Groups (NSGs)](./overview-vnet-integration.md#network-routing)
213+
* Direct traffic through specific network appliances with [User Defined Routes (UDRs)](./overview-vnet-integration.md#application-routing)
214+
* Obtain static outbound IP addresses and increase SNAT port availability with [NAT Gateway integration](./overview-inbound-outbound-ips.md#get-a-static-outbound-ip)
215+
* Enable [service endpoints](./overview-vnet-integration.md#service-endpoints) for Azure services
216+
* Connect to Azure services using [private endpoints](./overview-vnet-integration.md#private-endpoints) for enhanced security
217+
* Set up [private DNS zones](./overview-vnet-integration.md#azure-dns-private-zones) for name resolution of private endpoints
218+
219+
## Troubleshooting common issues
220+
221+
### Connectivity problems
222+
223+
**Issue**: App can't reach virtual network resources after migration
224+
225+
**Solutions**:
226+
1. Verify subnet delegation is set to `Microsoft.Web/serverFarms`
227+
2. Check NSG rules allow required traffic
228+
3. Ensure Route All is enabled if needed
229+
4. Confirm DNS resolution is working
230+
231+
### Performance issues
232+
233+
**Issue**: Slower performance after migration
234+
235+
**Solutions**:
236+
1. Monitor network latency to virtual network resources
237+
2. Review and optimize NSG and UDR configurations
238+
3. Consider enabling NAT Gateway for better SNAT port availability
239+
4. Check for bandwidth limitations in network appliances
21240

22-
| Feature | Virtual network integration | Gateway-based integration |
23-
| :-----------------------------------------------------: | :-----------------------------------: | :----------------------------: |
24-
| Gateway required | No | Yes |
25-
| Bandwidth limit | Virtual machine limit | SSTP Point-to-site VPN limit |
26-
| Connect up to | Two subnets per plan | Five virtual networks per plan |
27-
| Route table, NSG, NAT gateway support | Yes | No |
28-
| OS Support | Windows, Linux, and Windows Container | Windows only |
29-
| Access service endpoints | Yes | No |
30-
| Resolve network protected Key Vault app settings | Yes | No |
31-
| Co-connect to virtual network with Express Route | Yes | No |
32-
| Connect directly to virtual network in different region | Only through global peerings | Yes |
241+
### IP address exhaustion
33242

34-
## Migration path and planning
243+
**Issue**: Running out of IP addresses in integration subnet
35244

36-
The complexity and planning of migration varies based on your current setup. Migrating from gateway-based to regional virtual network integration is a disconnect/connect operation. Before making the switch, make sure you have a subnet configured for your apps. The subnet must meet certain [requirements](./overview-vnet-integration.md#subnet-requirements). You can either have one subnet per plan or take advantage of the [multi-plan subnet join feature](./overview-vnet-integration.md#subnet-requirements) to connect apps from different plans to the same subnet. You should spend time planning your subnet address range. The general recommendation is to have double the IPs as the expected maximum planned instances of your plan. You should also delegate the subnet to `Microsoft.Web/serverFarms`.
245+
**Solutions**:
246+
1. Move to a larger subnet (can't resize existing subnet)
247+
2. Implement multi-plan subnet join to consolidate plans
248+
3. Monitor and right-size your App Service plan instances
37249

38-
## Same region migration
250+
### DNS resolution issues
39251

40-
If you're connecting to a gateway in the same region as your app, the migration is simple. First you need to select or create a subnet in the virtual network where the apps integrate going forward.
252+
**Issue**: Can't resolve private DNS names
41253

42-
![Diagram that illustrates moving to virtual network integration.](media/migrate-gateway-based-vnet-integration/same-region-migration.png)
254+
**Solutions**:
255+
1. Configure Azure DNS private zones
256+
2. Set up custom DNS servers in virtual network settings
257+
3. Verify private endpoint DNS configuration
43258

44-
Then you need to configure the virtual network integration following the standard process described in [Enable virtual network integration in Azure App Service](./configure-vnet-integration-enable.md).
259+
## Next steps
45260

46-
## Post configurations
261+
After successfully migrating to regional virtual network integration, explore these related articles:
47262

48-
After moving to regional virtual network integration, you have new options that you can take advantage of. You can decide if configuration options like backup/restore and image pull for container based workloads should be [routed through the virtual network](./overview-vnet-integration.md#configuration-routing). You can also define Network Security Groups or User Defined Routes for the individual subnets. You can also increase SNAT ports and get a [deterministic outbound public source IP by attaching a NAT gateway to the subnet](./overview-inbound-outbound-ips.md#get-a-static-outbound-ip).
263+
* [Enable virtual network integration in Azure App Service](./configure-vnet-integration-enable.md)
264+
* [Configure virtual network integration routing](./configure-vnet-integration-routing.md)
265+
* [Azure NAT Gateway integration](./overview-nat-gateway-integration.md)
266+
* [App Service networking features overview](./networking-features.md)
267+
* [Virtual network integration overview](./overview-vnet-integration.md)
268+
* [Troubleshoot virtual network integration](../includes/app-service-web-vnet-troubleshooting.md)

0 commit comments

Comments
 (0)