リファレンス: セルフホステッド ゲートウェイ コンテナーの構成設定
適用対象: 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