你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

将托管在 stv1 平台上的注入 VNet 的 API 管理实例迁移到 stv2

适用于：开发人员 | 高级

本文提供了当实例注入（部署）到外部或内部 VNet 中时，将托管在 stv1 计算平台上的 API 管理实例就地迁移到 stv2 平台的步骤。 对于此方案，请通过更新 VNet 配置设置来迁移实例。 确定是否需要这样做。

如果需要迁移托管在 stv1 平台上的未注入 VNnet 的 API 管理实例，请参阅将未注入 VNet 的 API 管理实例迁移到 stv2 平台。

重要

将在 2024 年 8 月 31 日前停用对 stv1 平台上托管的 API 管理实例的支持。 如果在 stv1 平台上托管有实例，请在该日期之前将其迁移到 stv2 平台，以避免服务中断。 了解详细信息。

注意

• 将 API 管理实例迁移到 stv2 平台是一项运行时间较长的操作。
• 实例的 VIP 地址将会更改。 迁移后，需要更新任何网络依赖项（包括 DNS、防火墙规则和 VNet）才能使用新的 VIP 地址。 相应地计划迁移。
• 迁移到 stv2 的操作是不可逆的。

迁移期间会发生什么情况？

将 API 管理平台从 stv1 迁移到 stv2 仅涉及到更新基础计算，并且不会影响存储层中保留的服务/API 配置。

• 升级过程包括创建与旧计算并行的新计算，这最多可能需要 45 分钟。
• Azure 门户中的 API 管理状态将为“正在更新”。
• 实例的 VIP 地址（或多区域部署的地址）将更改。
• Azure 管理管理终结点 DNS，并在成功迁移时立即更新为新计算。
• 如果正在使用自定义域，则网关 DNS 仍指向旧计算。
• 如果未使用自定义 DNS，则网关和门户 DNS 会立即指向新计算。
• 对于内部 VNet 模式下的实例，客户管理 DNS，因此 DNS 条目会继续指向旧计算，直到客户更新为止。
• 它是指向新计算或旧计算的 DNS，因此 API 不会停机。
• 防火墙规则（如果有）需要更改才能允许新的计算子网访问后端。
• 成功迁移后，旧计算默认会在大约 15 分钟后自动停用。 可以启用将旧网关保留 48 小时的迁移设置。 48 小时延迟选项仅适用于注入 VNet 的服务。

先决条件

• API 管理实例托管在 stv1 计算平台上。 若要确认实例是否托管在 stv1 平台上，请参阅如何知道哪个平台托管了我的 API 管理实例？必须将实例诸如虚拟网络。

• 当前虚拟网络中部署 API 管理实例的每个区域中的新子网。 （或者，在 API 管理实例所在的同一区域和订阅中的不同虚拟网络中设置子网）。 必须将网络安全组附加到子网，而且必须配置 API 管理的 NSG 规则。

• （可选）在 API 管理实例所在的同一区域和订阅中存在新的标准 SKU 公共 IPv4 地址资源。 有关详细信息，请查看网络连接的先决条件。

  重要

  • 从 2024 年 5 月开始，在内部模式下的 VNet 中部署（注入）API 管理实例或将内部 VNet 配置迁移到新子网时，不再需要公共 IP 地址。 在外部 VNet 模式下，指定公共 IP 地址为可选操作；如果未提供，则会自动配置 Azure 托管的公共 IP 地址。 在外部 VNet 模式下，公共 IP 地址用于运行时 API 流量。
  • 目前，如果在内部模式或外部模式下的 VNet 中为 API 管理实例启用区域冗余，则必须指定新的公共 IP 地址。

触发注入网络的 API 管理实例的迁移

通过更新现有网络配置以在部署该实例的每个区域中使用新的网络设置，触发注入网络的 API 管理实例向 stv2 平台的迁移。 更新完成后，可以迁移回所使用的原始 VNet 和子网（可选步骤）。

还可通过启用高级层中的区域冗余来迁移到 stv2 平台。

重要

API 管理实例的 VIP 地址将更改。 但 API 请求在迁移期间将会保持响应。 基础结构配置（如自定义域、位置和 CA 证书）将锁定 30 分钟。 迁移后，需要更新任何网络依赖项（包括 DNS、防火墙规则和对等 VNet）才能使用新的 VIP 地址。

更新网络配置

可以使用 Azure 门户迁移到相同或不同 VNet 中的新子网。 下图大致概述了迁移到新子网期间发生的情况。

Portal

1. 在 Azure 门户，导航到 API 管理实例。

2. 在左侧菜单中的“设置”下，选择“平台迁移”。

3. 在“平台迁移”页上的“步骤 1”中，查看迁移要求和先决条件。

4. 在“步骤 2”中，选择迁移选项：

   • 选择要迁移的位置。

   • 选择要迁移到的“虚拟网络”、“子网”和可选的“公共 IP 地址”。

     

   • 选择迁移后是“尽快返回到原始子网”还是“保留在新子网中，并保留 stv1 计算大约 48 小时”。 如果选择前者，迁移后大约 15 分钟会删除 stv1 计算，以便根据需要直接迁移回原始子网。 如果选择后者，则 stv1 计算将保留 48 小时。 可以利用此时间段来验证网络设置和连接。

     

5. 在“步骤 3”中，确认要迁移，然后选择“迁移”。 API 管理实例的状态将更改为“正在更新”。 迁移过程大约需要 45 分钟才能完成。 当状态变为“联机”时，迁移完成。

如果 API 管理实例部署在多个区域中，请重复上述步骤，继续迁移实例剩余位置的 VNet 设置。

（可选）迁移回原始子网

在迁移到 stv2 平台之前，可以选择迁移回在每个区域中之前所使用的原始子网。 为此，请再次更新 VNet 配置，这次指定每个区域的原始 VNet 和子网。 与前面的迁移一样，预计操作运行时间较长，而且 VIP 地址预计会更改。

下图大致概述了迁移回原始子网期间发生的情况。

重要

如果 VNet 和子网已锁定（由于部署了其他基于 stv1 平台的 API 管理实例），或者部署原始 VNet 的资源组具有资源锁，请确保在迁移到原始子网之前删除该锁。 在尝试迁移到原始子网之前，请等待锁定删除完成。 了解详细信息。

其他先决条件

• 部署 API 管理实例的每个区域中已解锁的原始子网。 必须将网络安全组附加到子网，而且必须配置 API 管理的 NSG 规则。

• （可选）在 API 管理实例所在的同一区域和订阅中存在新的标准 SKU 公共 IPv4 地址资源。

  重要

  • 从 2024 年 5 月开始，在内部模式下的 VNet 中部署（注入）API 管理实例或将内部 VNet 配置迁移到新子网时，不再需要公共 IP 地址。 在外部 VNet 模式下，指定公共 IP 地址为可选操作；如果未提供，则会自动配置 Azure 托管的公共 IP 地址。 在外部 VNet 模式下，公共 IP 地址用于运行时 API 流量。
  • 目前，如果在内部模式或外部模式下的 VNet 中为 API 管理实例启用区域冗余，则必须指定新的公共 IP 地址。

更新 VNet 配置

1. 在门户中，导航到原始 VNet。
2. 在左侧菜单中，选择“子网”，然后选择原始子网。
3. 确认原始 IP 地址已由 API 管理释放。 在“可用 IP”下，记下子网中可用的 IP 地址数。 所有地址（Azure 保留地址除外）都应可用。 如有必要，请等待 IP 地址释放。
4. 导航到 API 管理实例。
5. 在左侧菜单的“网络”下，选择“虚拟网络”。
6. 在该位置中选择要更新的网络连接。
7. 选择原始 VNet 网络和子网。 （可选）选择新的公共 IP。 选择“应用”。
8. 如果 API 管理实例部署在多个区域中，请继续配置实例剩余位置的 VNet 设置。
9. 在顶部导航栏中选择“保存”。

更新 VNet 配置后，API 管理实例的状态将更改为“正在更新”。 迁移过程大约需要 45 分钟才能完成。 当状态变为“联机”时，迁移完成。

验证迁移

若要验证迁移是否成功，当状态更改为“联机”时，请检查 API 管理实例的平台版本。 成功迁移后，该值为 stv2 或 stv2.1。

在清除旧网关之前确认设置

成功迁移注入 VNet 的 API 管理实例后，迁移过程中创建的旧计算和新计算会共存一小段时间（大约 15 分钟），这是一个很短的时间窗口，可用于验证部署以及你的应用程序是否按预期工作。 （可以提前联系 Azure 支持，将此窗口延长至 48 小时。）

• 在此窗口期间，新旧网关都处于联机状态并提供流量。 在此期间无需付费。
• 在此窗口期内更新任何网络依赖项（包括 DNS、防火墙规则和 VNet）以使用新的 VIP 地址和子网地址空间。
• 此外，请检查更新后实例的网络状态以确保实例与其依赖项的连接。 在门户中左侧菜单中的“部署和基础结构”下，选择“网络”“网络状态”。 如果需要，请更新 UDR 和 NSG 规则等设置。
• 在该窗口期后，旧网关将停用，新网关是唯一提供流量的网关。

迁移失败时自动还原

如果在迁移过程中出现故障，实例将自动还原到 stv1 平台。 如果迁移成功完成（实例的平台版本显示为 stv2 或 stv2.1，并且状态显示为“联机”），则无法回滚到 stv1 平台。

如果迁移失败，请联系 Azure 支持以获取帮助。

如果需要手动回滚功能，建议与原始 API 管理实例并行部署新的 stv2 实例。

帮助和支持

我们将在此处帮助你迁移到 stv2 平台，同时将对服务造成的干扰降至最低。

如果有疑问，请从 Microsoft Q&A 中的社区专家那里快速获取解答。 如有支持计划并需要技术帮助，请创建支持请求。

1. 对于“摘要”，请键入问题的说明，例如“stv1 停用”。
2. 在“问题类型”下，选择“技术”。
3. 在“订阅”下，选择自己的订阅。
4. 在“服务”下，选择“我的服务”，然后选择“API 管理服务”。
5. 在“资源”下，选择要为其创建支持请求的 Azure 资源。
6. 请在“问题类型”处选择“管理”。
7. 对于“问题子类型”，选择“升级、缩放或 SKU 更改”。

常见问题

• 需要哪些信息来选择迁移路径？

  • API 管理实例的网络模式是什么？
  • 是否配置了自定义域？
  • 是否涉及防火墙？
  • 上游/下游对所涉及的 IP 是否有任何已知的依赖项？
  • 是多区域部署吗？
  • 我们可以修改现有实例吗？还是需要并行设置？
  • 会有故障时间吗？
  • 迁移是否可以在非业务时间内完成？

• 迁移的先决条件是什么？

  对于注入 VNet 的实例，需要新的子网才能在每个 VNet 中进行迁移（外部模式或内部模式）。 在外部模式下，可以选择提供公共 IP 地址资源。 子网必须按照 stv2 平台的规则附加 NSG，如此处所述。

• 迁移是否会产生故障时间？

  由于仅在新计算正常且联机后才清除旧网关，因此在使用默认主机名时不应停机。 至关重要的是，要使受影响的 API 正常运行，必须提前处理好所有网络依赖项。 但是，如果正在使用自定义域，它们将在更新前持续指向被清除的计算，这可能会导致停机。 或者，启用将旧网关保留 48 小时的迁移设置。 让旧计算和新计算共存将促进验证，然后可以随时更新自定义 DNS 条目。

• 我的流量通过防火墙强制隧道传输的。 需要哪些更改？

  • 首先，请确保为迁移创建的新子网保留以下配置（它们应已在当前子网中配置）：
    • 如此处所述启用服务终结点
    • UDR（用户定义的路由）具有从 ApiManagement 服务标记设置为“Internet”的跃点，而不仅仅是防火墙地址
  • 无论你是否有防火墙，stv2 的 NSG 配置要求保持不变；确保新子网包含它
  • 应更新引用 API 管理实例的当前 IP 地址范围的防火墙规则，以使用新子网的 IP 地址范围。

• 迁移期间是否可能发生数据或配置丢失？

  stv1 到 stv2 迁移涉及仅更新计算平台，内部存储层不会更改。 因此，在迁移过程中，所有配置都是安全的。 这包括系统分配的托管标识，如果启用，则会保留该标识。

• 如何确认迁移已完成且成功？

  当概述页中的状态显示“联机”，并且平台版本为 stv2 或 stv2.1 时，迁移被视为已完成且成功。 此外，请验证“网络”边栏选项卡中的网络状态是否对所有必需连接显示绿色。

• 是否可以使用门户执行迁移？

  是的，可以通过在“平台迁移”边栏选项卡中更改子网配置来迁移注入 VNet 的实例。

• 是否可以保留实例的 IP 地址？

  如果实例注入 VNet，则当前无法保留 IP 地址。

• 是否存在不修改现有实例的迁移路径？

  是的，需要并行迁移。 这意味着，可以与当前实例并行创建新的 API 管理实例，并将配置复制到新实例。

• 如果迁移失败，会发生什么情况？

  如果在启动迁移后，API 管理实例的平台版本未显示为 stv2 或 stv2.1，并且状态未显示为“联机”，则迁移可能失败。 服务会自动回滚到旧实例，不会做出任何更改。

• 迁移期间，哪些功能不可用？

  API 请求在迁移期间将会保持响应。 基础结构配置（如自定义域、位置和 CA 证书）锁定 30 分钟。 迁移后，需要更新任何网络依赖项（包括 DNS、防火墙规则和 VNet）才能使用新的 VIP 地址。

• 迁移需要多长时间？

  迁移到新 VNet 配置的预期持续时间约为 45 分钟。 检查迁移是否已执行的指示器是检查实例的状态是否返回到“联机”，而不是“正在更新”。

• 尝试迁移之前，是否有方法验证 VNet 配置？

  可以使用用于实际迁移的新 VNet、子网和 IP 地址资源部署新的 API 管理实例（可选）。 部署完成后导航到“网络状态”页，并验证每个终结点连接状态是否为绿色。 如果是，则可以删除此新的 API 管理实例，然后继续执行原始 stv1 托管服务的实际迁移。

• 如果需要，是否可以回滚迁移？

  如果在迁移过程中出现故障，实例将自动回滚到 stv1 平台。 但是，在服务成功迁移后，无法回滚到 stv1 平台。

  成功迁移注入 VNet 的服务后，旧网关在短时间内会继续提供流量，你可以在此期间确认网络设置。 请参阅在清除旧网关之前确认设置

• 自定义域/专用 DNS 区域是否需要任何更改？

  在内部模式下使用注入 VNet 的实例时，需要在迁移后将专用 DNS 区域更新为获取的新 VNet IP 地址。 请注意也更新非 Azure DNS 区域（例如，指向 API 管理专用 IP 地址的本地 DNS 服务器）。 但是，在外部模式下，迁移过程将在使用时自动更新默认域。

• 我的 stv1 实例部署到多个 Azure 区域（多区域）。 如何升级到 stv2？

  多区域部署包括部署在其他位置的更多托管网关。 通过更新相应的网络设置（例如，使用“平台迁移”边栏选项卡）单独迁移每个位置。 仅当迁移所有位置时，该实例才会被视为迁移到新平台。 所有区域网关都将在整个迁移过程中继续正常运行。

• 是否可以将 stv1 实例升级到同一子网？

  • 无法在不停机的情况下一次性将 stv1 实例迁移到同一子网。 但是，可以选择将迁移的实例移回原始子网。 此处提供了更多详细信息。
  • 旧网关需要 15 分钟到 45 分钟才能腾出子网，以便启动移动。 然而，可以启用将旧网关保留 48 小时的迁移设置。
  • 确保针对 stv2 依赖项更新了 NSG 和防火墙的旧子网网络。
  • 子网 IP 地址分配是不确定的，因此在移回原始子网时，“内部模式”部署的原始 ILB（入口）IP 可能会发生变化。 如果使用 A 记录，则需要 DNS 更改。

• 是否可以在切换实时流量之前测试新网关？

  • 默认情况下，旧托管网关和新托管网关会共存 15 分钟，这是验证部署的一个短暂的时间窗口。 可以启用将旧网关保留 48 小时的迁移设置。 此更改会使旧托管网关和新托管网关保持活动状态，以接收流量并促进验证。
  • 迁移过程会自动更新默认域名，如果使用，流量会立即路由到新网关。
  • 如果使用自定义域名，则如果不使用 CNAME，则可能需要使用新的 IP 地址更新相应的 DNS 记录。 在进行切换之前，客户可以将其主机文件更新到新的 API 管理 IP 并验证实例。 在此验证过程中，旧网关继续为实时流量提供服务。

• 使用默认域名时是否有任何注意事项？

  在外部模式下使用默认 DNS 名称的实例由迁移过程自动更新 DNS。 此外，迁移过程会自动更新始终使用默认域名的管理终结点。 由于成功迁移后会立即进行切换，因此新实例会立即开始接收流量，任何网络限制/依赖项都需提前处理，以避免受影响的 API 不可用。

• 我们应考虑哪些自承载网关？

  无需在自承载网关中执行任何操作。 只需迁移 Azure 中运行的、受 stv1 平台停用影响的 API 管理实例。 请注意，API 管理实例的配置终结点可能存在新的 IP，并且应更新固定到 IP 的任何网络限制。

• 开发人员门户如何受到迁移的影响？

  对开发人员门户没有影响。 如果使用自定义域，应在迁移后使用有效的 IP 更新 DNS 记录。 但是，如果默认域正在使用，则会在成功迁移时自动更新它们。 在迁移过程中，开发人员门户没有故障时间。

• 迁移到 stv2 后，是否会对成本产生任何影响？

  对于 stv2，计费模型保持不变，迁移期间和之后不会再产生任何费用。

• stv1 到 stv2 的迁移需要哪些 RBAC 权限？

  进行迁移的用户/进程需要对 API 管理实例的写入权限。 此外，还需要以下两个权限：

  • Microsoft.Network/virtualNetworks/subnets/join/action
  • Microsoft.Network/publicIPAddresses/join/action

视频

相关内容

• 如何知道哪个平台托管了我的 API 管理实例？

• API 管理 stv2 计算平台的优势

• 了解 stv1 平台将于 2024 年 8 月停用