Supplemental Information for Self-hosted Gateway v1 & v2 Version

The self-hosted gateway is an optional, containerized version of the default managed gateway included in every API Management service. It allows you to deploy a gateway in a separate environment where to host your APIs, such as on-prem or AKS. For self-hosted gateway general knowledge, you can refer to this APIM self-hosted gateway official document. 

In this article, we will not go over the basic concept and usage scenarios. As the self-hosted gateway v2 was released in early 2022, we will focus on the main differences between v1 and v2, as well as some frequently asked questions that are not mentioned in the official document. 

Section 1: Dependency differences between Self-hosted gateway v1 & v2  

Section 2: APIM self-hosted gateway v2 is backward compatible. 

Section 3: Self-hosted gateway keys 

Section 1: Self-hosted gateway v1 & v2 differences 

1.1 Background: 

Self-hosted gateway and APIM will share the same APIM Gateway configuration file which contains the API definition, gateway settings and corelated configuration. The config file is stored in Azure Storage.  

1.2 What is Management endpoint & Configuration endpoint of APIM: 

• APIM Management endpoint provides the address of the storage endpoint so that the service will know where to get the config file.  
• The APIM Configuration endpoint will pre-download the config file. It provides the gateway config file directly when calling it. 

1.3 How does the self-hosted gateway get/update the gateway config file? 

The self-hosted gateway will regularly get the config file via Management endpoint or Configuration endpoint.  

For a common scenario, the APIM is deployed in an internal VNET while the self-hosted gateway is deployed in the on-prem environment. Below chart shows how the on-prem self-hosted gateway fetch the proxy data. 

For v1 the data fetching workflow is: 

1. Self-hosted gateway sends fetch data request to the management endpoint. 
2. The management endpoint returns the storage endpoint address where the data is stored. 
3. Self-hosted gateway send request to the Storage endpoint. 
4. The Storage/SQL returns the proxy related data.  

For v2, the configuration endpoint can fetch proxy-related data in managed APIM. The v2 self-hosted gateway data fetching workflow is: 

1. Self-hosted gateway sends requests to the configuration endpoint. 
2. The configuration endpoint returns the related data. 

In general:  

• For the v1 self-hosted gateway it has dependency on APIM management endpoint and storage endpoint. 
• For the v2 self-hosted gateway mainly has dependency on configuration endpoint. 

1.4 Network configuration tips: 

Suppose you’ve configured the APIM in an internal VNet. In that case, you’ll know that we need to make sure the connectivity between APIM and management endpoint and its dependencies including storage, SQL … etc.  

Let’s assume that the APIM is in the internal VNET, and the self-hosted gateway is deployed in an on-premises environment, just like the picture shown above. 

Obviously, if the VNET and On-prem Network environment is not linked, the request from the self-hosted gateway to APIM will be an external call. The configuration endpoint and management endpoint will become unreachable. The APIM dependencies running in the Azure Cloud, we need to make sure the connectivity from the self-hosted gateway to its dependencies.  

• For the v1 self-hosted gateway, we can use App GW to expose the internal APIM management endpoint to the public. Don’t forget to unblock the traffic from the self-hosted gateway to bob storage and table storage endpoint, if you have any firewall or NVA configured. You can find details in this FQDN dependencies. 
• For the v2 self-hosted gateway, we need to notice that the configuration endpoint doesn’t support custom domain which indicates that it is not able to be exposed from the application gateway. In such scenario, we could either use VPN gateway/express route to extend your on-prem network to the Azure VNET or we can use v1 self-hosted gateway.  We will support the configuration endpoint custom domain in the future. 

Section 2: APIM self-hosted gateway v2 is backward compatible. 

As configuration endpoint is a new feature, some users may worry about the stability and have this question: ‘If the configuration endpoint is unreachable, will the v2 self-hosted gateway use v1 dependency instead?’ 

The answer is yes, the APIM self-hosted gateway v2 is backward compatible. 

• If config.service.endpoint has the configuration endpoint specified in the env.conf file, then the self-hosted gateway will consider itself as v2 capable only and will continuously send request to APIM configuration endpoint to fetch proxy related data.  

• If config.service.endpoint has management endpoint specified with default host name like ‘https://<service name>. management.azure-api.net/subscriptions/{sub id}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{apim-service-name}?api-version={api-version}’, then the self-hosted gateway will consider itself as both v1 and v2 capable and will send the request to configuration endpoint first. If the configuration endpoint is unreachable, it will fall back to send a request to the management endpoint.
• If config.service.endpoint has management endpoint specified with custom domain like ‘https://AAA.BBB.CCC, then the self-hosted gateway will consider itself as V1 capable only. Self-hosted gateway will then send the request to the management endpoint to fetch data. 

Section 3: Self-hosted gateway keys 

This key is used to access the management endpoint/ configuration endpoint to get the configuration file. 

Regenerating a key will invalidate any gateway tokens created with it. Any active gateways using such tokens will become unable to receive configuration updates. 

Another frequently asked question is where I can be notified that there are any changes or updates for the APIM self-hosted gateway, such as function change, specific version stop supporting?  

Please visit docker hub to check latest version: https://hub.docker.com/_/microsoft-azure-api-management-gateway?tab=description