Set up a Service Fabric backend in API Management using the Azure portal

This article shows how to configure a Service Fabric service as a custom API backend using the Azure portal. For demonstration purposes, it shows how to set up a basic stateless ASP.NET Core Reliable Service as the Service Fabric backend.

For background, see Backends in API Management.

Prerequisites

Prerequisites to configure a sample service in a Service Fabric cluster running Windows as a custom backend:

• Windows development environment - Install Visual Studio 2019 and the Azure development, ASP.NET and web development, and .NET Core cross-platform development workloads. Then set up a .NET development environment.

• Service Fabric cluster - See Tutorial: Deploy a Service Fabric cluster running Windows into an Azure virtual network. You can create a cluster with an existing X.509 certificate or for test purposes create a new, self-signed certificate. The cluster is created in a virtual network.

• Sample Service Fabric app - Create a Web API app and deploy to the Service Fabric cluster as described in Integrate API Management with Service Fabric in Azure.

  These steps create a basic stateless ASP.NET Core Reliable Service using the default Web API project template. Later, you expose the HTTP endpoint for this service through Azure API Management.

  Take note of the application name, for example fabric:/myApplication/myService.

• API Management instance - An existing or new API Management instance in the Premium or Developer tier and in the same region as the Service Fabric cluster. If you need one, create an API Management instance.

• Virtual network - Add your API Management instance to the virtual network you created for your Service Fabric cluster. API Management requires a dedicated subnet in the virtual network.

  For steps to enable virtual network connectivity for the API Management instance, see How to use Azure API Management with virtual networks.

Create backend - portal

Add Service Fabric cluster certificate to API Management

The Service Fabric cluster certificate is stored and managed in an Azure key vault associated with the cluster. Add this certificate to your API Management instance as a client certificate.

For steps to add a certificate to your API Management instance, see How to secure backend services using client certificate authentication in Azure API Management.

Add Service Fabric backend

1. In the Azure portal, navigate to your API Management instance.
2. Under APIs, select Backends > + Add.
3. Enter a backend name and an optional description
4. In Type, select Service Fabric.
5. In Runtime URL, enter the name of the Service Fabric backend service that API Management will forward requests to. Example: fabric:/myApplication/myService.
6. In Maximum number of partition resolution retries, enter a number between 0 and 10.
7. Enter the management endpoint of the Service Fabric cluster. This endpoint is the URL of the cluster on port 19080, for example, https://mysfcluster.chinanorth.chinacloudapp.cn:19080.
8. In Client certificate, select the Service Fabric cluster certificate you added to your API Management instance in the previous section.
9. In Management endpoint authorization method, enter a thumbprint or server X509 name of a certificate used by the Service Fabric cluster management service for TLS communication.
10. Enable the Validate certificate chain and Validate certificate name settings.
11. In Authorization credentials, provide credentials, if necessary, to reach the configured backend service in Service Fabric. For the sample app used in this scenario, authorization credentials aren't needed.
12. Select Create.

Use the backend

To use a custom backend, reference it using the set-backend-service policy. This policy transforms the default backend service base URL of an incoming API request to a specified backend, in this case the Service Fabric backend.

The set-backend-service policy can be useful with an existing API to transform an incoming request to a different backend than the one specified in the API settings. For demonstration purposes in this article, create a test API and set the policy to direct API requests to the Service Fabric backend.

Create API

Follow the steps in Add an API manually to create a blank API.

• In the API settings, leave the Web service URL blank.

• Add an API URL suffix, such as fabric.

  

Add GET operation to the API

As shown in Deploy a Service Fabric back-end service, the sample ASP.NET Core service deployed on the Service Fabric cluster supports a single HTTP GET operation on the URL path /api/values.

The default response on that path is a JSON array of two strings:

["value1", "value2"]

To test the integration of API Management with the cluster, add the corresponding GET operation to the API on the path /api/values:

1. Select the API you created in the previous step.

2. Select + Add Operation.

3. In the Frontend window, enter the following values, and select Save.

   Setting	Value
   Display name	Test backend
   URL	GET
   URL	/api/values

   

Configure set-backend-service policy

Add the set-backend-service policy to the test API.

1. On the Design tab, in the Inbound processing section, select the code editor (</>) icon.

2. Position the cursor inside the <inbound> element

3. Add the set-service-backend policy statement.

   • In backend-id, substitute the name of your Service Fabric backend.

   • The sf-resolve-condition is a condition for re-resolving a service location and resending a request. The number of retries was set when configuring the backend. For example:

     <set-backend-service backend-id="mysfbackend" sf-resolve-condition="@(context.LastError?.Reason == "BackendConnectionFailure")"/>
     

4. Select Save.

   

Test backend API

1. On the Test tab, select the GET operation you created in a previous section.
2. Select Send.

When properly configured, the HTTP response shows an HTTP success code and displays the JSON returned from the backend Service Fabric service.

Next steps

• Learn how to configure policies to forward requests to a backend
• Backends can also be configured using the API Management REST API, Azure PowerShell, or Azure Resource Manager templates