Deploy an Azure API Management gateway on Azure Arc (preview)

With the integration between Azure API Management and Azure Arc on Kubernetes, you can deploy the API Management gateway component as an extension in an Azure Arc-enabled Kubernetes cluster.

Deploying the API Management gateway on an Azure Arc-enabled Kubernetes cluster expands API Management support for hybrid and multicloud environments. Enable the deployment using a cluster extension to make managing and applying policies to your Azure Arc-enabled cluster a consistent experience.


API Management self-hosted gateway on Azure Arc is currently in preview. During preview, the API Management gateway extension is available in the following regions:

  • Asia (East, Southeast)
  • Australia (Central, Central 2, East & Southeast)
  • Brazil (South & Southeast)
  • Canada (Central, East)
  • Europe (North, West)
  • France (Central & South)
  • Germany (North & West Central)
  • India (Central, South, West, Jio central & Jio West)
  • Japan (East & West)
  • Korea (Central & South)
  • Norway (East & West)
  • South Africa (North & West)
  • Sweden (Central)
  • Switzerland (North & West)
  • United Arab Emirates (UAE - Central & North)
  • United Kingdom (UK -South)
  • United States (US - Central, Central EUAP, East, East 2, East 2 EUAP, North Central, South Central, West Central, West, West 2, West 3)


You can also deploy the self-hosted gateway directly to Kubernetes.



This feature is available in the Premium and Developer tiers of API Management.


Deploy the API Management gateway extension using Azure CLI

  1. In the Azure portal, navigate to your API Management instance.

  2. Select Gateways from the side navigation menu.

  3. Select and open your provisioned gateway resource from the list.

  4. In your provisioned gateway resource, click Deployment from the side navigation menu.

  5. Make note of the Token and Configuration URL values for the next step.

  6. In Azure CLI, deploy the gateway extension using the az k8s-extension create command. Fill in the token and configuration URL values.

    az k8s-extension create --cluster-type connectedClusters --cluster-name <cluster-name> \
        --resource-group <rg-name> --name <extension-name> --extension-type Microsoft.ApiManagement.Gateway \
        --scope namespace --target-namespace <namespace> \
        --configuration-settings gateway.configuration.uri='<Configuration URL>' \
        --config-protected-settings gateway.auth.token='<token>' \
        --configuration-settings service.type='LoadBalancer' --release-train preview


    -protected- flag for gateway.auth.token is optional, but recommended.

  7. Verify deployment status using the following CLI command:

    az k8s-extension show --cluster-type connectedClusters --cluster-name <cluster-name> --resource-group <rg-name> --name <extension-name>
  8. Navigate back to the Gateways list to verify the gateway status shows a green check mark with a node count. This status means the deployed self-hosted gateway pods:

    • Are successfully communicating with the API Management service.
    • Have a regular "heartbeat".

Deploy the API Management gateway extension using Azure portal

  1. In the Azure portal, navigate to your Azure Arc-connected cluster.

  2. In the left menu, select Extensions > + Add > API Management gateway (preview).

  3. Select Create.

  4. In the Install API Management gateway window, configure the gateway extension:

    • Select the subscription and resource group for your API Management instance.
    • In Gateway details, select the API Management instance and Gateway name. Enter a Namespace scope for your extension and optionally a number of Replicas, if supported in your API Management service tier.
    • In Kubernetes configuration, select the default configuration or a different configuration for your cluster. For options, see available extension configurations.

    Screenshot of deploying the extension in Azure portal

  5. On the Monitoring tab, optionally enable monitoring to upload metrics tracking requests to the gateway and backend. If enabled, select an existing Log Analytics workspace.

  6. Select Review + install and then Install.

Available extension configurations

The self-hosted gateway extension for Azure Arc provides many configuration settings to customize the extension for your environment. This section lists required deployment settings and optional settings for integration with Log Analytics. For a complete list of settings, see the self-hosted gateway extension reference.

Required settings

The following extension configurations are required.

Setting Description
gateway.configuration.uri Configuration endpoint in API Management service for the self-hosted gateway.
gateway.auth.token Gateway token (authentication key) to authenticate to API Management service. Typically starts with GatewayKey.
service.type Kubernetes service configuration for the gateway: LoadBalancer, NodePort, or ClusterIP.

Log Analytics settings

To enable monitoring of the self-hosted gateway, configure the following Log Analytics settings:

Setting Description
monitoring.customResourceId Azure Resource Manager resource ID for the API Management instance.
monitoring.workspaceId Workspace ID of Log Analytics.
monitoring.ingestionKey Secret with ingestion key from Log Analytics.


If you haven't enabled Log Analytics:

  1. Walk through the Create a Log Analytics workspace quickstart.
  2. Learn where to find the Log Analytics agent settings.

Next Steps