Deploy an Azure API Management instance to multiple Azure regions

Availability

Azure API Management supports multi-region deployment, which enables API publishers to add regional API gateways to an existing API Management instance in one or more supported Azure regions. Multi-region deployment helps reduce request latency perceived by geographically distributed API consumers and improves service availability if one region goes offline.

When adding a region, you configure:

• The number of scale units that region will host.

• Optional availability zones, if that region supports it.

• Virtual network settings in the added region, if networking is configured in the existing region or regions.

About multi-region deployment

• With multi-region deployment, only the gateway component of your API Management instance is replicated to multiple regions. The instance's management plane and developer portal remain hosted only in the primary region, the region where you originally deployed the service.

• Gateway configurations such as APIs and policy definitions are regularly synchronized between the primary and secondary regions you add. Multi-region deployment provides availability of the API gateway in more than one region and provides service availability if one region goes offline.

• When API Management receives public HTTP requests to the primary gateway endpoint, traffic is routed to a regional gateway based on lowest latency, which can reduce latency experienced by geographically distributed API consumers.

• If a region goes offline, API requests are automatically routed around the failed region to the next closest gateway.

• If the primary region goes offline, the API Management management plane and developer portal become unavailable, but secondary regions continue to serve API requests using the most recent gateway configuration.

Prerequisites

• If you haven't created an API Management service instance, see Create an API Management service instance. Select the Premium service tier.
• If your API Management instance is deployed in a virtual network, ensure that you set up a virtual network and subnet in the location that you plan to add, and within the same subscription. See virtual network prerequisites.

Deploy API Management service to an additional region

1. In the Azure portal, navigate to your API Management service and select Locations from the left menu.
2. Select + Add in the top bar.
3. Select the added location from the dropdown list.
4. Select the number of scale Units in the location.
5. Optionally select one or more Availability zones.
6. If the API Management instance is deployed in a virtual network, configure virtual network settings in the location, including virtual network, subnet, and public IP address (if enabling availability zones).
7. Select Add to confirm.
8. Repeat this process until you configure all locations.
9. Select Save in the top bar to start the deployment process.

Remove an API Management service region

1. In the Azure portal, navigate to your API Management service and select Locations from the left menu.
2. For the location you would like to remove, select the context menu using the ... button at the right end of the table. Select Delete.
3. Confirm the deletion and select Save to apply the changes.

Route API calls to regional backend services

By default, each API routes requests to a single backend service URL. Even if you've configured Azure API Management gateways in various regions, the API gateway will still forward requests to the same backend service, which is deployed in only one region. In this case, the performance gain will come only from responses cached within Azure API Management in a region specific to the request; contacting the backend across the globe may still cause high latency.

To take advantage of geographical distribution of your system, you should have backend services deployed in the same regions as Azure API Management instances. Then, using policies and @(context.Deployment.Region) property, you can route the traffic to local instances of your backend.

1. Navigate to your Azure API Management instance and select APIs from the left menu.

2. Select your desired API.

3. Select Code editor from the arrow dropdown in the Inbound processing.

   

4. Use the set-backend combined with conditional choose policies to construct a proper routing policy in the <inbound> </inbound> section of the file.

   For example, the following XML file would work for China North and China East regions:

   <policies>
       <inbound>
           <base />
           <choose>
               <when condition="@("China North".Equals(context.Deployment.Region, StringComparison.OrdinalIgnoreCase))">
                   <set-backend-service base-url="http://contoso-backend-us.com/" />
               </when>
               <when condition="@("China East".Equals(context.Deployment.Region, StringComparison.OrdinalIgnoreCase))">
                   <set-backend-service base-url="http://contoso-backend-asia.com/" />
               </when>
               <otherwise>
                   <set-backend-service base-url="http://contoso-backend-other.com/" />
               </otherwise>
           </choose>
       </inbound>
       <backend>
           <base />
       </backend>
       <outbound>
           <base />
       </outbound>
       <on-error>
           <base />
       </on-error>
   </policies>
   

Use Traffic Manager for routing to regional backends

You may also front your backend services with Azure Traffic Manager, direct the API calls to the Traffic Manager, and let it resolve the routing automatically.

• For traffic distribution and failover, we recommend using Traffic Manager with the Geographic routing method. We don't recommend using Traffic Manager with the Weighted routing method with API Management backends.

• For traffic control during maintenance operations, we recommend using the Priority routing method.

Use custom routing to API Management regional gateways

API Management routes the requests to a regional gateway based on the lowest latency. Although it isn't possible to override this setting in API Management, you can use your own Traffic Manager with custom routing rules.

1. Create your own Azure Traffic Manager.
2. If you're using a custom domain, use it with the Traffic Manager instead of the API Management service.
3. Configure the API Management regional endpoints in Traffic Manager. The regional endpoints follow the URL pattern of https://<service-name>-<region>-01.regional.azure-api.cn, for example https://contoso-chinanorth2-01.regional.azure-api.cn.
4. Configure the API Management regional status endpoints in Traffic Manager. The regional status endpoints follow the URL pattern of https://<service-name>-<region>-01.regional.azure-api.cn/status-0123456789abcdef, for example https://contoso-chinaeast-01.regional.azure-api.cn/status-0123456789abcdef.
5. Specify the routing method of the Traffic Manager.

Disable routing to a regional gateway

Under some conditions, you might need to temporarily disable routing to one of the regional gateways. For example:

• After adding a new region, to keep it disabled while you configure and test the regional backend service
• During regular backend maintenance in a region
• To redirect traffic to other regions during a planned disaster recovery drill that simulates an unavailable region, or during a regional failure

To disable routing to a regional gateway in your API Management instance, update the gateway's disableGateway property value to true. You can set the value using the Create or update service REST API, the az apim update command in the Azure CLI, the set-azapimanagement Azure PowerShell cmdlet, or other Azure tools.

To disable a regional gateway using the Azure CLI:

1. Use the az apim show command to show the locations, gateway status, and regional URLs configured for the API Management instance.

   az apim show --name contoso --resource-group apim-hello-world-resource \
       --query "additionalLocations[].{Location:location,Disabled:disableGateway,Url:gatewayRegionalUrl}" \
       --output table
   

   Example output:

   Location    Disabled    Url
   ----------  ----------  ------------------------------------------------------------
   China North 2   True        https://contoso-chinanorth2-01.regional.azure-api.cn
   China North True        https://contoso-chinanorth-01.regional.azure-api.cn
   

2. Use the az apim update command to disable the gateway in an available location, such as China North 2.

   az apim update --name contoso --resource-group apim-hello-world-resource \
   --set additionalLocations[location="China North 2"].disableGateway=true
   

   The update may take a few minutes.

3. Verify that traffic directed to the regional gateway URL is redirected to another region.

To restore routing to the regional gateway, set the value of disableGateway to false.

Virtual networking

This section provides considerations for multi-region deployments when the API Management instance is injected in a virtual network.

• Configure each regional network independently. The connectivity requirements such as required network security group rules for a virtual network in an added region are generally the same as those for a network in the primary region.
• Virtual networks in the different regions don't need to be peered.

IP addresses

• A public virtual IP address is created in every region added with a virtual network. For virtual networks in either external mode or internal mode, this public IP address is used for management traffic on port 3443.

  • External VNet mode - The public IP addresses are also required to route public HTTP traffic to the API gateways.

  • Internal VNet mode - A private IP address is also created in every region added with a virtual network. Use these addresses to connect within the network to the API Management endpoints in the primary and secondary regions.

Routing

• External VNet mode - Routing of public HTTP traffic to the regional gateways is handled automatically, in the same way it is for a non-networked API Management instance.

• Internal VNet mode - Private HTTP traffic isn't routed or load-balanced to the regional gateways by default. Users own the routing and are responsible for bringing their own solution to manage routing and private load balancing across multiple regions.

Next steps

• Learn more about configuring availability zones to improve the availability of an API Management instance in a region.

• For more information about virtual networks and API Management, see:

  • Connect to a virtual network using Azure API Management

  • Connect to a virtual network in internal mode using Azure API Management

  • IP addresses of API Management