Integrate your app with an Azure virtual network

This article describes the Azure App Service virtual network integration feature and how to set it up with apps in App Service. With Azure virtual networks, you can place many of your Azure resources in a non-internet-routable network. The App Service virtual network integration feature enables your apps to access resources in or through a virtual network.

Note

Information about Gateway-required virtual network integration has moved to a new location.

App Service has two variations:

  • The dedicated compute pricing tiers, which include the Basic, Standard, Premium, Premium v2, and Premium v3.
  • The App Service Environment, which deploys directly into your virtual network with dedicated supporting infrastructure and is using the Isolated and Isolated v2 pricing tiers.

The virtual network integration feature is used in Azure App Service dedicated compute pricing tiers. If your app is in an App Service Environment, it's already integrated with a virtual network and doesn't require you to configure virtual network integration feature to reach resources in the same virtual network. For more information on all the networking features, see App Service networking features.

Virtual network integration gives your app access to resources in your virtual network, but it doesn't grant inbound private access to your app from the virtual network. Private site access refers to making an app accessible only from a private network, such as from within an Azure virtual network. Virtual network integration is used only to make outbound calls from your app into your virtual network. Refer to private endpoint for inbound private access.

The virtual network integration feature:

  • Requires a supported Basic or Standard, Premium, Premium v2, Premium v3, or Elastic Premium App Service pricing tier.
  • Supports TCP and UDP.
  • Works with App Service apps, function apps and Logic apps.

There are some things that virtual network integration doesn't support, like:

  • Mounting a drive.
  • Windows Server Active Directory domain join.
  • NetBIOS.

Virtual network integration supports connecting to a virtual network in the same region. Using virtual network integration enables your app to access:

  • Resources in the virtual network you're integrated with.
  • Resources in virtual networks peered to the virtual network your app is integrated with including global peering connections.
  • Resources across Azure ExpressRoute connections.
  • Service endpoint-secured services.
  • Private endpoint-enabled services.

When you use virtual network integration, you can use the following Azure networking features:

  • Network security groups (NSGs): You can block outbound traffic with an NSG that's placed on your integration subnet. The inbound rules don't apply because you can't use virtual network integration to provide inbound access to your app.
  • Route tables (UDRs): You can place a route table on the integration subnet to send outbound traffic where you want.
  • NAT gateway: You can use NAT gateway to get a dedicated outbound IP and mitigate SNAT port exhaustion.

Learn how to enable virtual network integration.

How virtual network integration works

Apps in App Service are hosted on worker roles. Virtual network integration works by mounting virtual interfaces to the worker roles with addresses in the delegated subnet. Because the from address is in your virtual network, it can access most things in or through your virtual network like a VM in your virtual network would.

Diagram that shows how virtual network integration works.

When virtual network integration is enabled, your app makes outbound calls through your virtual network. The outbound addresses that are listed in the app properties portal are the addresses still used by your app. However, if your outbound call is to a virtual machine or private endpoint in the integration virtual network or peered virtual network, the outbound address will be an address from the integration subnet. The private IP assigned to an instance is exposed via the environment variable, WEBSITE_PRIVATE_IP.

When all traffic routing is enabled, all outbound traffic is sent into your virtual network. If all traffic routing isn't enabled, only private traffic (RFC1918) and service endpoints configured on the integration subnet will be sent into the virtual network. Outbound traffic to the internet will be routed directly from the app.

The feature supports two virtual interfaces per worker. Two virtual interfaces per worker mean two virtual network integrations per App Service plan. The apps in the same App Service plan can only use one of the virtual network integrations to a specific subnet. If you need an app to connect to more virtual networks or more subnets in the same virtual network, you need to create another App Service plan. The virtual interfaces used aren't resources customers have direct access to.

Subnet requirements

Virtual network integration depends on a dedicated subnet. When you create a subnet, the Azure subnet consumes five IPs from the start. One address is used from the integration subnet for each plan instance. If you scale your app to four instances, then four addresses are used.

When you scale up or down in size, the required address space is doubled for a short period of time. The scale operation affects the real, available supported instances for a given subnet size. The following table shows both the maximum available addresses per CIDR block and the effect the available addresses has on horizontal scale.

CIDR block size Maximum available addresses Maximum horizontal scale (instances)*
/28 11 5
/27 27 13
/26 59 29

*Assumes that you'll need to scale up or down in either size or SKU at some point.

Because subnet size can't be changed after assignment, use a subnet that's large enough to accommodate whatever scale your app might reach. To avoid any issues with subnet capacity, use a /26 with 64 addresses. When you're creating subnets in Azure portal as part of integrating with the virtual network, a minimum size of /27 is required. If the subnet already exists before integrating through the portal, you can use a /28 subnet.

Note

Windows Containers uses an additional IP address per app for each App Service plan instance, and you need to size the subnet accordingly. If you have for example 10 Windows Container App Service plan instances with 4 apps running, you will need 50 IP addresses and additional addresses to support horizontal (up/down) scale.

When you want your apps in your plan to reach a virtual network that's already connected to by apps in another plan, select a different subnet than the one being used by the pre-existing virtual network integration.

Permissions

You must have at least the following Role-based access control permissions on the subnet or at a higher level to configure virtual network integration through Azure portal, CLI or when setting the virtualNetworkSubnetId site property directly:

Action Description
Microsoft.Network/virtualNetworks/read Read the virtual network definition
Microsoft.Network/virtualNetworks/subnets/read Read a virtual network subnet definition
Microsoft.Network/virtualNetworks/subnets/join/action Joins a virtual network

If the virtual network is in a different subscription than the app, you must ensure that the subscription with the virtual network is registered for the Microsoft.Web resource provider. You can explicitly register the provider by following this documentation, but it will also automatically be registered when creating the first web app in a subscription.

Routes

You can control what traffic goes through the virtual network integration. There are three types of routing to consider when you configure virtual network integration. Application routing defines what traffic is routed from your app and into the virtual network. Configuration routing affects operations that happen before or during startup of your app. Examples are container image pull and app settings with Key Vault reference. Network routing is the ability to handle how both app and configuration traffic are routed from your virtual network and out.

Through application routing or configuration routing options, you can configure what traffic will be sent through the virtual network integration. Traffic is only subject to network routing if it's sent through the virtual network integration.

Application routing

Application routing applies to traffic that is sent from your app after it has been started. See configuration routing for traffic during startup. When you configure application routing, you can either route all traffic or only private traffic (also known as RFC1918 traffic) into your virtual network. You configure this behavior through the Route All setting. If Route All is disabled, your app only routes private traffic into your virtual network. If you want to route all your outbound app traffic into your virtual network, make sure that Route All is enabled.

  • Only traffic configured in application or configuration routing is subject to the NSGs and UDRs that are applied to your integration subnet.
  • When Route All is enabled, the source address for your outbound public traffic from your app is still one of the IP addresses that are listed in your app properties. If you route your traffic through a firewall or a NAT gateway, the source IP address will then originate from this service.

Learn how to configure application routing.

Note

Outbound SMTP connectivity (port 25) is supported for App Service when the SMTP traffic is routed through the virtual network integration. The supportability is determined by a setting on the subscription where the virtual network is deployed. For virtual networks/subnets created before 1. August 2022 you need to initiate a temporary configuration change to the virtual network/subnet for the setting to be synchronized from the subscription. An example could be to add a temporary subnet, associate/dissociate an NSG temporarily or configure a service endpoint temporarily. For more information, see Troubleshoot outbound SMTP connectivity problems in Azure.

Configuration routing

When you're using virtual network integration, you can configure how parts of the configuration traffic are managed. By default, configuration traffic will go directly over the public route, but for the mentioned individual components, you can actively configure it to be routed through the virtual network integration.

Content share

Bringing your own storage for content in often used in Functions where content share is configured as part of the Functions app.

To route content share traffic through the virtual network integration, you must ensure that the routing setting is configured. Learn how to configure content share routing.

In addition to configuring the routing, you must also ensure that any firewall or Network Security Group configured on traffic from the subnet allow traffic to port 443 and 445.

Container image pull

When using custom containers, you can pull the container over the virtual network integration. To route the container pull traffic through the virtual network integration, you must ensure that the routing setting is configured. Learn how to configure image pull routing.

App settings using Key Vault references

App settings using Key Vault references will attempt to get secrets over the public route. If the Key Vault is blocking public traffic and the app is using virtual network integration, an attempt will then be made to get the secrets through the virtual network integration.

Note

  • Backup/restore to private storage accounts is currently not supported.
  • Configure SSL/TLS certificates from private Key Vaults is currently not supported.
  • App Service Logs to private storage accounts is currently not supported. We recommend using Diagnostics Logging and allowing Trusted Services for the storage account.

Network routing

You can use route tables to route outbound traffic from your app without restriction. Common destinations can include firewall devices or gateways. You can also use a network security group (NSG) to block outbound traffic to resources in your virtual network or the internet. An NSG that's applied to your integration subnet is in effect regardless of any route tables applied to your integration subnet.

Route tables and network security groups only apply to traffic routed through the virtual network integration. See application routing and configuration routing for details. Routes won't apply to replies from inbound app requests and inbound rules in an NSG don't apply to your app. Virtual network integration affects only outbound traffic from your app. To control inbound traffic to your app, use the access restrictions feature or private endpoints.

When configuring network security groups or route tables that applies to outbound traffic, you must make sure you consider your application dependencies. Application dependencies include endpoints that your app needs during runtime. Besides APIs and services the app is calling, these endpoints could also be derived endpoints like certificate revocation list (CRL) check endpoints and identity/authentication endpoint, for example Azure Active Directory. If you're using continuous deployment in App Service, you might also need to allow endpoints depending on type and language. Specifically for Linux continuous deployment, you'll need to allow oryx-cdn.microsoft.io:443.

When you want to route outbound traffic on-premises, you can use a route table to send outbound traffic to your Azure ExpressRoute gateway. If you do route traffic to a gateway, set routes in the external network to send any replies back. Border Gateway Protocol (BGP) routes also affect your app traffic. If you have BGP routes from something like an ExpressRoute gateway, your app outbound traffic is affected. Similar to user-defined routes, BGP routes affect traffic according to your routing scope setting.

Service endpoints

Virtual network integration enables you to reach Azure services that are secured with service endpoints. To access a service endpoint-secured service, follow these steps:

  1. Configure virtual network integration with your web app to connect to a specific subnet for integration.
  2. Go to the destination service and configure service endpoints against the integration subnet.

Private endpoints

If you want to make calls to private endpoints, make sure that your DNS lookups resolve to the private endpoint. You can enforce this behavior in one of the following ways:

  • Integrate with Azure DNS private zones. When your virtual network doesn't have a custom DNS server, the integration is done automatically when the zones are linked to the virtual network.
  • Manage the private endpoint in the DNS server used by your app. To manage the configuration, you must know the private endpoint IP address. Then point the endpoint you're trying to reach to that address by using an A record.
  • Configure your own DNS server to forward to Azure DNS private zones.

Azure DNS private zones

After your app integrates with your virtual network, it uses the same DNS server that your virtual network is configured with. If no custom DNS is specified, it uses Azure default DNS and any private zones linked to the virtual network.

Limitations

There are some limitations with using virtual network integration:

  • The feature is available from all App Service deployments in Premium v2 and Premium v3. It's also available in Basic and Standard tier but only from newer App Service deployments. If you're on an older deployment, you can only use the feature from a Premium v2 App Service plan. If you want to make sure you can use the feature in a Basic or Standard App Service plan, create your app in a Premium v3 App Service plan. Those plans are only supported on our newest deployments. You can scale down if you want after the plan is created.
  • The feature can't be used by Isolated plan apps that are in an App Service Environment.
  • You can't reach resources across peering connections with classic virtual networks.
  • The feature requires an unused subnet that's an IPv4 /28 block or larger in an Azure Resource Manager virtual network.
  • The app and the virtual network must be in the same region.
  • The integration virtual network can't have IPv6 address spaces defined.
  • The integration subnet can't have service endpoint policies enabled.
  • The integration subnet can be used by only one App Service plan.
  • You can't delete a virtual network with an integrated app. Remove the integration before you delete the virtual network.
  • You can't have more than two virtual network integrations per App Service plan. Multiple apps in the same App Service plan can use the same virtual network integration. Currently you can only configure the first integration through Azure portal. The second integration must be created using Azure Resource Manager templates or Azure CLI commands.
  • You can't change the subscription of an app or a plan while there's an app that's using virtual network integration.

Access on-premises resources

No extra configuration is required for the virtual network integration feature to reach through your virtual network to on-premises resources. You simply need to connect your virtual network to on-premises resources by using ExpressRoute or a site-to-site VPN.

Peering

If you use peering with virtual network integration, you don't need to do any more configuration.

Manage virtual network integration

Connecting and disconnecting with a virtual network is at an app level. Operations that can affect virtual network integration across multiple apps are at the App Service plan level. From the app > Networking > VNet integration portal, you can get details on your virtual network. You can see similar information at the App Service plan level in the App Service plan > Networking > VNet integration portal.

In the app view of your virtual network integration instance, you can disconnect your app from the virtual network and you can configure application routing. To disconnect your app from a virtual network, select Disconnect. Your app is restarted when you disconnect from a virtual network. Disconnecting doesn't change your virtual network. The subnet isn't removed. If you then want to delete your virtual network, first disconnect your app from the virtual network.

The private IP assigned to the instance is exposed via the environment variable WEBSITE_PRIVATE_IP. Kudu console UI also shows the list of environment variables available to the web app. This IP is assigned from the address range of the integrated subnet. This IP will be used by the web app to connect to the resources through the Azure virtual network.

Note

The value of WEBSITE_PRIVATE_IP is bound to change. However, it will be an IP within the address range of the integration subnet, so you'll need to allow access from the entire address range.

Pricing details

The virtual network integration feature has no extra charge for use beyond the App Service plan pricing tier charges.

Troubleshooting

The feature is easy to set up, but that doesn't mean your experience will be problem free. If you encounter problems accessing your desired endpoint, there are various steps you can take depending on what you are observing. For more information, see virtual network integration troubleshooting guide.

Note

  • Virtual network integration isn't supported for Docker Compose scenarios in App Service.
  • Access restrictions does not apply to traffic coming through a private endpoint.

Deleting the App Service plan or app before disconnecting the network integration

If you deleted the app or the App Service plan without disconnecting the virtual network integration first, you won't be able to do any update/delete operations on the virtual network or subnet that was used for the integration with the deleted resource. A subnet delegation 'Microsoft.Web/serverFarms' will remain assigned to your subnet and will prevent the update/delete operations.

In order to do update/delete the subnet or virtual network again, you need to re-create the virtual network integration, and then disconnect it:

  1. Re-create the App Service plan and app (it's mandatory to use the exact same web app name as before).
  2. Navigate to Networking on the app in Azure portal and configure the virtual network integration.
  3. After the virtual network integration is configured, select the 'Disconnect' button.
  4. Delete the App Service plan or app.
  5. Update/Delete the subnet or virtual network.

If you still encounter issues with the virtual network integration after following these steps, contact Microsoft Support.