Deploy your Azure API Management instance to a virtual network - external mode

Availability

Azure API Management can be deployed (injected) inside an Azure virtual network (VNet) to access backend services within the network. For VNet connectivity options, requirements, and considerations, see:

• Using a virtual network with Azure API Management
• Network resource requirements for API Management injection into a virtual network

This article explains how to set up VNet connectivity for your API Management instance in the external mode, where the developer portal, API gateway, and other API Management endpoints are accessible from the public internet, and backend services are located in the network.

For configurations specific to the internal mode, where the endpoints are accessible only within the VNet, see Deploy your Azure API Management instance to a virtual network - internal mode.

Prerequisites

Enable VNet connection

Enable VNet connectivity using the Azure portal (stv2 compute platform)

1. Go to the Azure portal to find your API management instance. Search for and select API Management services.

2. Choose your API Management instance.

3. Select Network.

4. Select the External access type.

5. In the list of locations (regions) where your API Management service is provisioned:

   1. Choose a Location.
   2. Select Virtual network, Subnet, and (optionally) IP address.

   • The VNet list is populated with Resource Manager VNets available in your Azure subscriptions, set up in the region you are configuring.

     

6. Select Apply. The Network page of your API Management instance is updated with your new VNet and subnet choices.

7. Continue configuring VNet settings for the remaining locations of your API Management instance.

8. In the top navigation bar, select Save.

It can take 15 to 45 minutes to update the API Management instance. Instances in the Developer tier have downtime during the process. Instances in the Premium tier don't have downtime during the process.

Enable connectivity using a Resource Manager template (stv2 compute platform)

• Azure Resource Manager template (API version 2021-08-01)

  

Enable connectivity using Azure PowerShell cmdlets (stv1 platform)

Create or update an API Management instance in a VNet.

Configure NSG rules

Configure custom network rules in the API Management subnet to filter traffic to and from your API Management instance. We recommend the following minimum NSG rules to ensure proper operation and access to your instance.

• For most scenarios, use the indicated service tags instead of service IP addresses to specify network sources and destinations.
• Set the priority of these rules higher than that of the default rules.

Connect to a web service hosted within a virtual network

Once you've connected your API Management service to the VNet, you can access backend services within it just as you do public services. When creating or editing an API, type the local IP address or the host name (if a DNS server is configured for the VNet) of your web service into the Web service URL field.

Custom DNS server setup

In external VNet mode, Azure manages the DNS by default. You can optionally configure a custom DNS server.

The API Management service depends on several Azure services. When API Management is hosted in a VNet with a custom DNS server, it needs to resolve the hostnames of those Azure services.

• For guidance on custom DNS setup, including forwarding for Azure-provided hostnames, see Name resolution for resources in Azure virtual networks.
• Outbound network access on port 53 is required for communication with DNS servers. For more settings, see Virtual network configuration reference.

Routing

• A load-balanced public IP address (VIP) is reserved to provide access to the API Management endpoints and resources outside the VNet.
  • The public VIP can be found on the Overview/Essentials blade in the Azure portal.

For more information and considerations, see IP addresses of Azure API Management.

VIP and DIP addresses

Dynamic IP (DIP) addresses will be assigned to each underlying virtual machine in the service and used to access endpoints and resources in the VNet and in peered VNets. The API Management service's public virtual IP (VIP) address will be used to access public-facing resources.

If IP restriction lists secure resources within the VNet or peered VNets, we recommend specifying the entire subnet range where the API Management service is deployed to grant or restrict access from the service.

Learn more about the recommended subnet size.

Force tunnel traffic to on-premises firewall using ExpressRoute or network virtual appliance

Forced tunneling lets you redirect or "force" all internet-bound traffic from your subnet back to on-premises for inspection and auditing. Commonly, you configure and define your own default route (0.0.0.0/0), forcing all traffic from the API Management subnet to flow through an on-premises firewall or to a network virtual appliance. This traffic flow breaks connectivity with API Management, since outbound traffic is either blocked on-premises, or NAT'd to an unrecognizable set of addresses that no longer work with various Azure endpoints. You can solve this issue via the following methods:

• Enable service endpoints on the subnet in which the API Management service is deployed for:

  • Azure SQL (required only in the primary region if the API Management service is deployed to multiple regions)
  • Azure Storage
  • Azure Event Hubs
  • Azure Key Vault (required when API Management is deployed on the stv2 platform)

  By enabling endpoints directly from the API Management subnet to these services, you can use the Azure backbone network, providing optimal routing for service traffic. If you use service endpoints with a force tunneled API Management, traffic for the preceding Azure services isn't force tunneled. However, the other API Management service dependency traffic remains force tunneled. Ensure that your firewall or virtual appliance doesn't block this traffic, or the API Management service may not function properly.

  Note

  We strongly recommend enabling service endpoints directly from the API Management subnet to dependent services such as Azure SQL and Azure Storage that support them. However, some organizations may have requirements to force tunnel all traffic from the API Management subnet. In this case, ensure that you configure your firewall or virtual appliance to allow this traffic. You will need to allow the complete IP address range of each dependent service, and keep this configuration up to date when the Azure infrastructure changes. Your API Management service may also experience latency or unexpected timeouts because of the force tunneling of this network traffic.

• All the control plane traffic from the internet to the management endpoint of your API Management service is routed through a specific set of inbound IPs, hosted by API Management. When the traffic is force tunneled, the responses won't symmetrically map back to these inbound source IPs and connectivity to the management endpoint is lost. To overcome this limitation, configure user-defined routes (UDRs) for these inbound IPs with next hop type set to "Internet", to steer traffic back to Azure. Configure the ApiManagement service tag, or find the set of inbound IPs for control plane traffic documented in Control plane IP addresses.

  Important

  Control plane IP addresses should be configured for network access rules and routes only when needed in certain networking scenarios. We recommend using the ApiManagement service tag instead of control plane IP addresses to prevent downtime when infrastructure improvements necessitate IP address changes.

  Note

  Allowing API Management management traffic to bypass an on-premises firewall or network virtual appliance isn't considered a significant security risk. The recommended configuration for your API Management subnet allows inbound management traffic on port 3443 only from the set of Azure IP addresses encompassed by the ApiManagement service tag. The recommended UDR configuration is only for the return path of this Azure traffic.

• (External VNet mode) Data plane traffic for clients attempting to reach the API Management gateway and developer portal from the internet will also be dropped by default because of asymmetric routing introduced by forced tunneling. For each client that requires access, configure an explicit UDR with next hop type "Internet" to bypass the firewall or virtual network appliance.

• For other force tunneled API Management service dependencies, resolve the hostname and reach out to the endpoint. These include:

  • Metrics and Health Monitoring
  • Azure portal diagnostics
  • SMTP relay
  • Developer portal CAPTCHA
  • Azure KMS server

For more information, see Virtual network configuration reference.

Common network configuration issues

This section has moved. See Virtual network configuration reference.

Troubleshooting

• Unsuccessful initial deployment of API Management service into a subnet
  • Deploy a virtual machine into the same subnet.
  • Connect to the virtual machine and validate connectivity to one of each of the following resources in your Azure subscription:
    • Azure Storage blob
    • Azure SQL Database
    • Azure Storage Table
    • Azure Key Vault

• Verify network connectivity status

  • After deploying API Management into the subnet, use the portal to check the connectivity of your instance to dependencies, such as Azure Storage.
  • In the portal, in the left-hand menu, under Deployment and infrastructure, select Network connectivity status.

  

  Filter	Description
  Required	Select to review the required Azure services connectivity for API Management. Failure indicates that the instance is unable to perform core operations to manage APIs.
  Optional	Select to review the optional services connectivity. Failure indicates only that the specific functionality will not work (for example, SMTP). Failure may lead to degradation in using and monitoring the API Management instance and providing the committed SLA.

  To address connectivity issues, review network configuration settings and fix required network settings.

• Incremental updates
  When making changes to your network, refer to NetworkStatus API to verify that the API Management service has not lost access to critical resources. The connectivity status should be updated every 15 minutes.

  To apply a network configuration change to the API Management instance using the portal:

  1. In the left-hand menu for your instance, under Deployment and infrastructure, select Virtual network.
  2. Select Apply network configuration.

• Resource navigation links
  An APIM instance hosted on the compute platform, when deployed into a Resource Manager VNET subnet, reserves the subnet by creating a resource navigation link. If the subnet already contains a resource from a different provider, deployment will fail. Similarly, when you delete an API Management service, or move it to a different subnet, the resource navigation link will be removed.

Next steps

Learn more about:

• Virtual network configuration reference
• Connecting a virtual network to backend using VPN Gateway
• Connecting a virtual network from different deployment models
• Debug your APIs using request tracing
• Virtual Network frequently asked questions
• Service tags