自承载网关迁移指南

项目
03/08/2022

适用于：开发人员 | 高级

本文介绍如何将现有的自承载网关部署迁移到自承载网关 v2。

重要

对 Azure API 管理自托管网关版本 0 和版本 1 容器映像的支持及其相应配置 API v1 将于 2023 年 10 月 1 日结束。在弃用文档中了解详细信息

新增功能

当我们努力使客户更轻松地部署自承载网关时，我们引入了一个新的配置 API，用于删除对 Azure 存储的依赖关系，除非你使用的是 API 检查器或配额。

新的配置 API 允许客户在其现有基础结构中更轻松地采用、部署和操作自承载网关。

我们引入了新的容器映像标记，让客户选择最佳方式试用网关并将其部署到生产环境中。

为了帮助客户在生产环境中运行网关，我们扩充了生产指南，介绍如何自动缩放网关，并在 Kubernetes 群集中部署网关以实现高可用性。

在本文中详细了解网关的连接性、新的基础结构要求，以及丢失连接时会发生什么情况。

先决条件

在迁移到自承载网关 v2 之前，需要确保基础结构满足要求。

正在迁移到自承载网关 v2

从自承载网关 v2 迁移需要执行几个小步骤：

使用新的容器映像
使用新的配置 API
满足最低安全要求

容器映像

更改部署脚本中的映像标记以使用 2.0.0 或更高版本。

或者，选择其他容器映像标记之一。

可在此处找到可用标记的完整列表，或在 Docker Hub 上找到我们。

使用新的配置 API

为了迁移到自承载网关 v2，客户需要使用新的配置 API v2。

目前，Azure API 管理为自承载网关提供以下配置 API：

配置服务	URL	支持	要求
v2	`{name}.configuration.azure-api.net`	是	链接
v1	`{name}.management.azure-api.net/subscriptions/{sub-id}/resourceGroups/{rg-name}/providers/Microsoft.ApiManagement/service/{name}?api-version=2021-01-01-preview`	否	链接

客户必须通过更改部署脚本来使用新的配置 API v2，以便使用新 URL 并满足基础结构要求。

重要

DNS 主机名必须可解析为 IP 地址，并且相应的 IP 地址必须可访问。如果使用的是专用 DNS、内部 VNET 或其他基础结构要求，则可能需要其他配置。

安全性

可用的 TLS 密码套件

启动时，自承载网关 v2.0 仅使用了 v1.x 正在使用的密码套件的一部分。自 v2.0.4 开始，我们恢复了 v1.x 支持的所有密码套件。

可以在本文中详细了解所使用的密码套件，或使用 v2.1.1 来控制要使用的密码套件。

满足最低安全要求

在启动期间，自承载网关将准备要使用的 CA 证书。这要求网关容器至少使用用户 ID 1001 运行，并且不能使用只读文件系统。

在 Kubernetes 中为容器配置安全性上下文时，至少需要以下各项：

securityContext:
  runAsNonRoot: true
  runAsUser: 1001
  readOnlyRootFilesystem: false

但是，由于 2.0.3，自托管网关能够在 Kubernetes 中以非 root 身份运行，因此客户可以安全地运行该网关。

以下是自托管网关的安全性上下文示例：

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

警告

不支持使用只读文件系统 (readOnlyRootFilesystem: true) 运行自托管网关。

使用 Azure 顾问评估影响

为了简化迁移，我们引入了新的 Azure 顾问建议：

使用自承载网关 v2 建议 - 标识已标识自承载网关 v0.x 或 v1.x 的使用情况的 Azure API 管理实例。
将配置 API v2 用于自承载网关建议 - 标识已标识自承载网关的配置 API v1 的使用情况的 Azure API 管理实例。

强烈建议客户使用 Azure 顾问中的“所有建议”概述来确定是否需要迁移。使用筛选选项查看是否存在上述建议之一。

使用 Azure Resource Graph 来识别 Azure API 管理实例

该 Azure Resource Graph 查询提供受影响的 Azure API Management 实例列表：

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"

Search-AzGraph -Query "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"

已知限制

下面是自承载网关 v2 的已知限制列表：

配置 API v2 不支持自定义域名

通过