すべてのプロダクト
Search

このプロダクト

    Container Service for Kubernetes:MSE Ingressゲートウェイでサポートされる注釈

    ドキュメントセンター

    Container Service for Kubernetes:MSE Ingressゲートウェイでサポートされる注釈

    最終更新日:Nov 19, 2024

    マイクロサービスエンジン (MSE) Ingressゲートウェイは、NGINX Ingressゲートウェイのコアおよび一般的なアノテーションをサポートします。 これにより、NGINX IngressゲートウェイからMSE Ingressゲートウェイへのシームレスな移行が容易になります。 MSE Ingressゲートウェイは、トラフィックガバナンスのための追加の注釈も提供します。 このトピックでは、MSE Ingressゲートウェイでサポートされるアノテーションについて説明します。

    背景情報

    Ingressリソースは、Kubernetesクラスター内のサービスが外部アクセスにどのように公開されるかを管理するために使用されます。 クラウドネイティブ分散アプリケーションの数が増加するにつれて、Kubernetes標準で定義されているIngressリソースがユーザーのトラフィック管理要件を満たすことができなくなります。 さまざまなシナリオでIngress機能の要件を満たすために、Ingressコントローラーの開発チームはカスタムアノテーションの定義を開始しました。 主流のNGINX Ingressコントローラに対して100を超えるアノテーションが定義されています。

    MSE Ingressゲートウェイは、NGINX Ingressゲートウェイの共通およびコアアノテーションをサポートしており、ビジネスをKubernetesエコシステムに統合できます。 これにより、NGINX IngressゲートウェイからMSE Ingressゲートウェイへのシームレスな移行が容易になります。 MSE Ingressゲートウェイは、応答性を向上させるためのトラフィックガバナンスの追加アノテーションも提供します。

    概要

    Kubernetes標準で定義されているIngressリソースは、Transport Layer Security (TLS) 暗号化通信とレイヤー7 HTTPトラフィックの単純なルーティングのみを提供します。 ほとんどの場合、Ingressコントローラーは注釈を使用して、トラフィックガバナンスとセキュリティ保護の観点からIngress機能を強化します。

    サポートされているIngressアノテーション

    NGINX Ingressアノテーション

    NGINX IngressゲートウェイからMSE Ingressゲートウェイへのシームレスな移行を容易にするために、MSE IngressゲートウェイはほとんどのNGINX Ingressアノテーションをサポートしています。 次の表に、NGINX Ingressアノテーションのサポートステータスを示します。

    NGINX Ingressアノテーション

    注釈の総数

    説明

    サポートされる注釈

    51

    シナリオの90% に適しています。

    機能に影響を与えないアノテーション

    15

    設定は必要ありません。

    サポート対象の注釈

    48

    いくつかのシナリオでサポートされます。

    サポートされていない注釈

    5

    NGINX Ingressゲートウェイのコードスニペットに関与します。

    説明

    機能を実装するためのMSEのコードは、NGINXのコードとは異なります。

    1. MSEのNGINX Ingressアノテーションとコードスニペットで設定されているNGINX変数は、NGINXの変数と互換性がありません。

    2. NGINX Ingress Controllerでは、nginx.ingress.kubernetes.io/proxy-body-sizeアノテーションを使用して、クライアント要求本文の最大許容サイズを設定します。 リクエストボディが指定された制限を超えると、NGINXはエラーを報告します。 比較すると、MSEクラウドネイティブゲートウェイは、データ送信にチャンク転送エンコーディングを採用しています。 このアプローチは、リクエストボディのサイズを事前設定する必要なしに、大きなリクエストボディを自動的にチャンクに分割します。 大きなファイルを転送するには、MSEゲートウェイの [パラメーター設定] ウィンドウでDownstreamConnectionBufferLimitsパラメーターの設定を変更します。

    MSE Ingressアノテーション

    MSE Ingressゲートウェイは、トラフィックガバナンスのための追加の注釈を提供します。 次の表に、MSEによって提供される追加アノテーションのサポートステータスを示します。

    MSE Ingressアノテーション

    注釈の総数

    説明

    拡張アノテーション

    40

    NGINX Ingressアノテーションに加えて、MSE Ingressゲートウェイは、トラフィックガバナンスとセキュリティ保護を強化するための追加のアノテーションを提供します。

    スコープの説明

    • Ingress: このスコープのアノテーションは、使用するIngressリソースで定義されているルーティングルールに適用されます。

    • ドメイン名: このスコープの注釈は、使用するIngressリソースによって定義されたホストに適用されます。 このスコープは、他のIngressリソースの同じホストでも有効になります。

    • サービス: このスコープの注釈は、使用するIngressリソースによって定義されたサービスに適用されます。 注釈は、他のIngressリソースの同じサービスにも有効です。

    注釈プレフィックス

    MSE Ingressゲートウェイは、NGINX Ingressゲートウェイでサポートされている関連するアノテーションと同じ機能を持つアノテーションを提供します。 たとえば、nginx ingress Gatewayによって提供される注釈NGINX. ingress.kubernetes.io/xxxの機能は、mse ingress Gatewayによって提供される注釈MSE. Ingress. kubernetes.io/xxxの機能と同じです。 使用習慣に基づいて、nginxまたはmseビジネスドメインプレフィックスを使用できます。 ただし、mse Ingressゲートウェイによって排他的に提供されるアノテーションのMSEプレフィックスは、nginxプレフィックスに置き換えることはできません。

    サポートされる注釈

    このセクションでは、トラフィックガバナンスとセキュリティ保護の観点からサポートされている注釈について説明します。

    トラフィックガバナンス

    カナリアリリース

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io /カナリア

    Ingress

    互換性あり

    カナリアリリース機能を有効にするかどうかを指定します。

    nginx.ingress.kubernetes.io/canary-by-header

    Ingress

    互換性あり

    トラフィック分割に使用するリクエストヘッダーキーを指定します。

    nginx.ingress.kubernetes.io/canary-by-header-value

    Ingress

    互換性あり

    トラフィック分割に使用するリクエストヘッダー値を指定します。 リクエストヘッダー値の完全一致がサポートされています。

    nginx.ingress.kubernetes.io/canary-by-header-pattern

    Ingress

    互換性あり

    トラフィック分割に使用するリクエストヘッダー値を指定します。 リクエストヘッダー値では、正規表現の一致がサポートされています。

    mse.ingress.kubernetes.io/canary-by-query

    Ingress

    MSE-exclusive

    トラフィック分割に使用するURLクエリパラメーターを指定します。

    mse.ingress.kubernetes.io/canary-by-query-value

    Ingress

    MSE-exclusive

    トラフィック分割に使用するURLクエリパラメーターを指定します。 完全一致は、URLクエリパラメーター値でサポートされています。

    mse.ingress.kubernetes.io/canary-by-query-pattern

    Ingress

    MSE-exclusive

    トラフィック分割に使用するURLクエリパラメーターを指定します。 URLクエリパラメーター値では、正規表現の一致がサポートされています。

    nginx.ingress.kubernetes.io/canary-by-cookie

    Ingress

    互換性あり

    トラフィック分割に使用されるリクエストcookieキーを指定します。

    mse.ingress.kubernetes.io/canary-by-cookie-value

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.30

    トラフィック分割に使用されるリクエストcookie値を指定します。 リクエストcookie値の完全一致がサポートされています。

    nginx.ingress.kubernetes.io/canary-weight

    Ingress

    互換性あり

    トラフィック分割に使用されるサービスの重みを指定します。

    nginx.ingress.kubernetes.io/canary-weight-total

    Ingress

    互換性あり

    合計の重みを指定します。

    マルチサービス

    注釈

    スコープ

    サポート状況

    説明

    mse.ingress.kubernetes.io/destination

    Ingress

    MSE-exclusive

    ルートの重みベースのサービス分布を指定します。

    設定構文は {weight}% {serviceName}.{serviceNamespace}.svc.cluster.local:{port} です。

    説明

    • このアノテーションを設定すると、Ingressゲートウェイ上のすべてのルーティングルールの宛先サービスが、このアノテーションで指定されたサービスに変更されます。

    • このアノテーションの構成構文が要件を満たさない場合、このアノテーションは無視されます。 この場合、Ingressゲートウェイ上のすべてのルーティングルールの宛先サービスは変更されません。

    サンプル構文:

    annotations:
  # 60% of traffic is routed to the foo service and 40% of traffic is routed to the bar service. 
  mse.ingress.kubernetes.io/destination: |
    60% foo.default.svc.cluster.local:8080
    40% bar.default.svc.cluster.local:9090

    サービスサブセット

    注釈

    スコープ

    サポート状況

    説明

    mse.ingress.kubernetes.io/service-subset

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    サービスサブセットは、1つのサービスが複数の展開を管理するシナリオに適しています。 サービスサブセットは、Ingressの構成に基づいて要求が転送されるサービスポッドのサブセットです。

    • mse.ingress.kubernetes.io/subset-labelsアノテーションが設定されていない場合、リクエストはこのアノテーションの値に基づいて転送されます。

      • このアノテーションが "" またはbaseに設定されている場合、リクエストはラベルにopensergo.io/canary: "" が含まれているポッド、またはラベルキーの先頭にopensergo.io/canaryが付いていないポッドに転送されます。 このようにして、リクエストは空のラベルを持つポッドまたはラベルを持たないポッドに転送されます。

      • このアノテーションが "" またはbase以外の値に設定されている場合、リクエストはラベルがopensergo.io/canary-{指定値}: {指定値} を含むポッドに転送されます。 たとえば、このアノテーションをグレーに設定した場合、リクエストはラベルにopensergo.io/canary-gray: grayが含まれているポッドに転送されます。

    • mse.ingress.kubernetes.io/subset-labelsアノテーションが設定されている場合、リクエストは、mse.ingress.kubernetes.io/subset-labelsで定義されたKey:Valueをラベルが含むポッドにのみ転送されます。

    説明

    サービスに指定されたラベルのポッドが含まれていない場合、リクエストはサービスのすべてのポッドに自動的に転送されます。

    mse.ingress.kubernetes.io /サブセットラベル

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    必要に応じて、 このアノテーションをmse.ingress.kubernetes.io/service-subsetアノテーションと共に使用して、ポッドをサブセットに分類するために使用するラベルを指定できます。

    フォールバック

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io/default-backend

    Ingress

    互換性あり

    フォールバックサービスを指定します。 Ingressルールで定義されたサービスで使用できるノードがない場合、リクエストは自動的にフォールバックサービスに転送されます。

    nginx.ingress.kubernetes.io/custom-http-errors

    Ingress

    互換性あり

    このアノテーションは、nginx.ingress.kubernetes.io/default-backendアノテーションで機能します。 指定されたHTTPステータスコードがバックエンドサービスから返された場合、元の要求はフォールバックサービスに再度転送されます。

    重要

    リクエストがフォールバックサービスに転送されると、リクエストのパスはスラッシュ (/) に書き換えられます。 この動作は、NGINX Ingressゲートウェイに実装されている動作と一致しています。

    Regexマッチ

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io/use-regex

    Ingress

    互換性あり

    正規表現を使用して、Ingressで定義されたパスと一致させるかどうかを指定します。 正規表現はRE2構文を使用します。

    書き換え

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io /書き換え対象

    Ingress

    互換性あり

    書き換え操作の宛先パスを指定します。 キャプチャグループがサポートされています。

    nginx.ingress.kubernetes.io/upstream-vhost

    Ingress

    互換性あり

    書き換え先ホストを指定します。 IngressリソースのCustomResourceDefinition (CRD) と一致するルートリクエストがバックエンドサービスに転送された場合、システムはリクエストヘッダーのホスト値を指定された値に変更します。

    リダイレクト

    説明

    NGINXは、NGINX Ingressよりも幅広い機能を提供します。 リダイレクトのためのNGINX変数の使用は、いくつかのNGINX Ingressバージョンでサポートされ得る。 ただし、この機能についてはAnnotationsのドキュメントには記載されていません。 リダイレクトにNGINX変数を使用すると、非互換性の問題が発生する可能性があります。 NGINX IngressのリダイレクトにはNGINX変数を使用しないことを推奨します。

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io/ssl-リダイレクト

    Ingress

    互換性あり

    HTTPをHTTPSにリダイレクトするかどうかを指定します。

    nginx.ingress.kubernetes.io/force-ssl-redirect

    Ingress

    互換性あり

    HTTPを強制的にHTTPSにリダイレクトするかどうかを指定します。

    nginx.ingress.kubernetes.io/permanent-redirect

    Ingress

    互換性あり

    永久リダイレクトを指定します。

    nginx.ingress.kubernetes.io/permanent-redirect-code

    Ingress

    互換性あり

    永久リダイレクトに使用されるステータスコードを指定します。

    nginx.ingress.kubernetes.io /一時リダイレクト

    Ingress

    互換性あり

    一時的なリダイレクトを指定します。

    nginx.ingress.kubernetes.io/app-root

    Ingress

    互換性あり

    リダイレクトの宛先アプリケーションのルートパスを指定します。 このアノテーションは、指定されたパスから /へリクエストをリダイレクトするために使用されます。

    CORS

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io/enable-cors

    Ingress

    互換性あり

    クロスオリジンリソース共有 (CORS) を有効にするかどうかを指定します。

    nginx.ingress.kubernetes.io/cors-allow-origin

    Ingress

    互換性あり

    CORSに許可されるサードパーティのサイトを指定します。

    nginx.ingress.kubernetes.io/cors-allow-methods

    Ingress

    互換性あり

    CORSに許可されるリクエストメソッドを指定します。 許可されているリクエストメソッドには、GET、POST、およびPUTが含まれます。

    nginx.ingress.kubernetes.io/cors-allow-headers

    Ingress

    互換性あり

    CORSに許可されるリクエストヘッダーを指定します。

    nginx.ingress.kubernetes.io/cors-expose-headers

    Ingress

    互換性あり

    ブラウザーに公開される許可された応答ヘッダーを指定します。

    nginx.ingress.kubernetes.io/cors-allow-credentials

    Ingress

    互換性あり

    資格情報をCORSリクエストに含めることができるかどうかを指定します。

    nginx.ingress.kubernetes.io/cors-max-age

    Ingress

    互換性あり

    事前チェック結果がキャッシュされる最大期間を指定します。

    ヘッダー制御

    説明

    ベースルートに対して定義されたヘッダ制御関連の注釈およびカナリアルートに対して定義されたヘッダ制御関連の注釈は、互いに独立しており、別々に検証される。 ヘッダー制御機能を使用して、ベースルートのリクエストとカナリアルートのリクエストに対して異なるヘッダー制御ポリシーを設定できます。

    注釈

    スコープ

    サポート状況

    説明

    mse.ingress.kubernetes.io/request-header-control-add

    Ingress

    MSE-exclusive

    リクエストがバックエンドサービスに転送されるときにリクエストに追加されるヘッダーを指定します。 ヘッダーが存在する場合、その値は元の値の後に連結されます。 次の構文が使用されます。

    • シングルヘッダー: キーと値のペアが使用されます。

    • 複数のヘッダー: YAMLファイルの縦棒 (|) が使用されます。 各キーと値のペアは別々の行を占めます。

    mse.ingress.kubernetes.io/request-header-control-update

    Ingress

    MSE-exclusive

    リクエストがバックエンドサービスに転送されるときにリクエストで変更されるヘッダーを指定します。 ヘッダーが存在する場合、その値は元の値を上書きします。 次の構文が使用されます。

    • シングルヘッダー: キーと値のペアが使用されます。

    • 複数のヘッダー: YAMLファイルの縦棒 (|) が使用されます。 各キーと値のペアは別々の行を占めます。

    mse.ingress.kubernetes.io/request-header-control-remove

    Ingress

    MSE-exclusive

    リクエストがバックエンドサービスに転送されたときにリクエストから削除されるヘッダーを指定します。 次の構文が使用されます。

    • シングルヘッダー: キーが使用されます。

    • 複数のヘッダー: 複数のヘッダーはコンマ (,) で区切られています。

    mse.ingress.kubernetes.io/response-header-control-add

    Ingress

    MSE-exclusive

    応答がクライアントに転送される前に、バックエンドサービスから受信した応答に追加されるヘッダーを指定します。 ヘッダーが存在する場合、その値は元の値の後に連結されます。 次の構文が使用されます。

    • シングルヘッダー: キーと値のペアが使用されます。

    • 複数のヘッダー: YAMLファイルの縦棒 (|) が使用されます。 各キーと値のペアは別々の行を占めます。

    mse.ingress.kubernetes.io/response-header-control-update

    Ingress

    MSE-exclusive

    応答がクライアントに転送される前にバックエンドサービスから受信した応答で変更されるヘッダーを指定します。 ヘッダーが存在する場合、その値は元の値を上書きします。 次の構文が使用されます。

    • シングルヘッダー: キーと値のペアが使用されます。

    • 複数のヘッダー: YAMLファイルの縦棒 (|) が使用されます。 各キーと値のペアは別々の行を占めます。

    mse.ingress.kubernetes.io/response-header-control-remove

    Ingress

    MSE-exclusive

    応答がクライアントに転送される前に、バックエンドサービスから受信した応答から削除されるヘッダーを指定します。 次の構文が使用されます。

    • シングルヘッダー: キーが使用されます。

    • 複数のヘッダー: 複数のヘッダーはコンマ (,) で区切られています。

    タイムアウト

    注釈

    スコープ

    サポート状況

    説明

    mse.ingress.kubernetes.io /タイムアウト

    Ingress

    MSE-exclusive

    リクエストのタイムアウト期間を指定します。 単位は秒です。 デフォルトでは、タイムアウト期間は設定されていません。

    説明

    タイムアウト設定は、トランスポート層のTCPではなく、アプリケーション層に対して有効になります。

    再試行

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io/proxy-next-upstream-tries

    Ingress

    互換性あり

    リクエストの再試行の最大回数を指定します。 デフォルト値: 3。

    nginx.ingress.kubernetes.io/proxy-next-upstream-timeout

    Ingress

    互換性あり

    リクエストの再試行のタイムアウト期間を指定します。 単位は秒です。 デフォルトでは、タイムアウト期間は設定されていません。

    nginx.ingress.kubernetes.io/proxy-next-upstream

    Ingress

    互換性あり

    リトライ条件を指定します。 詳細については、「NGINXの再試行メカニズム」をご参照ください。

    トラフィックミラーリング

    注釈

    スコープ

    サポート状況

    説明

    mse.ingress.kubernetes.io/mirror-target-service

    Ingress

    MSE-exclusive

    ミラーリングされたトラフィックが転送される宛先サービスを指定します。 形式はnamespace/name:portです。

    • namespace: Kubernetesサービスが存在する名前空間。 このパラメーターはオプションです。 デフォルトの名前空間は、Ingressゲートウェイが存在する名前空間です。

    • name: Kubernetesサービスの名前。 This parameter is required.

    • port: ミラーリングされたトラフィックが転送されるKubernetesサービスポート。 このパラメーターはオプションです。 デフォルトでは、最初のポートが使用されます。

    mse.ingress.kubernetes.io /ミラーパーセンテージ

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.32

    ミラーリングされたトラフィックの割合を指定します。 有効な値: 0-100 デフォルト値：100

    ドメインエイリアス

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io/server-alias

    ドメイン

    • 部分互換性 (完全一致ドメインとワイルドカードドメインのみをサポート)

    • 必要なゲートウェイのバージョン: V1.2.30

    Ingress仕様で定義されているドメインエイリアスを指定します。 ドメインエイリアスは、ソースドメインのトランスポート層セキュリティ (TLS) 、ルーティング、およびトラフィックガバナンスに関連する設定を共有します。

    シングルゲートウェイ調整 (非推奨)

    注釈

    スコープ

    サポート状況

    説明

    mse.ingress.kubernetes.io/route-limit-rpm

    Ingress

    MSE-exclusive

    ゲートウェイでルーティングされる1分あたりの最大リクエスト数 (RPM) を指定します。 バースト制限は、指定された値にmse.ingress.kubernetes.io/route-limit-burst-multiplierを掛けた値に等しくなります。

    スロットリングがトリガーされると、応答本文の内容はlocal_rate_limitedになります。 応答ステータスコード:

    • ゲートウェイのバージョンがV1.2.23より前の場合、ステータスコード503が返されます。

    • ゲートウェイのバージョンがV1.2.23以降の場合、ステータスコード429が返されます。

    mse.ingress.kubernetes.io/route-limit-rps

    Ingress

    MSE-exclusive

    ゲートウェイでルーティングされる1秒あたりの最大リクエスト数 (RPS) を指定します。 バースト制限は、指定された値にmse.ingress.kubernetes.io/route-limit-burst-multiplierを掛けた値に等しくなります。

    スロットリングがトリガーされると、応答本文の内容はlocal_rate_limitedになります。 応答ステータスコード:

    • ゲートウェイのバージョンがV1.2.23より前の場合、ステータスコード503が返されます。

    • ゲートウェイのバージョンがV1.2.23以降の場合、ステータスコード429が返されます。

    mse.ingress.kubernetes.io/route-limit-burst-multiplier

    Ingress

    MSE-exclusive

    バースト制限の乗数を指定します。 既定値：5

    (推奨) グローバルスロットル制御

    注釈

    スコープ

    サポート状況

    説明

    mse.ingress.kubernetes.io/rate-limit

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    ゲートウェイでルーティングされるRPSの最大数を指定します。 このアノテーションはグローバルスロットリングに使用されます。

    mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    Ingressによって定義されたルートでスロットリングがトリガーされたときのレスポンスコードを指定します。 デフォルト値: 429

    説明

    このアノテーションは、mse.ingress.kubernetes.io/rate-limit-fallback-redirect-urlアノテーションと相互に排他的です。 2つのアノテーションのいずれかを指定する必要があります。

    mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    Ingressによって定義されたルートでスロットリングがトリガーされたときのレスポンスボディの形式を指定します。 デフォルト値: text。

    • このパラメーターがtextに設定されている場合、レスポンスのContent-Type値はtext/plain; charset=UTF-8です。

    • このパラメーターがJSONに設定されている場合、レスポンスのContent-Type値はapplication/json; charset=UTF-8です。

    mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    Ingressによって定義されたルートでスロットリングがトリガーされたときのレスポンスボディを指定します。 デフォルト値: センチネル率制限。

    mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    Ingressによって定義されたルートでスロットリングがトリガーされたときのリダイレクトURLを指定します。

    説明

    このアノテーションは、mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-codeアノテーションと相互に排他的です。 2つのアノテーションのいずれかを指定する必要があります。

    グローバル同時実行制御

    注釈

    スコープ

    サポート状況

    説明

    mse.ingress.kubernetes.io /同時実行制限

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    同時に処理できるリクエストの最大数を指定します。 このアノテーションは、ゲートウェイ内のルートのグローバル同時実行制御に使用されます。

    mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    Ingressによって定義されたルートで同時実行制御がトリガーされたときのレスポンスコードを指定します。 デフォルトの応答コードは429です。

    説明

    このアノテーションは、mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-urlアノテーションと相互に排他的です。 2つのアノテーションのいずれかを指定する必要があります。

    mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    Ingressによって定義されたルートが同時実行制御をトリガーするときのレスポンス本文の形式を指定します。 デフォルト値: text。

    • このパラメーターがtextに設定されている場合、レスポンスのContent-Type値はtext/plain; charset=UTF-8です。

    • このパラメーターがJSONに設定されている場合、レスポンスのContent-Type値はapplication/json; charset=UTF-8です。

    mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    Ingressによって定義されたルートが同時実行制御をトリガーするときのレスポンス本文を指定します。 デフォルト値: センチネル率制限。

    mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url

    Ingress

    • MSE-exclusive

    • 必要なゲートウェイのバージョン: V1.2.25

    Ingressによって定義されたルートが同時実行制御をトリガーする場合のリダイレクトURLを指定します。

    説明

    このアノテーションは、mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-codeアノテーションと相互に排他的です。 2つのアノテーションのいずれかを指定する必要があります。

    バックエンドプロトコル

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io/backend-protocol

    サービス

    部分的に互換性があります。 AJPとFCGIはサポートされていません。

    バックエンドサービスで使用されるプロトコルを指定します。 デフォルト値: HTTP。 有効な値：

    • HTTP

    • HTTP2

    • HTTPS

    • gRPC

    • gRPCS

    負荷分散

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io /ロードバランス

    サービス

    部分的に互換性があります。 指数加重移動平均 (EWMA) アルゴリズムはサポートされていません。 EWMAアルゴリズムを負荷分散アルゴリズムとして設定した場合、アルゴリズムはラウンドロビン負荷分散アルゴリズムにロールバックされます。

    バックエンドサービスで使用される一般的な負荷分散アルゴリズムを指定します。 デフォルト値はround_robinです。 有効な値：

    • round_robin: ラウンドロビン負荷分散アルゴリズム。

    • leung_conn: 最小接続ベースの負荷分散アルゴリズム。

    • random: ランダム化された負荷分散アルゴリズム。

    nginx.ingress.kubernetes.io/upstream-hash-by

    サービス

    部分的に互換性があります。 NGINX変数と定数の組み合わせはサポートされていません。

    コンシステントハッシュ負荷分散アルゴリズムを指定します。 MSE Ingressゲートウェイは、以下のタイプのコンシステントハッシングをサポートします。

    • NGINX変数に基づく一貫したハッシュ:

      • $request_uri: ハッシュキーとして使用されるリクエストパス。 パスパラメータが含まれています。

      • $host: ハッシュキーとして使用されるリクエストホスト。

      • $remote_addr: ハッシュキーとして使用されるクライアントのIPアドレス。

    • リクエストヘッダーに基づく一貫したハッシュ。 $http_headerNameのみを設定する必要があります。

    • 要求パスパラメータに基づく一貫したハッシュ。 $arg_varNameのみを設定する必要があります。

    サービスのプリフェッチ (graceful start)

    注釈

    スコープ

    サポート状況

    説明

    mse.ingress.kubernetes.io/warmup

    サービス

    MSE-exclusive

    サービスがプリフェッチされる期間を指定します。 単位は秒です。 デフォルトでは、サービスプリフェッチ機能は無効になっています。

    重要

    サービスプリフェッチは、選択した負荷分散アルゴリズムに依存します。 ラウンドロビンおよび最小接続に基づく負荷分散アルゴリズムのみがサポートされています。

    クッキー親和性

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io/affinity

    サービス

    互換性あり

    affinity型を指定します。 デフォルトの有効な値はcookieです。

    nginx.ingress.kubernetes.io/affinity-mode

    サービス

    部分的に互換性があります。 persistentモードはサポートされていません。

    affinityモードを指定します。 デフォルトおよび有効な値のみがバランスされます。

    nginx.ingress.kubernetes.io/session-cookie-name

    サービス

    互換性あり

    ハッシュキーとして使用されるcookieの名前を指定します。

    nginx.ingress.kubernetes.io/session-cookie-path

    サービス

    互換性あり

    指定されたcookieが存在しない場合に生成されるcookieのパスを指定します。 デフォルト値: /。

    nginx.ingress.kubernetes.io/session-cookie-max-age

    サービス

    互換性あり

    指定されたcookieが存在しない場合に生成されるcookieの有効期限を指定します。 単位は秒です。 デフォルトでは、このアノテーションはセッションレベルで指定されます。

    nginx.ingress.kubernetes.io/session-cookie-expires

    サービス

    互換性あり

    指定されたcookieが存在しない場合に生成されるcookieの有効期限を指定します。 単位は秒です。 デフォルトでは、このアノテーションはセッションレベルで指定されます。

    IPアドレスベースのアクセス制御

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io/whitelist-source-range

    Ingress

    互換性あり

    特定のルートのIPアドレスホワイトリストを指定します。 IPアドレスとCIDRブロックがサポートされています。 IPアドレスまたはCIDRブロックはコンマ (,) で区切ります。

    nginx.ingress.kubernetes.io/denylist-source-range

    Ingress

    • 互換性あり

    • 必要なゲートウェイのバージョン: V1.2.31

    特定のルートのIPアドレスブラックリストを指定します。 IPアドレスとCIDRブロックがサポートされています。 IPアドレスまたはCIDRブロックはコンマ (,) で区切ります。

    説明

    このアノテーションは、MSE排他的アノテーションmse.ingress.kubernetes.io/blacklist-source-rangeよりも優先されます。

    mse.ingress.kubernetes.io/blacklist-source-range

    Ingress

    MSE-exclusive

    特定のルートのIPアドレスブラックリストを指定します。 IPアドレスとCIDRブロックがサポートされています。 IPアドレスまたはCIDRブロックはコンマ (,) で区切ります。

    mse.ingress.kubernetes.io/domain-whitelist-source-range

    Ingress

    MSE-exclusive

    特定のドメイン名のIPアドレスホワイトリストを指定します。 ルートレベルのIPアドレスホワイトリストは、ドメイン名レベルのIPアドレスホワイトリストよりも優先されます。 IPアドレスとCIDRブロックがサポートされています。 IPアドレスまたはCIDRブロックはコンマ (,) で区切ります。

    mse.ingress.kubernetes.io /ドメイン-blacklist-source-range

    Ingress

    MSE-exclusive

    特定のドメイン名のIPアドレスブラックリストを指定します。 ルートレベルのIPアドレスブラックリストは、ドメイン名レベルのIPアドレスブラックリストよりも優先されます。 IPアドレスとCIDRブロックがサポートされています。 IPアドレスまたはCIDRブロックはコンマ (,) で区切ります。

    ゲートウェイとバックエンドサービス間の接続プールの設定

    注釈

    スコープ

    サポート状況

    説明

    mse.ingress.kubernetes.io/connection-policy-tcp-max-connection

    サービス

    MSE-exclusive

    ゲートウェイとバックエンドサービスの間に確立できる接続の最大数を指定します。

    mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint

    サービス

    MSE-exclusive

    ゲートウェイとバックエンドサービスの単一ノード間に確立できる接続の最大数を指定します。

    mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection

    サービス

    MSE-exclusive

    ゲートウェイとバックエンドサービス間の1つの接続でのリクエストの最大数を指定します。

    セキュリティ保護

    クライアントとゲートウェイ間の暗号化通信

    注釈

    スコープ

    サポート状況

    説明

    mse.ingress.kubernetes.io/tls-min-protocol-version

    ドメイン名

    MSE-exclusive

    TLSの最小バージョンを指定します。 デフォルト値: TLSv1.0。 有効な値：

    • TLSv1.0

    • TLSv1.1

    • TLSv1.2

    • TLSv1.3

    mse.ingress.kubernetes.io/tls-max-protocol-version

    ドメイン名

    MSE-exclusive

    TLSの最大バージョンを指定します。 デフォルト値: TLSv1.3. 有効な値：

    • TLSv1.0

    • TLSv1.1

    • TLSv1.2

    • TLSv1.3

    nginx.ingress.kubernetes.io/ssl-cipher

    ドメイン名

    互換性あり

    TLS暗号スイートを指定します。 カンマ (,) で区切られた複数のTLS暗号スイートを指定できます。 このパラメーターは、TLSハンドシェイク中にv1.0からv1.2までのTLSバージョンが使用されている場合にのみ有効です。

    デフォルトの暗号スイート:

    • ECDHE-ECDSA-AES128-GCM-SHA256

    • ECDHE-RSA-AES128-GCM-SHA256

    • ECDHE-ECDSA-AES128-SHA

    • ECDHE-RSA-AES128-SHA

    • AES128-GCM-SHA256

    • AES128-SHA

    • ECDHE-ECDSA-AES256-GCM-SHA384

    • ECDHE-RSA-AES256-GCM-SHA384

    • ECDHE-ECDSA-AES256-SHA

    • ECDHE-RSA-AES256-SHA

    • AES256-GCM-SHA384

    • AES256-SHA

    mse.ingress.kubernetes.io/auth-tls-secret

    ドメイン名

    部分的に互換性があります。 形式は、(ドメイン名証明書が属するシークレットの名前) -cacertである必要があります。

    ゲートウェイが相互TLS (mTLS) ハンドシェイク中にクライアントによって提供された証明書を検証するために使用するCA証明書を指定します。 この注釈は、ゲートウェイがクライアントのIDを検証する必要があるシナリオに適しています。

    ゲートウェイとバックエンドサービス間の暗号化された通信

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io/proxy-ssl-secret

    サービス

    互換性あり

    ゲートウェイによって使用されるクライアント証明書を指定します。 クライアント証明書は、バックエンドサービスがゲートウェイを認証するために使用されます。

    nginx.ingress.kubernetes.io/proxy-ssl-name

    サービス

    互換性あり

    TLSハンドシェイク中に使用されるサーバー名表示 (SNI) を指定します。

    nginx.ingress.kubernetes.io/proxy-ssl-server-name

    サービス

    互換性あり

    TLSハンドシェイク中に使用されるSNIを有効にするかどうかを指定します。

    認証

    Basic

    注釈

    スコープ

    サポート状況

    説明

    nginx.ingress.kubernetes.io/auth-type

    Ingress

    部分的に互換性があります。 基本認証タイプのみがサポートされています。

    認証タイプを指定します。

    nginx.ingress.kubernetes.io/auth-secret

    Ingress

    互換性あり

    シークレットの名前を指定します。 形式は <namespace>/<name> である必要があります。 シークレット名には、Ingressルールで定義されたルートへのアクセスを許可されたユーザー名とパスワードが含まれます。

    nginx.ingress.kubernetes.io/auth-secret-type

    Ingress

    互換性あり

    シークレットコンテンツの形式を指定します。 有効な値：

    • auth-file: データのキーはauthで、データの値はユーザー名とパスワードです。 各アカウントの情報は別々の行を占めます。

    • auth-map: データのキーはユーザー名で、データの値はパスワードです。

    nginx.ingress.kubernetes.io/auth-realm

    Ingress

    互換性あり

    認証レルムを指定します。 ユーザ名およびパスワードは、認証領域で共有される。

    NGINX Ingressアノテーションの詳細については、「アノテーション」をご参照ください。