Shortly after Microsoft acquired Apiphany, which we know as Azure API Management today, I was working at a customer with Apigee, which is owned by Google today. Back then, Apigee was way ahead of APIM in functionality and one of the interesting parts was their Edge microgateway which could be installed on any device.

At the London conference Integrate 2019 Microsoft announced they were working on a similar thing and in April this year Microsoft GA-ed the Self-Hosted Gateway.

Let's have a look at what it is and what we can do with it.

What problem does it solve?

The scenario of having all your API's configured and managed centrally in the cloud is very convenient: all your cloud, on-prem and 3rd party based API's can be accessed via this one cloud endpoint. Consumers from anywhere in the world can easily access the functionality you expose.

Centralized management in this case also means all traffice from and to the API's need to pass through Azure. What about the scenario where your API's live somewhere else? A different cloud provider or on-prem?

How about the scenario where you still want to take advantage of centralized API management, but both your API's and client apps are in your on-prem data center. Every call from your client app in-your-data-center to your API in-your-data-center needs to go via Azure, meaning a round trip to the cloud to access the API's running on the on-prem server next to the one serving your client app. This introduces unnecessary latency, but also security risks as you have to expose your API's to the cloud to make them accessible from APIM. In some cases that's not even allowed by the security officer, as there is no business value in routing your calls through Azure.

The idea of the self-hosted gateway is to install a request handler close to where the API's live.

One solution is to install an API management product in your data center, but if you happen to find one suitable for you, it's features most probably will be behind as vendors often have a cloud-first approach. The on-prem setup Microsoft provides with Azure Stack never even contained APIM, and with the introduction of the self-hosted gateway this makes sense now.

The Self-hosted gateway can be installed in your data center and still use the configuration from the cloud. Your client apps can be configured to use the local endpoint while you still have the benefits of centralized API management.

How does it work?

The simple answer is you install the self-hosted gateway docker container on-prem or at the other cloud provider, configure it to connect it to your APIM instance in Azure and you can start using your APIM local address to access API's. Configuration in the self-hosted gateway is updated every 10 seconds, and if the connection is lost it remains working. Telemetry data is uploaded to APIM so it shows up on your dashboard and Application Insights instance.

As you might know APIM consists of tree parts: Management plane, Gateway and Developer portal. It's important to understand only the Gateway part runs as self-hosted solution.

The more detailed answer is that the self-hosted gateway is a Linux based docker image. You can run that directly on Docker for dev/test purposes or run on a Kubernetes cluster more suitable for production setups. The container only uses an outbound connection to APIM, thus no ports need to be opened for this to work. It stores the configuration in memory, so when the connection to Azure is dropped it continues to work. However when the docker engine restarts, the configuration is lost. To make sure a pod restart can be survived, it is possible to add persistent file storage to the container. To speed up performance you can add external cache.

The advantages of the self-hosted gateway are clear, but there are also disadvantages.

• One of the main ones is it adds maintenance load on your IT department: they need to maintain, update and monitor the container as there is obviously no SLA from Microsoft side on your data center.
• The self-hosted gateway option is only available as part of the Premium plan

Setting up a self-hosted gateway

For this to work, APIM and the remote self-hosted gateway need to communicate with each other. This means we have to prepare APIM on one side and setup the self-hosted gateway in Docker on the other side. This is remarkably simple.

Setup APIM

Add a local gateway in APIM and specify which of your API's are accessible via the self-hosted gateway.

After the self-hosted gateway is created, you'll see an overview of all self-hosted gateways available. The number of nodes is the number of connected local gateways running in Docker or Kubernetes, currently none.

Click on the gateway to get an overview with graphs similar to what you see on the main APIM overview page. You can see here which API's are accessible via the local gateway and configure a custom host name.

The interesting part is the deployment section. Here you find the configuration you need in order to setup the Docker container locally to run the self-hosted gateway.

In the Docker part at the bottom of the deployment section, there is Run and Environment information. Click the link env.conf to download the environment settings, you'll need it to configure the Docker container. Copy the Docker Run... command so you have it on the clipboard to be used on your local environment.

This is all you need to do from APIM side, now take a look at the local side of it.

Setup Docker

First of all you need to have Docker running.

Open a terminal, change the directory to where you downloaded the Environment file and paste in the Docker Run... command. This will download and start the Linux image containing the self-hosted gateway from the Docker gallery. With docker ps you can verify the container actually runs.

If everything is setup correctly, then on the Azure portal you should be able to see a node is connected.

Testing

That is quite simple to setup, but how does it work?

The test setup was not particularly interesting, as I just use the out-of-the-box Echo API. The call to both gateways work as expected and are return HTTP 200.

The difference in response times between the two can also be explained, as the call via the local gateway first needs to go through the Docker container.

However you can imagine the advantage when your API is not somewhere in the cloud, but in the data center where the self-hosted gateway runs.

Telemetry

When you want to know what is happening in your Docker container, you can use the docker container log command. Please do so, you'll see some awesome ASCII art.

And the logs themselves of course, which can help you diagnose issues.

Application Insights

In Application Insights you'll see the behaviour of all your instances, in Azure or locally. It's very convenient to have all data in the same location, so querying is easy.

Future developments

Early June the yearly Integrate conference was held, where the Microsoft integration related product groups share their latest nieuws. On the road map for the self-hosted gateway is:

• Remote management for self-hosted gateways will be simplification with Microsoft Arc
• Docker setup will allow AD credentials, next to SAS tokens we already have today