Merge pull request #262563 from dlepow/lbback

[APIM] Backend pool

Author: v-regandowner

articles/api-management/api-management-api-import-restrictions.md

@@ -254,6 +254,9 @@ Namespaces other than the target aren't preserved on export. While you can impor
 ### Multiple endpoints
 WSDL files can define multiple services and endpoints (ports) by one or more `wsdl:service` and `wsdl:port` elements. However, the API Management gateway is able to import and proxy requests to only a single service and endpoint. If multiple services or endpoints are defined in the WSDL file, identify the target service name and endpoint when importing the API by using the [wsdlSelector](/rest/api/apimanagement/apis/create-or-update#wsdlselector) property.
 
+> [!TIP]
+> If you want to load-balance requests across multiple services and endpoints, consider configuring a [load-balanced backend pool](backends.md#load-balanced-pool-preview).
+
 ### Arrays 
 SOAP-to-REST transformation supports only wrapped arrays shown in the example below:
 

articles/api-management/backends.md

@@ -1,14 +1,14 @@
 ---
 title: Azure API Management backends | Microsoft Docs
-description: Learn about custom backends in API Management
+description: Learn about custom backends in Azure API Management
 services: api-management
 documentationcenter: ''
 author: dlepow
 editor: ''
 
 ms.service: api-management
 ms.topic: article
-ms.date: 08/16/2023
+ms.date: 01/09/2024
 ms.author: danlep 
 ms.custom:
 ---
@@ -26,9 +26,13 @@ API Management also supports using other Azure resources as an API backend, such
 * A [Service Fabric cluster](how-to-configure-service-fabric-backend.md).
 * A custom service. 
 
-API Management supports custom backends so you can manage the backend services of your API. Use custom backends, for example, to authorize the credentials of requests to the backend service. Configure and manage custom backends in the Azure portal, or using Azure APIs or tools.
+API Management supports custom backends so you can manage the backend services of your API. Use custom backends for one or more of the following:
 
-After creating a backend, you can reference the backend in your APIs. Use the [`set-backend-service`](set-backend-service-policy.md) policy to direct an incoming API request to the custom backend. If you already configured a backend web service for an API, you can use the `set-backend-service` policy to redirect the request to a custom backend instead of the default backend web service configured for that API.
+* Authorize the credentials of requests to the backend service
+* Protect your backend from too many requests
+* Route or load-balance requests to multiple backends
+
+Configure and manage custom backends in the Azure portal, or using Azure APIs or tools.
 
 ## Benefits of backends
 
@@ -38,6 +42,43 @@ A custom backend has several benefits, including:
 * Easily used by configuring a transformation policy on an existing API.
 * Takes advantage of API Management functionality to maintain secrets in Azure Key Vault if [named values](api-management-howto-properties.md) are configured for header or query parameter authentication.
 
+## Reference backend using set-backend-service policy
+
+After creating a backend, you can reference the backend in your APIs. Use the [`set-backend-service`](set-backend-service-policy.md) policy to direct an incoming API request to the custom backend. If you already configured a backend web service for an API, you can use the `set-backend-service` policy to redirect the request to a custom backend instead of the default backend web service configured for that API. For example:
+
+```xml
+<policies>
+    <inbound>
+        <base />
+        <set-backend-service backend-id="myBackend" />
+    </inbound>
+    [...]
+<policies/>
+```
+
+You can use conditional logic with the `set-backend-service` policy to change the effective backend based on location, gateway that was called, or other expressions.
+
+For example, here is a policy to route traffic to another backend based on the gateway that was called:
+
+```xml
+<policies>
+    <inbound>
+        <base />
+        <choose>
+            <when condition="@(context.Deployment.Gateway.Id == "factory-gateway")">
+                <set-backend-service backend-id="backend-on-prem" />
+            </when>
+            <when condition="@(context.Deployment.Gateway.IsManaged == false)">
+                <set-backend-service backend-id="self-hosted-backend" />
+            </when>
+            <otherwise />
+        </choose>
+    </inbound>
+    [...]
+<policies/>
+```
+
+
 ## Circuit breaker (preview)
 
 Starting in API version 2023-03-01 preview, API Management exposes a [circuit breaker](/rest/api/apimanagement/current-preview/backend/create-or-update?tabs=HTTP#backendcircuitbreaker) property in the backend resource to protect a backend service from being overwhelmed by too many requests.
@@ -50,16 +91,15 @@ The backend circuit breaker is an implementation of the [circuit breaker pattern
 
 ### Example
 
-Use the API Management REST API or a Bicep or ARM template to configure a circuit breaker in a backend. In the following example, the circuit breaker trips when there are three or more `5xx` status codes indicating server errors in a day. The circuit breaker resets after one hour.
+Use the API Management [REST API](/rest/api/apimanagement/backend) or a Bicep or ARM template to configure a circuit breaker in a backend. In the following example, the circuit breaker in *myBackend* in the API Management instance *myAPIM* trips when there are three or more `5xx` status codes indicating server errors in a day. The circuit breaker resets after one hour.
 
 #### [Bicep](#tab/bicep)
 
-Include a snippet similar to the following in your Bicep template:
+Include a snippet similar to the following in your Bicep template for a backend resource with a circuit breaker:
 
 ```bicep
 resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-03-01-preview' = {
-  name: 'myBackend'
-  parent: resourceSymbolicName
+  name: 'myAPIM/myBackend'
   properties: {
     url: 'https://mybackend.com'
     protocol: 'http'
@@ -72,7 +112,6 @@ resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-03-01-previ
               'Server errors'
             ]
             interval: 'P1D'
-            percentage: int
             statusCodeRanges: [
               {
                 min: 500
@@ -85,20 +124,19 @@ resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-03-01-previ
         }
       ]
     }
-  }
-[...]
-}
+   }
+ }
 ```
 
 #### [ARM](#tab/arm)
 
-Include a JSON snippet similar to the following in your ARM template:
+Include a JSON snippet similar to the following in your ARM template for a backend resource with a circuit breaker:
 
 ```JSON
 {
   "type": "Microsoft.ApiManagement/service/backends",
   "apiVersion": "2023-03-01-preview",
-  "name": "myBackend",
+  "name": "myAPIM/myBackend",
   "properties": {
     "url": "https://mybackend.com",
     "protocol": "http",
@@ -122,18 +160,88 @@ Include a JSON snippet similar to the following in your ARM template:
       ]
     }
   }
-[...]
 }
 ```
 
 ---
 
+## Load-balanced pool (preview)
+
+Starting in API version 2023-05-01 preview, API Management supports backend *pools*, when you want to implement multiple backends for an API and load-balance requests across those backends. Currently, the backend pool supports round-robin load balancing.
+
+Use a backend pool for scenarios such as the following:
+
+* Spread the load to multiple backends, which may have individual backend circuit breakers.
+* Shift the load from one set of backends to another for upgrade (blue-green deployment).
 
+To create a backend pool, set the `type` property of the backend to `pool` and specify a list of backends that make up the pool.
+
+> [!NOTE]
+> Currently, you can only include single backends in a backend pool. You can't add a backend of type `pool` to another backend pool.
+
+### Example
+
+Use the API Management [REST API](/rest/api/apimanagement/backend) or a Bicep or ARM template to configure a backend pool. In the following example, the backend *myBackendPool* in the API Management instance *myAPIM* is configured with a backend pool. Example backends in the pool are named *backend-1* and *backend-2*. 
+
+#### [Bicep](#tab/bicep)
+
+Include a snippet similar to the following in your Bicep template for a backend resource with a load-balanced pool:
+
+```bicep
+resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-05-01-preview' = {
+  name: 'myAPIM/myBackendPool'
+  properties: {
+    description: 'Load balancer for multiple backends'
+    type: 'Pool'
+    protocol: 'http'
+    url: 'http://unused'
+    pool: {
+      services: [
+        {
+          id: '/backends/backend-1'
+        }
+        {
+          id: '/backends/backend-2'
+        }
+      ]
+    }
+  }
+}
+```
+#### [ARM](#tab/arm)
+
+Include a JSON snippet similar to the following in your ARM template for a backend resource with a load-balanced pool:
+
+```json
+{
+  "type": "Microsoft.ApiManagement/service/backends",
+  "apiVersion": "2023-05-01-preview",
+  "name": "myAPIM/myBackendPool",
+  "properties": {
+    "description": "Load balancer for multiple backends",
+    "type": "Pool",
+    "protocol": "http",
+    "url": "http://unused",
+    "pool": {
+      "services": [
+        {
+          "id": "/backends/backend-1"
+        },
+        {
+          "id": "/backends/backend-2"
+        }
+      ]
+    }
+  }
+}
+```
+
+---
 ## Limitation
 
 For **Developer** and **Premium** tiers, an API Management instance deployed in an [internal virtual network](api-management-using-with-internal-vnet.md) can throw HTTP 500 `BackendConnectionFailure` errors when the gateway endpoint URL and backend URL are the same. If you encounter this limitation, follow the instructions in the [Self-Chained API Management request limitation in internal virtual network mode](https://techcommunity.microsoft.com/t5/azure-paas-blog/self-chained-apim-request-limitation-in-internal-virtual-network/ba-p/1940417) article in the Tech Community blog. 
 
-## Next steps
+## Related content
 
 * Set up a [Service Fabric backend](how-to-configure-service-fabric-backend.md) using the Azure portal.
-* Backends can also be configured using the API Management [REST API](/rest/api/apimanagement), [Azure PowerShell](/powershell/module/az.apimanagement/new-azapimanagementbackend), or [Azure Resource Manager templates](../service-fabric/service-fabric-tutorial-deploy-api-management.md).
+