Self-hosted gateway overview
Availability
Important
This feature is available in the Premium and Developer tiers of API Management.
The self-hosted gateway is an optional, containerized version of the default managed gateway included in every API Management service. It's useful for scenarios such as placing gateways in the same environments where you host your APIs. Use the self-hosted gateway to improve API traffic flow and address API security and compliance requirements.
This article explains how the self-hosted gateway feature of Azure API Management enables hybrid and multicloud API management, presents its high-level architecture, and highlights its capabilities.
For an overview of the features across the various gateway offerings, see API gateway in API Management.
Hybrid and multicloud API management
The self-hosted gateway feature expands API Management support for hybrid and multicloud environments and enables organizations to efficiently and securely manage APIs hosted on-premises and across clouds from a single API Management service in Azure.
With the self-hosted gateway, customers have the flexibility to deploy a containerized version of the API Management gateway component to the same environments where they host their APIs. All self-hosted gateways are managed from the API Management service they're federated with, thus providing customers with the visibility and unified management experience across all internal and external APIs.
Each API Management service is composed of the following key components:
- Management plane, exposed as an API, used to configure the service via the Azure portal, PowerShell, and other supported mechanisms.
- Gateway (or data plane), which is responsible for proxying API requests, applying policies, and collecting telemetry
- Developer portal used by developers to discover, learn, and onboard to use the APIs
By default, all these components are deployed in Azure, causing all API traffic (shown as solid black arrows on the following picture) to flow through Azure regardless of where backends implementing the APIs are hosted. The operational simplicity of this model comes at the cost of increased latency, compliance issues, and in some cases, extra data transfer fees.
Deploying self-hosted gateways into the same environments where the backend API implementations are hosted allows API traffic to flow directly to the backend APIs, which reduces latency, optimizes data transfer costs, and enables compliance while retaining the benefits of having a single point of management, observability, and discovery of all APIs within the organization regardless of where their implementations are hosted.
Packaging
The self-hosted gateway is available as a Linux-based Docker container image from the Microsoft Artifact Registry. It can be deployed to Docker, Kubernetes, or any other container orchestration solution running on a server cluster on premises, cloud infrastructure, or for evaluation and development purposes, on a personal computer.
Container images
We provide a variety of container images for self-hosted gateways to meet your needs:
| Tag convention | Recommendation | Example | Rolling tag | Recommended for production |
|---|---|---|---|---|
{major}.{minor}.{patch} |
Use this tag to always run the same version of the gateway | 2.0.0 |
❌ | ✔️ |
v{major} |
Use this tag to always run a major version of the gateway with every new feature and patch. | v2 |
✔️ | ❌ |
v{major}-preview |
Use this tag if you always want to run our latest preview container image. | v2-preview |
✔️ | ❌ |
latest |
Use this tag if you want to evaluate the self-hosted gateway. | latest |
✔️ | ❌ |
beta1 |
Use this tag if you want to evaluate preview versions of the self-hosted gateway. | beta |
✔️ | ❌ |
You can find a full list of available tags here.
1Preview versions aren't officially supported and are for experimental purposes only. See the self-hosted gateway support policies.
Use of tags in our official deployment options
Our deployment options in the Azure portal use the v2 tag that allows customers to use the most recent version of the self-hosted gateway v2 container image with all feature updates and patches.
Note
We provide the command and YAML snippets as reference, feel free to use a more specific tag if you wish to.
When installing with our Helm chart, image tagging is optimized for you. The Helm chart's application version pins the gateway to a given version and doesn't rely on latest.
Learn more on how to install an API Management self-hosted gateway on Kubernetes with Helm.
Risk of using rolling tags
Rolling tags are tags that are potentially updated when a new version of the container image is released. This allows container users to receive updates to the container image without having to update their deployments.
This means that you can potentially run different versions in parallel without noticing it, for example when you perform scaling actions once v2 tag was updated.
Example - v2 tag was released with 2.0.0 container image, but when 2.1.0 will be released, the v2 tag will be linked to the 2.1.0 image.
Important
Consider using a specific version tag in production to avoid unintentional upgrade to a newer version.
Connectivity to Azure
Self-hosted gateways require outbound TCP/IP connectivity to Azure on port 443. Each self-hosted gateway must be associated with a single API Management service and is configured via its management plane. A self-hosted gateway uses connectivity to Azure for:
- Reporting its status by sending heartbeat messages every minute
- Regularly checking for (every 10 seconds) and applying configuration updates whenever they're available
- Sending metrics to Azure Monitor, if configured to do so
- Sending events to Application Insights, if set to do so
Important
Support for Azure API Management self-hosted gateway version 0 and version 1 container images is ending on 1 October 2023, along with its corresponding Configuration API v1. Use our migration guide to use self-hosted gateway v2.0.0 or higher with Configuration API v2. Learn more in our deprecation documentation
FQDN dependencies
To operate properly, each self-hosted gateway needs outbound connectivity on port 443 to the following endpoints associated with its cloud-based API Management instance:
| Description | Required for v1 | Required for v2 | Notes |
|---|---|---|---|
| Hostname of the configuration endpoint | <apim-service-name>.management.azure-api.cn |
<apim-service-name>.configuration.azure-api.cn1 |
Custom hostnames are also supported and can be used instead of the default hostname. |
| Public IP address of the API Management instance | ✔️ | ✔️ | IP address of primary location is sufficient. |
| Public IP addresses of Azure Storage service tag | ✔️ | Optional2 | IP addresses must correspond to primary location of API Management instance. |
| Hostname of Azure Blob Storage account | ✔️ | Optional2 | Account associated with instance (<blob-storage-account-name>.blob.core.chinacloudapi.cn) |
| Hostname of Azure Table Storage account | ✔️ | Optional2 | Account associated with instance (<table-storage-account-name>.table.core.chinacloudapi.cn) |
| Endpoints for Azure Resource Manager | ✔️ | Optional3 | Required endpoints are management.chinacloudapi.cn. |
| Endpoints for Microsoft Entra integration | ✔️ | Optional4 | Required endpoints are <region>.login.microsoft.com and login.partner.microsoftonline.cn. |
| Endpoints for Azure Application Insights integration | Optional5 | Optional5 | Minimal required endpoints are:
|
| Endpoints for Event Hubs integration | Optional5 | Optional5 | Learn more in Azure Event Hubs docs |
| Endpoints for external cache integration | Optional5 | Optional5 | This requirement depends on the external cache that is being used |
1For an API Management instance in an internal virtual network, see Connectivity in an internal virtual network.
2Only required in v2 when API inspector or quotas are used in policies.
3Only required when using Microsoft Entra authentication to verify RBAC permissions.
4Only required when using Microsoft Entra authentication or Microsoft Entra related policies.
5Only required when feature is used and requires public IP address, port, and hostname information.
Important
- DNS hostnames must be resolvable to IP addresses and the corresponding IP addresses must be reachable.
- The associated storage account names are listed in the service's Network connectivity status page in the Azure portal.
- Public IP addresses underlying the associated storage accounts are dynamic and can change without notice.
Connectivity in internal virtual network
Private connectivity - If the self-hosted gateway is deployed in a virtual network, enable private connectivity to the v2 configuration endpoint from the location of the self-hosted gateway, for example, using a private DNS in a peered network.
Internet connectivity - If the self-hosted gateway needs to connect to the v2 configuration endpoint over the internet, configure a custom hostname for the configuration endpoint, and expose the endpoint using Application Gateway.
Authentication options
To authenticate the connection between the self-hosted gateway and the cloud-based API Management instance's configuration endpoint, you have the following options in the gateway container's configuration settings.
| Option | Considerations |
|---|---|
| Microsoft Entra authentication | Configure one or more Microsoft Entra apps for access to gateway Manage access separately per app Configure longer expiry times for secrets in accordance with your organization's policies Use standard Microsoft Entra procedures to assign or revoke user or group permissions to app and to rotate secrets |
| Gateway access token (also called authentication key) | Token expires every 30 days at maximum and must be renewed in the containers Backed by a gateway key that can be rotated independently (for example, to revoke access) Regenerating gateway key invalidates all access tokens created with it |
Connectivity failures
When connectivity to Azure is lost, the self-hosted gateway is unable to receive configuration updates, report its status, or upload telemetry.
The self-hosted gateway is designed to "fail static" and can survive temporary loss of connectivity to Azure. It can be deployed with or without local configuration backup. With configuration backup, self-hosted gateways regularly save a backup copy of the latest downloaded configuration on a persistent volume attached to their container or pod.
When configuration backup is turned off and connectivity to Azure is interrupted:
- Running self-hosted gateways will continue to function using an in-memory copy of the configuration
- Stopped self-hosted gateways won't be able to start
When configuration backup is turned on and connectivity to Azure is interrupted:
- Running self-hosted gateways will continue to function using an in-memory copy of the configuration
- Stopped self-hosted gateways will be able to start using a backup copy of the configuration
When connectivity is restored, each self-hosted gateway affected by the outage will automatically reconnect with its associated API Management service and download all configuration updates that occurred while the gateway was "offline".
Security
Limitations
The following functionality found in the managed gateways is not available in the self-hosted gateways:
- TLS session resumption.
- Client certificate renegotiation. To use client certificate authentication, API consumers must present their certificates as part of the initial TLS handshake. To ensure this behavior, enable the Negotiate Client Certificate setting when configuring a self-hosted gateway custom hostname (domain name).
Transport Layer Security (TLS)
Important
This overview is only applicable to the self-hosted gateway v1 & v2.
Supported protocols
The self-hosted gateway provides support for TLS v1.2 by default.
Customers using custom domains can enable TLS v1.0 and/or v1.1 in the control plane.
Available cipher suites
Important
This overview is only applicable to the self-hosted gateway v2.
The self-hosted gateway uses the following cipher suites for both client and server connections:
TLS_AES_256_GCM_SHA384TLS_CHACHA20_POLY1305_SHA256TLS_AES_128_GCM_SHA256TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384TLS_DHE_RSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256TLS_DHE_RSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384TLS_DHE_RSA_WITH_AES_256_CBC_SHA256TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256TLS_DHE_RSA_WITH_AES_128_CBC_SHA256TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHATLS_ECDHE_RSA_WITH_AES_256_CBC_SHATLS_DHE_RSA_WITH_AES_256_CBC_SHATLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHATLS_ECDHE_RSA_WITH_AES_128_CBC_SHATLS_DHE_RSA_WITH_AES_128_CBC_SHATLS_RSA_WITH_AES_256_GCM_SHA384TLS_RSA_WITH_AES_128_GCM_SHA256TLS_RSA_WITH_AES_256_CBC_SHA256TLS_RSA_WITH_AES_128_CBC_SHA256TLS_RSA_WITH_AES_256_CBC_SHATLS_RSA_WITH_AES_128_CBC_SHA
Managing cipher suites
As of v2.1.1 and above, you can manage the ciphers that are being used through the configuration:
net.server.tls.ciphers.allowed-suitesallows you to define a comma-separated list of ciphers to use for the TLS connection between the API client and the self-hosted gateway.net.client.tls.ciphers.allowed-suitesallows you to define a comma-separated list of ciphers to use for the TLS connection between the self-hosted gateway and the backend.
Next steps
- Learn more about the various gateways in our API gateway overview
- Learn more about the support policy for the self-hosted gateway
- Learn more about API Management in a hybrid and multicloud world
- Learn more about guidance for running the self-hosted gateway on Kubernetes in production
- Deploy self-hosted gateway to Docker
- Deploy self-hosted gateway to Kubernetes
- Deploy self-hosted gateway to Azure Container Apps
- Self-hosted gateway configuration settings
- Learn about observability capabilities in API Management
- Learn about Dapr integration with the self-hosted gateway