リファレンス: セルフホステッド ゲートウェイ コンテナーの構成設定

  • [アーティクル]

適用対象: Developer | Premium

この記事では、API Management セルフホステッド ゲートウェイ コンテナーを構成するために使われる必要な設定と省略可能な設定のリファレンスを提供します。

(Kubernetes) の運用ガイダンスの詳細については、こちらの記事 参照することをお勧めします。

重要

このリファレンスは、セルフホステッド ゲートウェイ v2 にのみ適用されます。 設定が可能な最小バージョンが用意されています。

構成 API の統合

構成 API は、Azure API Management に接続して最新の構成を取得し、有効にした場合にメトリックを送信するためにセルフホステッド ゲートウェイによって使用されます。

すべての構成オプションの概要を次に示します。

名前 説明 必要 Default 可用性
gateway.name セルフホステッド ゲートウェイ リソースの ID。 はい (Microsoft Entra 認証を使用する場合) 該当なし v2.3+
config.service.endpoint セルフホステッド ゲートウェイの Azure API Management の構成エンドポイント。 この値は、Azure portal の [ゲートウェイ]>[デプロイ] の下にあります。 はい 該当なし v2.0+
config.service.auth セルフホステッド ゲートウェイで構成 API に対して認証する方法を定義します。 現在、ゲートウェイ トークンと Microsoft Entra 認証がサポートされています。 はい 該当なし v2.0+
config.service.auth.azureAd.tenantId Microsoft Entra テナントの ID。 はい (Microsoft Entra 認証を使用する場合) 該当なし v2.3+
config.service.auth.azureAd.clientId 認証に使用する Microsoft Entra アプリのクライアント ID (アプリケーション ID とも呼ばれます)。 はい (Microsoft Entra 認証を使用する場合) 該当なし v2.3+
config.service.auth.azureAd.clientSecret 認証に使用する Microsoft Entra アプリのシークレット。 はい (証明書が指定されておらず、Microsoft Entra 認証を使用する場合) 該当なし v2.3+
config.service.auth.azureAd.certificatePath Microsoft Entra アプリでの認証に使用する証明書へのパス。 はい (シークレットが指定されておらず、Microsoft Entra 認証を使用する場合) 該当なし v2.3+
config.service.auth.azureAd.authority Microsoft Entra ID の機関 URL。 いいえ https://login.microsoftonline.com v2.3+
config.service.auth.tokenAudience Microsoft Entra 認証に使用されるトークンの対象ユーザー いいえ https://azure-api.net/configuration v2.3+
config.service.endpoint.disableCertificateValidation セルフホステッド ゲートウェイが Configuration API のサーバー側証明書を検証する必要があるかどうかを定義します。 証明書の検証を使用することをお勧めします。セキュリティ リスクが生じる可能性があるため、無効にするのは、テスト目的のみとし、慎重に行ってください。 いいえ false v2.0+
config.service.integration.timeout 構成 API と対話するためのタイムアウトを定義します。 いいえ 00:01:40 v2.3.5+

セルフホステッド ゲートウェイでは、config.service.auth を使用して定義できる構成 API と統合するためのいくつかの認証オプションがサポートされています。

このガイダンスは、認証方法を定義するために必要な情報を提供するのに役立ちます。

  • ゲートウェイ トークンベースの認証の場合は、セルフホステッド ゲートウェイのアクセス トークン (認証キー) を Azure portal の [ゲートウェイ]>[デプロイ] で指定します。
  • Microsoft Entra ID ベースの認証の場合は、azureAdApp を指定して、追加の config.service.auth.azureAd 認証設定を指定します。

クロスインスタンス検出と同期

名前 説明 必要 Default 可用性
neighborhood.host インスタンス間同期のために、セルフホステッド ゲートウェイデプロイのすべてのインスタンスを解決するために使用される DNS 名。 Kubernetes では、ヘッドレス サービスを使用して実現できます。 いいえ 該当なし v2.0+
neighborhood.heartbeat.port 他のインスタンスにハートビートを送信するために、セルフホステッド ゲートウェイデプロイのインスタンスに使用される UDP ポート。 いいえ 4291 v2.0+
policy.rate-limit.sync.port 複数のインスタンス間でレート制限を同期するために、セルフホステッド ゲートウェイ インスタンスに使用される UDP ポート。 いいえ 4290 v2.0+

HTTP

名前 説明 必要 Default 可用性
net.server.http.forwarded.proto.enabled 呼び出された API ルート (http/https のみ) を解決するスキームを識別するために、 X-Forwarded-Proto ヘッダーを受け入れた機能。 いいえ false v2.5 以降

Kubernetes の統合

Kubernetes イングレス

重要

Kubernetes イングレスのサポートは現在試験段階であり、Azure サポートの対象にはなっていません。 詳細については、GitHub をご覧ください。

名前 説明 必要 Default 可用性
k8s.ingress.enabled Kubernetes イングレス統合を有効にします。 いいえ false v1.2+
k8s.ingress.namespace Kubernetes イングレス リソースを監視する Kubernetes 名前空間。 いいえ default v1.2+
k8s.ingress.dns.suffix 要求の送信先であるサービスの DNS ホスト名を構築する DNS サフィックス。 いいえ svc.cluster.local v2.4+
k8s.ingress.config.path Kubernetes 構成 (Kubeconfig) のパス。 いいえ 該当なし v2.4+

メトリック

名前 説明 必要 Default 可用性
telemetry.metrics.local StatsD を使ってローカル メトリックの収集を有効にします。 値は、以下のオプションの いずれかです。none、statsd。 いいえ none v2.0+
telemetry.metrics.local.statsd.endpoint StatsD エンドポイント。 telemetry.metrics.local を statsd に設定した場合は "はい"。それ以外の場合は "いいえ"。 該当なし v2.0+
telemetry.metrics.local.statsd.sampling StatsD メトリックのサンプリング レート。 値は 0 から 1 にする必要があります (たとえば 0.5)。 いいえ 該当なし v2.0+
telemetry.metrics.local.statsd.tag-format StatsD エクスポーターのタグ付け形式。 値は、以下のオプションの いずれかです。ibrato、dogStatsD、influxDB。 いいえ 該当なし v2.0+
telemetry.metrics.cloud Azure Monitor に対するメトリックの生成を有効にするかどうかを示します。 いいえ true v2.0+
observability.opentelemetry.enabled Kubernetes 上で OpenTelemetry コレクターに対するメトリックの生成を有効にするかどうかを示します。 いいえ false v2.0+
observability.opentelemetry.collector.uri メトリックの送信先 OpenTelemetry コレクターの URI。 observability.opentelemetry.enabled を true に設定した場合は "はい"。それ以外の場合は "いいえ"。 該当なし v2.0+
observability.opentelemetry.system-metrics.enabled OpenTelemetry コレクター (CPU、メモリ、ガベージ コレクションなど) へのシステム メトリックの送信を有効にします。 いいえ false v2.3+
observability.opentelemetry.histogram.buckets OpenTelemetry のメトリックを報告するヒストグラム バケット。 形式: "x,y,z,..."。 いいえ "5,10,25,50,100,250,500,1000,2500,5000,10000" v2.0+

ログ

名前 説明 必要 Default 可用性
telemetry.logs.std 標準ストリームへのログ記録を有効にします。 値は、以下のオプションの いずれかです。none、text、json。 いいえ text v2.0+
telemetry.logs.std.level 標準ストリームに送信されるログのログ レベルを定義します。 値は、以下のオプションの いずれかです。all、debug、info、warn、errorまたはfatal。 いいえ info v2.0+
telemetry.logs.std.color 標準ストリームで色付きのログを使用する必要があるかどうかの表示。 いいえ true v2.0+
telemetry.logs.local ローカルのログ記録を有効にします。 値は、以下のオプションの いずれかです。none、auto、localsyslog、 rfc5424、 journal、 json いいえ auto v2.0+
telemetry.logs.local.localsyslog.endpoint localsyslog エンドポイント。 telemetry.logs.local を localsyslog に設定した場合は "はい"。それ以外の場合は "いいえ"。 構成の詳細については、 ローカル syslog のドキュメント を参照してください。 該当なし v2.0+
telemetry.logs.local.localsyslog.facility localsyslog ファシリティ コードを指定します (たとえば 7)。 いいえ 該当なし v2.0+
telemetry.logs.local.rfc5424.endpoint rfc5424 エンドポイント。 telemetry.logs.local を rfc5424 に設定した場合は "はい"。それ以外の場合は "いいえ"。 該当なし v2.0+
telemetry.logs.local.rfc5424.facility rfc5424 によるファシリティ コード (たとえば 7) いいえ 該当なし v2.0+
telemetry.logs.local.journal.endpoint ジャーナル エンドポイント。 telemetry.logs.local を journal に設定した場合は "はい"。それ以外の場合は "いいえ"。 該当なし v2.0+
telemetry.logs.local.json.endpoint JSON データを受け付ける UDP エンドポイント。ファイル パス、:<ポート>、<ホスト名>:<ポート> のいずれかの形式で指定します。 telemetry.logs.local を json に設定した場合は "はい"。それ以外の場合は "いいえ"。 127.0.0.1:8888 v2.0+

セキュリティ

証明書と暗号

名前 説明 必要 Default 可用性
certificates.local.ca.enabled マウントされているローカル CA 証明書をセルフホステッド ゲートウェイで使うかどうかを示します。 セルフホステッド ゲートウェイを、ルートとして、またはユーザー ID 1001 を使って実行する必要があります。 いいえ false v2.0+
net.server.tls.ciphers.allowed-suites API クライアントとセルフホステッド ゲートウェイ間の TLS 接続に使う暗号のコンマ区切りの一覧。 いいえ TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA v2.0+
net.client.tls.ciphers.allowed-suites セルフホステッド ゲートウェイとバックエンド間の TLS 接続に使う暗号のコンマ区切りの一覧。 いいえ TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA v2.0+
security.certificate-revocation.validation.enabled 証明書失効リストの検証を有効または無効にする機能を提供します いいえ false v2.3.6+

TLS

名前 説明 必要 Default 可用性
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls13 バックエンドに対して TLS 1.3 が許可されているかどうかを示します。 マネージド ゲートウェイでのプロトコル暗号の管理 に似ています。 いいえ true v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls12 バックエンドに対して TLS 1.2 が許可されているかどうかを示します。 マネージド ゲートウェイでのプロトコル暗号の管理 に似ています。 いいえ true v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11 TLS 1.1 がバックエンドに対して許可されているかどうかを示します。 マネージド ゲートウェイでのプロトコル暗号の管理 に似ています。 いいえ false v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10 バックエンドに対して TLS 1.0 が許可されているかどうかを示します。 マネージド ゲートウェイでのプロトコル暗号の管理 に似ています。 いいえ false v2.0+
Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Ssl30 バックエンドに対して SSL 3.0 が許可されているかどうかを示します。 マネージド ゲートウェイでのプロトコル暗号の管理 に似ています。 いいえ false v2.0+

ソブリン クラウド

ソブリン クラウドを操作できるように構成する必要がある設定の概要を次に示します。

Name 公開 Azure 中国 米国政府
config.service.auth.tokenAudience https://azure-api.net/configuration (既定値) https://azure-api.cn/configuration https://azure-api.us/configuration
logs.applicationinsights.endpoint https://dc.services.visualstudio.com/v2/track (既定値) https://dc.applicationinsights.azure.cn/v2/track https://dc.applicationinsights.us/v2/track

設定の構成方法

Kubernetes YAML ファイル

YAML ファイルを使ってセルフホステッド ゲートウェイを Kubernetes にデプロイする場合は、ゲートウェイの ConfigMap の data 要素で名前と値のペアという形式で設定を構成します。 次に例を示します。

apiVersion: v1
    kind: ConfigMap
    metadata:
        name: contoso-gateway-environment
    data:
        config.service.endpoint: "contoso.configuration.azure-api.net"
        telemetry.logs.std: "text"
        telemetry.logs.local.localsyslog.endpoint: "/dev/log"
        telemetry.logs.local.localsyslog.facility: "7"

[...]

Helm チャート

Helm を使ってセルフホステッド ゲートウェイを Kubernetes にデプロイする場合は、チャートの構成設定を helm install コマンドのパラメーターとして渡します。 次に例を示します。

helm install azure-api-management-gateway \
    --set gateway.configuration.uri='contoso.configuration.azure-api.net' \
    --set gateway.auth.key='GatewayKey contosogw&xxxxxxxxxxxxxx...' \
    --set secret.createSecret=false \
    --set secret.existingSecretName=`mysecret` \
    azure-apim-gateway/azure-api-management-gateway

次のステップ