all Technical posts

Running Azure API Management anywhere with Azure Arc for API Management

Microsoft announced the public preview of Azure Arc for API Management which allows you to run a self-hosted API gateway, manageable from Azure. Here are our findings!


Today, during Ignite, Microsoft publicly announced the public preview of Azure Arc for API Management which allows you to run a self-hosted API gateway, manageable from Azure.

Codit has had the privilege to join the private preview and experiment with it, here are our findings!

What is it?

Until now an Azure API Management gateway was always hosted in the Azure cloud as a managed service, but there were no options to take an API Management gateway and host it somewhere else.

This changes today with Azure Arc for API Management, a self-hosted Azure API management gateway (referred further to as self-hosted gateway as from now on), a self-hosted gateway that is a fully functional API Management gateway packed inside a docker container allowing you to run it anywhere you want.

Every self-hosted instance is managed from within the cloud as they are federated with a managed gateway in Azure. Due to this federation with the managed gateway, a self-hosted gateway can also be referred to as a federated gateway.

A gateway in Azure API management resembles a logical gateway of which you can deploy multiple nodes where you want.

The image below illustrates a setup with a single node:

It’s important to mention that the self-hosted gateway only brings the gateway capabilities while the management & development portal still live in Microsoft Azure.


  • Runs on any cloud, hybrid or on-premises – The self-hosted gateway, which is a full equivalent to a managed gateway, is packaged as a docker container meaning you can run it anywhere.
  • Consistent API Experience –  Azure Arc for API Management enables companies to provide APIs consistently to their consumers. A win-win-win scenario for API consumers, operations and developer teams.
  • Federated with API Management in the cloud – The self-hosted gateway will automatically pull down any new configuration deployed to the managed gateway in Azure and push its telemetry up. No inbound ports required, only outbound and no local storage required to maintain configuration data.
  • Improved developer experience – It’s not the main reason why the self-hosted gateway was made but being able to clone an API, configure the API on a local self-hosted gateway and develop and test policies locally without interfering with other team members is definitely a nice bonus.

Shared responsibilities

Self-hosting a gateway also means taking away some responsibilities from Microsoft into your own hands. Let’s have a look at the overview below to get an idea on the separation of responsibilities:

Microsoft Self-hosted gateway user
·       Management plane SLA ·       Gateway hosting
·       Gateway maintenance ·       Network configuration
·       Gateway updates ·       Gateway SLA
·       Keeping gateway up-to-date
·       Providing diagnostics data to support


For example: Azure will not be able to update your self-hosted gateway this is now the responsibility of the party hosting the self-hosted gateway.

We highly recommend API Management customers only to use Azure Arc for API Management if they cannot use Microsoft Azure as it brings a lot of responsibilities that have to be justified.

Creating and running a self-hosted gateway

let’s walk through the creation of a self-hosted gateway.

  • To create a self-hosted gateway, navigate to your API Management instance and search for ‘Gateways’:

  • Press ‘Add’, and you’ll be prompted for a Name, Region and Description for your gateway, note that the Region has nothing to do with Azure Regions, its just a reference to a location that should be meaningful to where the self-hosted gateway is deployed.

    Note that it’s possible to specify a number of API’s that automatically should be deployed to the gateway upon creation. We’ll come back to the configuration of API’s on the gateway in a later stage in this blogpost.
  • After completing the step you’ll see that the newly created gateway pops up in the gateway overview:

  • By clicking on the newly created gateway returns an overview page similar to Azure-based gateways in terms of operations such as request duration:

  • The gateway naturally has a ‘0 node(s)’ Status as we haven’t deployed any instance of the gateway yet. You can easily deploy an instance for this gateway by navigating to ‘Deployment’ which will guide you through the process:

  • To run an instance you’ll need to configure it via an environment file to tell it where the Azure API Management instance is located and register itself:
    1. config.service.endpoint – Configuration endpoint of your Azure API Management instance.
    2. config.service.auth – Token used to register the gateway in you Azure API Management instance.

You can easily download the environment file from the portal by clicking on the ‘env.conf’ link, navigate to the directory containing the environment file and run the docker command specified in the Azure portal:

After running the container, we can see in the Azure portal that a node has been registered for the self-hosted gateway and its last heartbeat timestamp:

As you can see setting up a self-hosted gateway is straight forward.

Using the self-hosted gateway

Now that we’ve created a self-hosted gateway, let’s start using it. Let’s create an API and deploy it to the gateway, in this sample we’ll be proxying a cat facts API which will return a random cat fact when you call it.

Note that the HTTP URL scheme is selected in the configuration above, I don’t have a FQDN with certificate for my local self-hosted gateway, so HTTPS is not an option. After creating the API, let’s add the GET operation to retrieve that fact:

Now that we have proxied the fact endpoint, let’s call the endpoint through API Management:

Great, it works! Configuring the cat facts API on the gateway can easily be done from the gateway configuration page:

Now let’s perform the same call as performed against the management API management instance bug against the IP address of the self-hosted gateway:

Another interesting cat fact proving the self-hosted gateway is functioning as expected!

If you’ve worked with API Management before you probably know that policies are a very powerful feature of Azure API Management. As a self-hosted gateway has all APIM capabilities policies are naturally also executed on the self-hosted gateway instance.

You can easily test this by configuring the policy below on the ‘Get – Fact’ operation:

The policy will verify if the request is performed against the Azure API Management instance and if so, rate limit the calls by IP address. Don’t forget to update the condition with your API Management instance name if you’re giving this a try.

Using the policy, the self-hosted gateway should be able to perform unlimited calls, but the API Management instance should be limited. Giving this a try this yields the expected result:

Self-hosted gateway logging capabilities

Another powerful feature of Azure API Management is its out of the box metrics and analytics capabilities, let’s see how this extends to the self-hosted gateways.

Let’s start with verifying the logs of the docker container running the self-hosted gateway using the command ‘docker logs <containername> -f’.

At container startup logging indicates the loading of configuration from the managed gateway in Azure and building of its internal routing table:

Performing an update on the cat-facts API in the managed gateway in Azure triggers an immediate update on the local self-hosted gateway:

calling the cat facts endpoint yields the logs below:

While these logs certainly are useful while developing or troubleshooting, they don’t provide any insights in a structured way. On the other hand, that’s to be expected of docker console logs, so let’s see what’s available in the managed gateway in Azure.

API Management’s Analytics feature provides some great out of the box insights on you API usage, yet it doesn’t seem to collect any data for API’s on a self-hosted gateway:

This is something that hopefully changes in the future as these analytics provide considerable out-of-the-box added value.

What however is available are events in the Application Instance resource linked to the Azure managed gateway:

As these events have custom properties containing the self-hosted gateway region its definitely possible to run queries on the data to abstract more useful insights regarding gateway usage:

What we’d like to see

Getting to know the self-hosted gateway a few features come up that we’d like to see in future as it matures:

  • API Landscape Map – A visual representation of all the gateways, APIs and products would help give an overview of our API landscape and how everything relates to each other.
  • Azure Monitor integration – One of the best things of the self-hosted gateway is its federation with the management API Management instance in Azure. This allows control of your API facades in a unified way simplifying the management and development process of APIs in a company. A key aspect is of course also monitoring, if would be nice to see extensive integration of the gateway metrics into Azure monitor so the monitoring aspect of non-Azure APIs can also be managed from within Azure.
  • Self-hosted Developer portal – Currently it’s only possible to self-host the gateway, the developer portal remains in Azure. Allowing the developer portal to also be self-hosted in a non-Azure environment makes sense as API documentation and the API itself belong together.
  • Self-hosted gateway API only – At the time or writing one has to make an API available in the management API Management instance in Azure before being able to deploy it to a self-hosted gateway. As there are definitely scenario’s where the facade in Azure won’t have an API in the backend but this will be gateway only API it would make sense to disable the facade in the Azure API Management instance.
  • Granular control on named values – By default all named values are available on all gateways. Being able to configure to what gateways the values apply would be an added value.


Azure Arc for API Management is another example of the industries shift to a cloud-anywhere approach. It’s good to see that Microsoft is investing in solutions that will run outside of their proprietary data center as well.

There’s a vast number of reasons why a cloud approach isn’t the solution for every problem, latency for example, and we can expect further advances from Microsoft in this area.

Nevertheless, a self-hosted approach brings a number of responsibilities with it that should be avoided, if possible, in favor of cloud-first approach.

Thanks for reading,

Subscribe to our RSS feed

Hi there,
how can we help?

Got a project in mind?

Connect with us

Let's talk

Let's talk

Thanks, we'll be in touch soon!

Call us

Thanks, we've sent the link to your inbox

Invalid email address


Your download should start shortly!

Stay in Touch - Subscribe to Our Newsletter

Keep up to date with industry trends, events and the latest customer stories

Invalid email address


Great you’re on the list!