Edit

Self-hosted gateway migration guide

  • Article

APPLIES TO: Developer | Premium

This article explains how to migrate existing self-hosted gateway deployments to self-hosted gateway v2.

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. Learn more in our deprecation documentation

What's new?

As we strive to make it easier for customers to deploy our self-hosted gateway, we've introduced a new configuration API that removes the dependency on Azure Storage, unless you're using API inspector or quotas.

The new configuration API allows customers to more easily adopt, deploy and operate our self-hosted gateway in their existing infrastructure.

We have introduced new container image tags to let customers choose the best way to try our gateway and deploy it in production.

To help customers run our gateway in production we've extended our production guidance to cover how to autoscale the gateway, and deploy it for high availability in your Kubernetes cluster.

Learn more about the connectivity of our gateway, our new infrastructure requirements, and what happens if connectivity is lost in this article.

Prerequisites

Before you can migrate to self-hosted gateway v2, you need to ensure your infrastructure meets the requirements.

Migrating to self-hosted gateway v2

Migrating from self-hosted gateway v2 requires a few small steps to be done:

  1. Use the new container image
  2. Use the new configuration API
  3. Meet minimal security requirements

Container Image

Change the image tag in your deployment scripts to use 2.0.0 or above.

Alternatively, choose one of our other container image tags.

You can find a full list of available tags here or find us on Docker Hub.

Using the new configuration API

In order to migrate to self-hosted gateway v2, customers need to use our new Configuration API v2.

Currently, Azure API Management provides the following Configuration APIs for self-hosted gateway:

Configuration Service URL Supported Requirements
v2 {name}.configuration.azure-api.net Yes Link
v1 {name}.management.azure-api.net/subscriptions/{sub-id}/resourceGroups/{rg-name}/providers/Microsoft.ApiManagement/service/{name}?api-version=2021-01-01-preview No Link

Customer must use the new Configuration API v2 by changing their deployment scripts to use the new URL and meet infrastructure requirements.

Important

  • DNS hostname must be resolvable to IP addresses and the corresponding IP addresses must be reachable. This might require additional configuration in case you are using a private DNS, internal VNET or other infrastrutural requirements.

Security

Available TLS cipher suites

At launch, self-hosted gateway v2.0 only used a subset of the cipher suites that v1.x was using. As of v2.0.4, we've brought back all the cipher suites that v1.x supported.

You can learn more about the used cipher suites in this article or use v2.1.1 to control what cipher suites to use.

Meet minimal security requirements

During startup, the self-hosted gateway will prepare the CA certificates that will be used. This requires the gateway container to run with at least user ID 1001 and can't use read-only file system.

When configuring a security context for the container in Kubernetes, the following are required at minimum:

securityContext:
  runAsNonRoot: true
  runAsUser: 1001
  readOnlyRootFilesystem: false

However, as of 2.0.3 the self-hosted gateway is able to run as non-root in Kubernetes allowing customers to run the gateway more securely.

Here's an example of the security context for the self-hosted gateway:

securityContext:
  allowPrivilegeEscalation: false
  runAsNonRoot: true
  runAsUser: 1001       # This is a built-in user, but you can use any user ie 1000 as well
  runAsGroup: 2000      # This is just an example
  privileged: false
  capabilities:
    drop:
    - all

Warning

Running the self-hosted gateway with read-only filesystem (readOnlyRootFilesystem: true) is not supported.

Assessing impact with Azure Advisor

In order to make the migration easier, we have introduced new Azure Advisor recommendations:

  • Use self-hosted gateway v2 recommendation - Identifies Azure API Management instances where the usage of self-hosted gateway v0.x or v1.x was identified.
  • Use Configuration API v2 for self-hosted gateways recommendation - Identifies Azure API Management instances where the usage of Configuration API v1 for self-hosted gateway was identified.

We highly recommend customers to use "All Recommendations" overview in Azure Advisor to determine if a migration is required. Use the filtering options to see if one of the above recommendations is present.

Use Azure Resource Graph to identify Azure API Management instances

This Azure Resource Graph query provides you with a list of impacted Azure API Management instances:

AdvisorResources
| where type == 'microsoft.advisor/recommendations'
| where properties.impactedField == 'Microsoft.ApiManagement/service' and properties.category == 'OperationalExcellence'
| extend
    recommendationTitle = properties.shortDescription.solution
| where recommendationTitle == 'Use self-hosted gateway v2' or recommendationTitle == 'Use Configuration API v2 for self-hosted gateways'
| extend
    instanceName = properties.impactedValue,
    recommendationImpact = properties.impact,
    recommendationMetadata = properties.extendedProperties,
    lastUpdated = properties.lastUpdated
| project tenantId, subscriptionId, resourceGroup, instanceName, recommendationTitle, recommendationImpact, recommendationMetadata, lastUpdated

az graph query -q "AdvisorResources | where type == 'microsoft.advisor/recommendations' | where properties.impactedField == 'Microsoft.ApiManagement/service' and properties.category == 'OperationalExcellence' | extend recommendationTitle = properties.shortDescription.solution | where recommendationTitle == 'Use self-hosted gateway v2' or recommendationTitle == 'Use Configuration API v2 for self-hosted gateways' | extend instanceName = properties.impactedValue, recommendationImpact = properties.impact, recommendationMetadata = properties.extendedProperties, lastUpdated = properties.lastUpdated | project tenantId, subscriptionId, resourceGroup, instanceName, recommendationTitle, recommendationImpact, lastUpdated"

Known limitations

Here's a list of known limitations for the self-hosted gateway v2:

  • Configuration API v2 doesn't support custom domain names

Next steps