運用環境の Kubernetes でのセルフホステッド ゲートウェイの実行に関するガイダンス

  • [アーティクル]

適用対象: Developer | Premium

運用環境でセルフホステッド ゲートウェイを実行するには、さまざまな点に注意する必要があります。 たとえば、可用性の高い方法でデプロイし、構成バックアップを使用して一時的な切断に対処するなどの多くの作業が必要です。

この記事では、運用ワークロード用に Kubernetes でセルフホステッド ゲートウェイを実行して、円滑かつ確実に動作するようにする方法についてのガイダンスを提供します。

重要

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

アクセス トークン

有効なアクセス トークンがない場合、セルフホステッド ゲートウェイで、関連付けられている API Management サービスのエンドポイントから構成データにアクセスしてダウンロードすることができません。 アクセス トークンは最大で 30 日間有効です。 有効期限が切れる前に再生成し、手動か自動化により、新しいトークンでクラスターを構成する必要があります。

トークンの更新を自動化する場合、この管理 API 操作を使用して新しいトークンを生成します。 Kubernetes シークレットの管理の詳細については、Kubernetes Web サイトを参照してください。

ヒント

また、セルフホステッド ゲートウェイを Kubernetes にデプロイし、Microsoft Entra ID を使用して API Management インスタンスへの認証を有効にすることもできます。

自動スケール

セルフホステッド ゲートウェイのレプリカの最小数に関するガイダンスが提供されていますが、セルフホステッド ゲートウェイの自動スケールを使用して、トラフィックの需要を事前に満たすようにすることをお勧めします。

セルフホステッド ゲートウェイを水平方向に自動スケールするには、次の 2 つの方法があります。

  • リソースの使用状況 (CPU およびメモリ) に基づく自動スケール
  • 1 秒あたりの要求数に基づく自動スケール

これはネイティブの Kubernetes 機能によって、または Kubernetes イベント ドリブン自動スケーリング (KEDA) を使用して行うことができます。 KEDA は、アプリケーションの自動スケールをシンプルにするために取り組む CNCF 育成プロジェクトです。

Note

KEDA は Azure サポートによってサポートされていないオープンソース テクノロジであるため、お客様が運用する必要があります。

リソースベースの自動スケーリング

Kubernetes ではポッドの水平オートスケーラーを使用して、リソース使用量に基づいてセルフホステッド ゲートウェイを自動スケールできます。 これにより、CPU とメモリのしきい値、およびスケールアウトまたはスケールインするレプリカの数を定義できます。

別の方法としては、CPU やメモリなどのさまざまなスケーラーに基づいてワークロードをスケーリングできる Kubernetes イベント ドリブン自動スケール (KEDA) を使用する方法があります。

ヒント

既に KEDA を使用して他のワークロードをスケーリングしている場合は、統合アプリ オートスケーラーとして KEDA を使用することをお勧めします。 そうでない場合は、ポッドの水平オートスケーラーを通じてネイティブの Kubernetes 機能を利用することを強くお勧めします。

トラフィックベースの自動スケーリング

Kubernetes には、トラフィックベースの自動スケーリング用のすぐに利用できるメカニズムが用意されていません。

Kubernetes イベント ドリブン自動スケール (KEDA) には、トラフィックベースの自動スケールに役立ついくつかの方法が用意されています。

  • Kubernetes イングレスからのメトリックが、すぐに利用できるスケーラーを使用して Prometheus または Azure Monitor 内で利用可能な場合、それらに基づいてスケーリングできます。
  • HTTP アドオンをインストールできます。これはベータ版で利用でき、1 秒あたりの要求数に基づいてスケール調整できます。

構成のバックアップ

セルフホステッド ゲートウェイ コンテナーのローカル ストレージ ボリュームを構成して、ダウンロードされた最新の構成のバックアップ コピーを保持できるようにします。 接続がダウンしている場合、ストレージ ボリュームでは再起動時、バックアップ コピーを利用できます。 ボリューム マウント パスは/apim/configで、グループ ID 1001によって所有されている必要があります。 例は GitHub でご覧ください。 Kubernetes でのストレージの詳細については、Kubernetes Web サイトを参照してください。 マウントされたパスの所有権を変更するには、Kubernetes Web サイトにあるsecurityContext.fsGroup設定を参照してください。

注意

Azure の接続が一時的に停止した場合のセルフホステッド ゲートウェイの動作については、「セルフホステッド ゲートウェイの概要」を参照してください。

コンテナー イメージ タグ

Azure portal に用意されている YAML ファイルでは、最新のタグが使用されます。 このタグでは常に、最新版のセルフホステッド ゲートウェイ コンテナー イメージが参照されます。

新しいバージョンへの意図しないアップグレードを避けるために、運用環境で特定のバージョン タグを使用することを検討してください。

利用できるタグの全一覧はこちらからダウンロードできます。

ヒント

Helm でインストールすると、イメージのタグ付けが自動的に最適化されます。 Helm チャートのアプリケーション バージョンでは、ゲートウェイは特定のバージョンに固定され、latest に依存しません。

Helm で Kubernetes に API Management セルフホステッド ゲートウェイをインストールする方法の詳細を確認してください。

コンテナー リソース

既定では、Azure portal で提供される YAML ファイルには、コンテナー リソース要求が指定されていません。

コンテナーごとの CPU およびメモリ リソースの量と、特定のワークロードをサポートするために必要なレプリカの数を確実に予測して推奨することは不可能です。 それには次のようなさまざまな要因があります。

  • クラスターが実行されている特定のハードウェア。
  • 仮想化の存在と種類。
  • 同時クライアント接続の数と割合。
  • 要求レート。
  • 構成されたポリシーの種類と数。
  • ペイロードのサイズと、ペイロードがバッファーされるのか、ストリーミングされるのか。
  • バックエンド サービスの待機時間。

リソース要求を 2 コアと 2 GiB に設定することから始めることをお勧めします。 ロード テストを実行し、結果に基づいてスケールアップ、スケールダウン、スケールアウト、スケールインします。

カスタム ドメイン名と SSL 証明書

API Management エンドポイントにカスタム ドメイン名を使用する場合、特に、管理エンドポイントのためにカスタム ドメイン名を使用する場合は、<gateway-name>.yaml ファイルの config.service.endpoint の値を更新して、既定のドメイン名をカスタム ドメイン名に置き換えることが必要な場合があります。 Kubernetes クラスター内のセルフホステッド ゲートウェイのポッドから管理エンドポイントにアクセスできることを確認します。

このシナリオでは、管理エンドポイントによって使用される SSL 証明書が、既知の CA 証明書によって署名されていない場合は、その CA 証明書がセルフホステッド ゲートウェイのポッドによって信頼されていることを確認する必要があります。

Note

セルフホステッド ゲートウェイ v2 を使用する場合、API Management には新しい構成エンドポイントが用意されます<apim-service-name>.configuration.azure-api.net。 このエンドポイントでは、カスタム ホスト名もサポートされており、既定のホスト名の代わりに使用できます。

DNS ポリシー

DNS 名前解決は、Azure 内の依存関係に接続してバックエンド サービスに API 呼び出しをディスパッチする、セルフホステッド ゲートウェイの機能において重要な役割を果たします。

Azure portal に用意されている YAML ファイルからは、既定の ClusterFirst ポリシーが適用されます。 このポリシーによって、クラスター DNS で解決されない名前解決要求は、ノードから継承される上流 DNS サーバーに転送されます。

Kubernetes での名前解決の詳細については、Kubernetes Web サイトを参照してください。 自分のセットアップに合わせて DNS ポリシーまたは DNS 構成をカスタマイズすることを検討してください。

外部トラフィック ポリシー

Azure portal で提供されている YAML ファイルでは、externalTrafficPolicy オブジェクトの externalTrafficPolicy フィールドが Local に設定されます。 これにより、(要求コンテキストでアクセスできる) 呼び出し元の IP アドレスが保持され、ノード間の負荷分散が無効になるため、発生するネットワーク ホップが排除されます。 この設定では、1 ノードあたりのゲートウェイ ポッド数が等しくないデプロイでトラフィックが非対称に分散される可能性があることに注意してください。

高可用性

セルフホステッド ゲートウェイは、インフラストラクチャの重要なコンポーネントであり、高可用性である必要があります。 ただし、エラーが発生する可能性はあります。

セルフホステッド ゲートウェイを中断から保護することを検討してください。

ヒント

Helm を使用してインストールすると、highAvailability.enabled 構成オプションを有効にすることで、高可用のスケジューリングを簡単に有効にできます。

Helm で Kubernetes に API Management セルフホステッド ゲートウェイをインストールする方法の詳細を確認してください。

ノードの障害からの保護

データ センターまたはノードの障害によって影響を受けないようにするには、可用性ゾーンを使用する Kubernetes クラスターを使用して、ノード レベルで高可用性を実現することを検討します。

可用性ゾーンでは、次のものを使用して、複数のゾーンに分散しているノードで、セルフホステッド ゲートウェイのポッドをスケジュールすることができます。

注意

Azure Kubernetes Service を使用している場合は、こちらの記事で可用性ゾーンの使用方法を確認してください。

ポッドの中断からの保護

ポッドは、手動でのポッドの削除や、ノードのメンテナンスなど、さまざまな理由により中断する可能性があります。

ポッド中断バジェットを使用して、常に最小限の数のポッドを使用可能にしておくことを検討してください。

HTTP(S) プロキシ

セルフホステッド ゲートウェイでは、従来の環境変数 HTTP_PROXY、HTTPS_PROXY、および NO_PROXY を使用して HTTP(S) プロキシがサポートされます。

構成が完了すると、セルフホステッド ゲートウェイはバックエンド サービスへのすべての送信 HTTP(S) 要求にプロキシを自動的に使用します。

バージョン 2.1.5 以上では、セルフホステッド ゲートウェイはプロキシ要求に関連する次のような監視機能を提供します。

  • HTTP(S) プロキシが使用されているときは、API 検査機能により、追加の手順とそれに関連する操作が表示されます。
  • プロキシ要求の動作を示すための詳細ログが提供されます。

Note

基本認証を使用する HTTP プロキシに関する既知の問題のため、証明書失効リスト (CRL) 検証の使用はサポートされていません。 詳細については、セルフホステッド ゲートウェイの設定のリファレンスに関するページで、適切に構成する方法を参照してください。

警告

インフラストラクチャ要件が満たされていることと、セルフホステッド ゲートウェイがそれらに引き続き接続できることを確認してください。しない場合、一部の機能が正常に動作しないことがあります。

ローカル ログとメトリック

セルフホスト ゲートウェイでは、関連する API Management サービスの構成設定ごとに、テレメトリが Azure Monitor と Azure Application Insights に送信されます。 Azure への接続が一時的に失われた場合、Azure へのテレメトリのフローは中断され、停止中のデータが失われます。

API トラフィックを監視し、Azure の接続が停止している間のテレメトリの損失を防ぐ機能を確保するために、Azure Monitor Container Insights を使用したコンテナ―の監視か、ローカル監視の設定を検討してください。

名前空間

Kubernetes 名前空間を使用すると、1 つのクラスターを複数のチーム、プロジェクト、またはアプリケーションに分割する際に役立ちます。 名前空間からはリソースと名前の範囲が与えられます。 リソース クォータとアクセス制御ポリシーに関連付けることができます。

Azure portal からは、既定の名前空間でセルフホステッド ゲートウェイ リソースを作成するコマンドが与えられます。 この名前空間は自動的に作成され、あらゆるクラスターに存在します。削除できません。 運用環境の別の名前空間にセルフホステッド ゲートウェイを作成およびデプロイすることを検討してください。

レプリカの数

運用環境に適したレプリカの最小数は 3 であり、インスタンスの高可用スケジューリングと組み合わせることをお勧めします。

既定では、セルフホステッド ゲートウェイは、RollingUpdate デプロイ戦略を使用してデプロイされます。 既定値を確認し、特に使用するレプリカの数が多い場合は、maxUnavailable および maxSurge フィールドに明示的に設定することを検討してください。

パフォーマンス

パフォーマンスを向上させるために、コンテナー ログを警告 (warn) に引き下げることをお勧めします。 詳細については、セルフホステッド ゲートウェイ構成リファレンスを参照してください。

要求の調整

セルフホステッド ゲートウェイの要求調整を有効にするには、API Management の rate-limit または rate-limit-by-key ポリシーを使います。 インスタンス検出用に Kubernetes デプロイで以下のポートを公開することで、クラスター ノード全体のゲートウェイ インスタンス間で同期するようにレート制限カウントを構成します。

  • ポート 4290 (UDP) (レート制限の同期用)
  • ポート 4291 (UDP) (他のインスタンスにハートビートを送信する用)

Note

セルフホステッド ゲートウェイのレート制限数は、Kubernetes の Helm グラフのデプロイや Azure portal デプロイ テンプレートの使用などにより、(クラスター ノード全体のゲートウェイ インスタンス間で) ローカルに同期するように構成できます。 ただし、レート制限数は、クラウドのマネージド ゲートウェイを含め、API Management インスタンスで構成されている他のゲートウェイ リソースと同期しません。

セキュリティ

セルフホステッド ゲートウェイは 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) を使用したセルフホステッド ゲートウェイの実行はサポートされていません。

警告

ローカル CA 証明書を使用する場合は、CA 証明書を管理するために、セルフホステッド ゲートウェイをユーザー ID (UID) 1001 で実行する必要があります。これを実行しない場合、ゲートウェイは起動しません。

次のステップ