Deploying an Azure APIM Self-Hosted Gateway
RSS feed
Date: Apr 22, 2021
Tags: azure
Share: Share on Twitter
NOTE: Technology changes fast, so some of the images and/or code in this article maybe be out of date. Feel free to leave a comment if you notice something that needs updating.
When working with APIs, how traffic is routed is a REALLY important topic. Whether it’s for security, latency optimization, performance improvements, or admins are just into that sort of thing, companies often want to have complete control over where and how users access their APIs. While Azure API Management (APIM) offers a great cloud-hosted API management solution, this may present a challenge when local traffic needs to stay in the neighborhood. Luckily, Azure APIM’s provide a self-hosted API gateway to ease the struggle.

Why APIM Self-Hosted Gateway?

Companies implement Azure APIM to control access to their APIs. By implementing subscriptions and products, administrators can ensure every request is authenticated and validated, while protecting their backend system. When those are on-premise, there a number of reasons why a company would want to keep all the traffic within their network. They are:

  • Only internal traffic
    If all traffic to an API is from internal users, it may make sense to keep all the communication within the network. There is little benefit in having calls go out the network to the cloud and back.
  • Reduced bandwidth costs Because most cloud platforms charge for data out of the cloud environment, keeping traffic internal for the duration of the operation can cut down on bandwidth usage significantly.
  • Reduced latency between systems
    Because the client and API are around the corner from each other, there should be a lot less latency between the systems.
  • All traffic stays local and secure
    With all API traffic kept in the network, security concerns are usually mitigated by the existing IT safeguards. This simplifies implementation as APIs and their consumers can operate freely within the confines of the established corporate network.

Enter Azure APIM Self-Hosted Gateways. This feature allows you to provide secure, on-prem API access with cloud-based Azure APIM Management. They are fantastic way to improve internal traffic communication and performance, with all the benefits of a centralized, cloud-hosted management experience. Double win!


For this article, I created the following architecture to demonstrate how/when you may want to use a self-hosted gateway for your Azure APIM service.

The architecture consists of the following main components:

Azure APIM
An Azure APIM service to manage the APIs.

On-Prem API
An API running on-prem (local) on the corporate network that returns the current time when a request is made to it.

Azure APIM Self-Hosted Gateway

This is the on-prem container image deployed within the network.

Azure APIM API Registration

The registration for the API within the Azure APIM service. Note that the URL for the API is configured to be an internal IP.

On-Prem user

Our internal developer that just wants to do his job and doesn’t care about where/how the API is managed.

Communication Flow

The desired communication would be:

  1. Internal user makes a request to the self-hosted (on-prem) gateway for an internal API.
  2. The self-hosted gateway applies the Azure APIM-provided configuration to request (request throttling, inbound policies, etc.).
  3. The request is sent tot internal API, keeping all communication within the network.

Now, let me show you how to implement a self-hosted gateway…

Create Self-Hosted Gateway

The first step is to create my self-hosted gateway within the Azure APIM service.


The following link provides a tutorial for creating the self-hosted gateway:

Provision a self-hosted gateway in Azure API Management | Microsoft Docs

In the APIM service, I select the Gateways option.

I assign a name and location for the gateway and select the API(s) to associate.


An API can be associated with multiple gateways (Azure, self-hosted, etc.). The required traffic patterns and routing will determine the best setup for the environment.  It’s entirely possible to have an API associated with both a self-hosted gateway and an Azure APIM gateway.

Once the gateway is created, I select the Deployment tab to see the connection details. Azure APIM provides Docker and Kubernetes commands to help you use the new container image in your environment.

Deploy Docker image

Azure APIM self-hosted gateways leverage a pre-configured container image. Included with this is an env.conf file that contains the specifics for your Azure APIM service and subscription.

I download env.conf file and review the supplied Docker command. Because I am running the image in Docker Desktop on my machine, I update my port mappings to work in my local environment.

docker run -d -p 1111:8080 -p 2222:8081 --name BSoltisDemoGateway --env-file env.conf

With the command successfully executed, I confirm the Docker container was created and running, using Docker Desktop.

I open the Logs for the new image. The logs will be used in testing the environment.


With the gateway created and running, I am ready to test the solution. Because I am simulating “local” traffic, I execute a request to local IP for the self-hosted gateway and confirm the response.

In the Docker Desktop Logs, I confirm the request is logged within the gateway container.

Lastly, I confirm the request is logged with in the Azure APIM service.

Because the self-hosted gateway maintains a connection to Azure APIM, all requests/traffic can be logged to Azure, while all traffic to the API is kept internal.

Important Stuff

While Azure APIM Self-Hosted Gateways are extremely powerful components, there are few important aspects developers should note:

  • Only available in Developer / Premium
    Currently, only the Azure APIM Developer and Premium tiers support self-hosted gateways. Ensure you have the proper tier selected before implementing.
  • Manual image updates
    With self-hosted gateways being based on a pre-configured Docker image, all updates to the gateways will be a manual process for administrators. Microsoft will make new container images available as they are updated. Administrators will need to define the update process for their on-prem gateways to leverage new images.
  • Gateways need Azure 443 connectivity
    In order to function, self-hosted gateways require a constant connection to the Azure APIM service over port 443. The gateway will attempt a connection every 10 seconds. This is to ensure the gateway is kept up to date, as the configuration is still being managed with the Azure APIM service.
  • Self-Hosted Gateways will not turn without Azure APIM connectivity
    If a self-hosted gateway loses connection, any running gateway will continue to function. If a gateway is shut down/powered on, it will not function until a connection to the Azure APIM service is restored. This helps ensure all traffic to the managed APIs is executed per your specifications and the gateways have the latest configuration applied.

What’s next?

OK, hopefully that was pretty awesome information to learn. I’m continually impressed with how much can be accomplished with Azure APIM and the multitude of ways they can be leveraged. Now that you know what Azure APIM self-hosted gateways are and how you may use them, you may wonder what comes next?

  • Deploy to Kubernetes In my demo, I deployed a gateway to Docker for a single node. Azure APIM also supports deploying to Kubernetes, where multiple replicas can be created for a redundant, highly available solution.
  • Regional deployments
    Organizations often have several locations, with APIs dispersed across them. With self-hosted gateways, each location can have their own gateway(s) to provide the optimal experience for each user in that region.
  • Config file updates
    The env.conf contains the necessary Azure APIM service information for management. This file can also be updated with your own variables and configurations. This allows to you further customize the gateway to fit your environment.
  • Internal / External Traffic
    APIs managed with Azure APIM can handle both internal and external traffic. Internal traffic may use a self-hosted gateway for faster performance/security, while external users can access the same API via the Azure APIM URL. In both cases, the API can continue to be managed from the single Azure APIM.
  • Similar to Azure APIM gateways, but not 100%
    Self-hosted provide flexibility to developers, but not every feature found on the cloud-hosted options. Be sure to review the documentation on what features are not included.
  • Support for Dapr!
    Dapr opens a new way for microservice development for users who often want to set up implementation across several environments. Self-hosted gateways allow Dapr traffic to routed internally and still leverage Azure APIM.

Moving forward

Azure APIM continues to be one of my favorite parts of the Azure platform. With so many customization and integrations options, organizations can leverage these powerful Azure services for a variety of architectures and applications. Self-hosted gateways help improve performance, while ensuring secure and efficient API traffic. Be sure to check out the links below to read up on the latest Azure APIM features and how self-hosted gateways can empower your developers. Good luck!

Learn More