セルフホステッドゲートウェイ移行ガイド

[アーティクル]
06/01/2023

適用対象: 開発者 | プレミアム

この記事では、既存のセルフホステッドゲートウェイデプロイをセルフホステッドゲートウェイ v2 に移行する方法について説明します。

重要

Azure API Management セルフホステッドゲートウェイバージョン 0 およびバージョン 1 コンテナーイメージのサポートは、それに対応する Configuration API v1 とともに 2023 年 10 月 1 日に終了します。非推奨に関するドキュメントで詳細を確認する

新機能

Microsoft では、そのセルフホステッドゲートウェイをお客様にとってデプロイしやすいものにするという取り組みの中で、API インスペクターまたはクォータが使用されていない限り、Azure Storage への依存を排除する新しい構成 API を導入しました。

新しい構成 API を使用すると、既存のインフラストラクチャに対し、以前よりも簡単に Microsoft のセルフホステッドゲートウェイを導入、デプロイし、それを運用できるようになります。

Microsoft のゲートウェイを運用環境で試し、デプロイする最適な方法をお客様が選択できるようにするため、新しいコンテナーイメージタグを導入しました。

Microsoft のゲートウェイを運用環境で実行しやすくするために、運用ガイダンスを拡充しました。ゲートウェイを自動スケーリングする方法や、それを Kubernetes クラスターにデプロイして高可用性を確保する方法を紹介しています。

ゲートウェイの接続や新しいインフラストラクチャ要件、接続が失われた場合に起こることについて詳しくは、こちらの記事を参照してください。

前提条件

セルフホステッドゲートウェイ v2 に移行するには、ご使用のインフラストラクチャが要件を満たしていることをあらかじめ確認しておく必要があります。

セルフホステッドゲートウェイ v2 に移行する

セルフホステッドゲートウェイ v2 の移行には、いくつかの簡単な手順が必要となります。

新しいコンテナーイメージを使用する
新しい構成 API を使用する
最小限のセキュリティ要件を満たす

コンテナーイメージ

デプロイスクリプトのイメージタグを、2.0.0 以降を使用するように変更します。

または、Microsoft が提供している他のコンテナーイメージタグをどれか選択してください。

使用できるタグの全一覧については、こちらまたは Docker Hub をご覧ください。

新しい構成 API を使用する

セルフホステッドゲートウェイ v2 に移行するためには、Microsoft の新しい Configuration API v2 を使用する必要があります。

現在、Azure API Management では、セルフホステッドゲートウェイ向けに、次の Configuration 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`	いいえ	リンク

新しい Configuration 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 で非ルートとして実行できるので、お客様はゲートウェイをより安全に実行できます。

セルフホステッドゲートウェイのセキュリティコンテキストの例を次に示します。

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 Advisor で影響を評価する

移行を容易にするために、Azure Advisor の新しい推奨事項が導入されました。

セルフホステッドゲートウェイ v2 の使用に関する推奨事項 - セルフホステッドゲートウェイ v0.x または v1.x の使用が確認された Azure API Management インスタンスを識別します。
セルフホステッドゲートウェイでの Configuration API v2 の使用に関する推奨事項 - セルフホステッドゲートウェイでの Configuration API v1 の使用が確認された Azure API Management インスタンスを識別します。

移行が必要かどうかを判断するために、Azure Advisor の "すべての推奨事項" の概要を使用することを強くお勧めします。フィルターオプションを使用して、上記の推奨事項のいずれかが存在するかどうかを確認してください。

Azure Resource Graph を使用して Azure API Management インスタンスを識別する

この 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 には、次の制限が確認されています。

Configuration API v2 ではカスタムドメイン名がサポートされません

次のステップ

ハイブリッドおよびマルチクラウドワールドでの API Management について学習する
運用環境の Kubernetes でのセルフホステッドゲートウェイの実行に関するガイダンスを参照してください
Docker にセルフホステッドゲートウェイをデプロイする
Kubernetes にセルフホステッドゲートウェイをデプロイする
Azure Arc 対応 Kubernetes クラスターにセルフホステッドゲートウェイをデプロイする

セルフホステッド ゲートウェイ移行ガイド

新機能