APIG Ingress は、コアおよび一般的な Nginx Ingress のアノテーションをサポートしています。これにより、Nginx Ingress から APIG Ingress ゲートウェイへのシームレスな移行が可能になります。また、APIG Ingress は、Nginx Ingress のアノテーションではサポートされていないトラフィックガバナンス機能を提供するために、追加のアノテーションを導入しています。このトピックでは、APIG Ingress が現在サポートしているアノテーションについて説明します。
アノテーション機能の概要
標準の Kubernetes Ingress は、レイヤー 7 の HTTP トラフィックの基本的なルーティングと TLS 暗号化のみを提供します。Ingress コントローラーは通常、アノテーションを使用して Ingress のトラフィックガバナンスとセキュリティ保護機能を強化します。
Ingress アノテーションのサポート状況
Nginx Ingress アノテーション
Nginx Ingress ユーザーが APIG Ingress へシームレスに移行できるよう、APIG Ingress は Nginx Ingress のアノテーションを幅広くサポートしています。以下の表にサポート状況を示します。
Nginx Ingress アノテーション | サポート総数 | 注釈 |
サポートされるアノテーション | 51 | ユーザーシナリオの 90% をカバーします。 |
機能に影響しないアノテーション | 15 | 設定は不要です。 |
一時的にサポートされていないアノテーション | 48 | サポートは進行中です。これらは一部のシナリオでのみ使用されます。 |
サポートされていないアノテーション | 5 | 主に Nginx 固有のコードスニペットに関連します。 |
Higress と Nginx の実装は異なるため、いくつかの違いがあります。
Nginx Ingress アノテーションで NGINX 変数やコードスニペットを使用する設定には互換性がありません。
Nginx Ingress は、
nginx.ingress.kubernetes.io/proxy-body-sizeアノテーションを使用して、クライアントリクエストボディのサイズ制限を設定します。リクエストボディが指定されたサイズを超えた場合、Nginx はエラーを返します。Higress クラウドネイティブゲートウェイはチャンクストリーミングを使用するため、事前にリクエストボディのサイズを指定する必要はありません。大規模なファイル転送の場合、ゲートウェイインスタンスのパラメーター設定で `DownstreamConnectionBufferLimits` パラメーターを調整できます。
APIG Ingress アノテーション
APIG Ingress は、Nginx Ingress のアノテーションでは利用できない管理機能を提供するために、追加のアノテーションを導入しています。以下の表に現在のサポート状況を示します。
APIG Ingress アノテーション | サポート総数 | 注釈 |
拡張アノテーション | 40 | Nginx を超えるトラフィックガバナンスとセキュリティ保護機能を強化します。 |
スコープの定義
Ingress： Ingress スコープのアノテーションは、現在の Ingress で定義されているルーティングルールにのみ適用されます。
ドメイン名： ドメインスコープのアノテーションは、現在の Ingress で指定されているホストに適用されます。このスコープは、同じホストが指定されている他の Ingress にも影響します。
サービス： サービススコープのアノテーションは、現在の Ingress で指定されているサービスに適用されます。このスコープは、同じサービスが指定されている他の Ingress にも影響します。
アノテーションのプレフィックス
APIG Ingress は、すべての Nginx Ingress のアノテーションをサポートしています。たとえば、nginx.ingress.kubernetes.io/xxx は、higress.ingress.kubernetes.io/xxx と同じ効果があります。nginx または higress のいずれかのプレフィックスを使用できます。ただし、APIG Ingress 固有のアノテーションには nginx プレフィックスを使用できません。
アノテーションのサポート概要
このトピックでは、トラフィックガバナンスとセキュリティ保護の 2 つの主要モジュールについて説明します。
トラフィックガバナンス
カナリアリリース
アノテーション | スコープ | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/canary | 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 | 互換性あり |
|
higress.ingress.kubernetes.io/canary-by-query | Ingress | Higress 拡張 |
|
higress.ingress.kubernetes.io/canary-by-query-value | Ingress | Higress 拡張 |
|
higress.ingress.kubernetes.io/canary-by-query-pattern | Ingress | Higress 拡張 |
|
nginx.ingress.kubernetes.io/canary-by-cookie | Ingress | 互換性あり |
|
higress.ingress.kubernetes.io/canary-by-cookie-value | Ingress |
|
|
nginx.ingress.kubernetes.io/canary-weight | Ingress | 互換性あり | 重みに基づいてトラフィックを分割します。 |
nginx.ingress.kubernetes.io/canary-weight-total | Ingress | 互換性あり | 重みの合計です。 |
複数サービス
アノテーション | スコープ | サポートレベル | 説明 |
higress.ingress.kubernetes.io/destination | Ingress | Higress 拡張 | ルートの重みベースのサービス配信を設定します。 構文は 説明
|
構文例：
annotations:
# トラフィックの 60% が foo サービスに、40% が bar サービスにルーティングされます。
higress.ingress.kubernetes.io/destination: |
60% foo.default.svc.cluster.local:8080
40% bar.default.svc.cluster.local:9090サービスサブセット
アノテーション | スコープ | サポートレベル | 説明 |
higress.ingress.kubernetes.io/service-subset | Ingress |
| 1 つのサービスが複数のデプロイメントを管理するシナリオに適用されます。Ingress によって定義されたルートが、このサービス配下の Pod のサブセットに転送されるように指定します。
説明 サービスに指定されたラベルを持つ Pod がない場合、トラフィックはディザスタリカバリのためにサービス配下のすべての Pod に自動的にルーティングされます。 |
higress.ingress.kubernetes.io/subset-labels | Ingress |
| オプション。このアノテーションは |
フォールバック (ディザスタリカバリ)
アノテーション | スコープ | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/default-backend | Ingress | 互換性あり | ディザスタリカバリサービス。Ingress で定義されたサービスにアクティブなノードがない場合、リクエストはこのディザスタリカバリサービスに自動的に転送されます。 |
nginx.ingress.kubernetes.io/custom-http-errors | Ingress | 互換性あり | このアノテーションは 重要 リクエストがディザスタリカバリサービスに転送されると、リクエストパスは / に書き換えられます。これは |
正規表現一致
アノテーション | スコープ | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/use-regex | Ingress | 互換性あり | 正規表現一致。Ingress で定義されたパスが正規表現を使用して照合されることを示します。正規表現は RE2 構文を使用します。 |
書き換え
アノテーション | スコープ | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/rewrite-target | Ingress | 互換性あり | Ingress で定義された元のパスを指定されたターゲットに書き換えます。 |
nginx.ingress.kubernetes.io/upstream-vhost | Ingress | 互換性あり | Ingress で定義されたルートに一致するリクエストがバックエンドサービスに転送されるときに、Host ヘッダーが指定された値に変更されます。 |
リダイレクト
Nginx と Nginx Ingress の機能セットは異なります。Nginx はより広範な機能を提供します。Nginx Ingress の公式ドキュメントでは、NGINX 変数を使用したリダイレクトのサポートについては言及されていません。一部のバージョンの Nginx Ingress は NGINX 変数の設定をサポートしている場合がありますが、この機能は公式に文書化されていないため、互換性の問題を引き起こす可能性があります。Nginx Ingress で NGINX 変数を使用しないことを推奨します。
アノテーション | スコープ | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/ssl-redirect | 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/temporal-redirect | Ingress | 互換性あり | 一時的なリダイレクト。 |
nginx.ingress.kubernetes.io/app-root | Ingress | 互換性あり | アプリケーションルートパスを変更します。/ へのリクエストは新しいパスにリダイレクトされます。 |
クロスドメイン
アノテーション | スコープ | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/enable-cors | Ingress | 互換性あり | クロスドメインアクセスを有効または無効にします。 |
nginx.ingress.kubernetes.io/cors-allow-origin | Ingress | 互換性あり | 許可されたサードパーティサイト。 |
nginx.ingress.kubernetes.io/cors-allow-methods | Ingress | 互換性あり | 許可されたリクエストメソッド (GET、POST、PUT など)。 |
nginx.ingress.kubernetes.io/cors-allow-headers | Ingress | 互換性あり | 許可されたリクエストヘッダー。 |
nginx.ingress.kubernetes.io/cors-expose-headers | Ingress | 互換性あり | ブラウザに公開できる許可されたレスポンスヘッダー。 |
nginx.ingress.kubernetes.io/cors-allow-credentials | Ingress | 互換性あり | 認証情報を携帯することを許可するかどうかを指定します。 |
nginx.ingress.kubernetes.io/cors-max-age | Ingress | 互換性あり | プリフライト結果の最大キャッシュ期間。 |
ヘッダー制御
標準ルートで定義されたヘッダー制御アノテーションは、カナリアルートには適用されません。標準ルートとカナリアルートで定義されたヘッダー制御アノテーションは独立しており、それぞれ個別に有効になります。これにより、標準ルートとカナリアルートで異なるヘッダー操作ポリシーを設定できます。
アノテーション | スコープ | サポートレベル | 説明 |
higress.ingress.kubernetes.io/request-header-control-add | Ingress | Higress 拡張 | リクエストがバックエンドサービスに転送されるときに、指定されたヘッダーを追加します。ヘッダーが存在する場合、その値は元の値に追加されます。構文は次のとおりです：
|
higress.ingress.kubernetes.io/request-header-control-update | Ingress | Higress 拡張 | リクエストがバックエンドサービスに転送されるときに、指定されたヘッダーを変更します。ヘッダーが存在する場合、その値は元の値を上書きします。構文は次のとおりです：
|
higress.ingress.kubernetes.io/request-header-control-remove | Ingress | Higress 拡張 | リクエストがバックエンドサービスに転送されるときに、指定されたヘッダーを削除します。構文は次のとおりです：
|
higress.ingress.kubernetes.io/response-header-control-add | Ingress | Higress 拡張 | バックエンドサービスからのレスポンスをクライアントに転送する前に、指定されたヘッダーを追加します。ヘッダーが存在する場合、その値は元の値に追加されます。構文は次のとおりです：
|
higress.ingress.kubernetes.io/response-header-control-update | Ingress | Higress 拡張 | バックエンドサービスからのレスポンスをクライアントに転送する前に、指定されたヘッダーを変更します。ヘッダーが存在する場合、その値は元の値を上書きします。構文は次のとおりです：
|
higress.ingress.kubernetes.io/response-header-control-remove | Ingress | Higress 拡張 | バックエンドサービスからのレスポンスをクライアントに転送する前に、指定されたヘッダーを削除します。構文は次のとおりです：
|
タイムアウト
アノテーション | スコープ | サポートレベル | 説明 |
higress.ingress.kubernetes.io/timeout | Ingress | Higress 拡張 | リクエストタイムアウト期間 (秒)。デフォルトでは、タイムアウト期間は設定されていません。 説明 タイムアウト設定は、トランスポート層 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 リトライメカニズム」をご参照ください。 |
トラフィックミラーリング
アノテーション | スコープ | サポートレベル | 説明 |
higress.ingress.kubernetes.io/mirror-target-service | Ingress | Higress 拡張 | トラフィックをコピーして指定されたミラーサービスに転送します。サービスのフォーマットは namespace/name:port です。
|
higress.ingress.kubernetes.io/mirror-percentage | Ingress |
| コピーするトラフィックの割合。値の範囲は 0 から 100 です。デフォルトは 100 です。 |
ドメイン名エイリアス
アノテーション | スコープ | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/server-alias | ドメイン名 |
| Ingress 仕様に表示されるドメイン名のエイリアスを定義します。ドメイン名エイリアスは、ソースドメイン名の TLS、ルーティング、およびトラフィックガバナンス設定を共有します。 |
単一インスタンスの速度制限 (非推奨予定)
アノテーション | スコープ | サポートレベル | 説明 |
higress.ingress.kubernetes.io/route-limit-rpm | Ingress | Higress 拡張 | 各ゲートウェイインスタンス上のこの Ingress で定義されたルートの 1 分あたりの最大リクエスト数。瞬間的な最大リクエスト数は、この値に 速度制限がトリガーされると、レスポンスボディは
|
higress.ingress.kubernetes.io/route-limit-rps | Ingress | Higress 拡張 | 各ゲートウェイインスタンス上のこの Ingress で定義されたルートの 1 秒あたりの最大リクエスト数。瞬間的な最大リクエスト数は、この値に 速度制限がトリガーされると、レスポンスボディは
|
higress.ingress.kubernetes.io/route-limit-burst-multiplier | Ingress | Higress 拡張 | 瞬間的な最大リクエスト数の係数。デフォルトは 5 です。 |
グローバルな速度制限 (推奨)
アノテーション | スコープ | サポートレベル | 説明 |
higress.ingress.kubernetes.io/rate-limit | Ingress |
| ゲートウェイインスタンス上のこの Ingress で定義されたルートのグローバルな速度制限。これは 1 秒あたりの最大リクエスト数です。 |
higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-code | Ingress |
| この Ingress で定義されたルートで速度制限がトリガーされたときのレスポンスステータスコード。デフォルトは 429 です。 説明 このアノテーションは rate-limit-fallback-redirect-url と相互排他です。カスタムレスポンスまたはリダイレクトのいずれかを選択できます。 |
higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type | Ingress |
| この Ingress で定義されたルートで速度制限がトリガーされたときのレスポンスボディのフォーマット。デフォルトは text です。
|
higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body | Ingress |
| この Ingress で定義されたルートで速度制限がトリガーされたときのレスポンスボディ。デフォルトは `sentinel rate limited` です。 |
higress.ingress.kubernetes.io/rate-limit-fallback-redirect-url | Ingress |
| この Ingress で定義されたルートで速度制限がトリガーされたときのリダイレクトアドレス。 説明 このアノテーションは rate-limit-fallback-custom-response-code と相互排他です。リダイレクトまたはカスタムレスポンスのいずれかを選択できます。 |
グローバルな同時実行制御
アノテーション | スコープ | サポートレベル | 説明 |
higress.ingress.kubernetes.io/concurrency-limit | Ingress |
| ゲートウェイインスタンス上のこの Ingress で定義されたルートのグローバルな同時実行制御。これは処理中の瞬間的な最大リクエスト数です。 |
higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code | Ingress |
| この Ingress で定義されたルートで同時実行制御がトリガーされたときのレスポンスステータスコード。デフォルトは 429 です。 説明 このアノテーションは concurrency-limit-fallback-redirect-url と相互排他です。カスタムレスポンスまたはリダイレクトのいずれかを選択できます。 |
higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type | Ingress |
| この Ingress で定義されたルートで同時実行制御がトリガーされたときのレスポンスボディのフォーマット。デフォルトは text です。
|
higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body | Ingress |
| この Ingress で定義されたルートで同時実行制御がトリガーされたときのレスポンスボディ。デフォルトは `sentinel rate limited` です。 |
higress.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url | Ingress |
| この Ingress で定義されたルートで同時実行制御がトリガーされたときのリダイレクトアドレス。 説明 このアノテーションは concurrency-limit-fallback-custom-response-code と相互排他です。リダイレクトまたはカスタムレスポンスのいずれかを選択できます。 |
バックエンドサービスが使用するプロトコル
アノテーション | スコープ | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/backend-protocol | サービス | 部分的に互換性あり。AJP と FCGI はサポートされていません。 | バックエンドサービスが使用するプロトコルを指定します。デフォルトは HTTP です。サポートされている値は次のとおりです：
|
負荷分散
アノテーション | スコープ | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/load-balance | サービス | 部分的に互換性あり。 | バックエンドサービスの標準的な負荷分散アルゴリズム。デフォルトは
|
nginx.ingress.kubernetes.io/upstream-hash-by | サービス | 部分的に互換性あり。NGINX 変数と定数の組み合わせはサポートされていません。 | 一貫性ハッシュ負荷分散アルゴリズム。APIG Ingress は次の形式をサポートします：
|
サービスプリフェッチ (グレースフルスタート)
アノテーション | スコープ | サポートレベル | 説明 |
higress.ingress.kubernetes.io/warmup | サービス | Higress 拡張 | サービスのランプアップ期間 (秒)。デフォルトでは無効です。 重要 サービスプリフェッチは、選択された負荷分散アルゴリズムに依存します。現在、round_robin と least_conn のみがサポートされています。 |
Cookie アフィニティ
アノテーション | 機能 | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/affinity | サービス | 互換性あり | アフィニティタイプ。現在、Cookie のみがサポートされています。デフォルトは |
nginx.ingress.kubernetes.io/affinity-mode | サービス | 部分的に互換性あり。 | アフィニティモード。APIG Ingress は現在、Balanced モードのみをサポートしています。デフォルトは |
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 の有効期間 (TTL)。単位は秒です。デフォルトはセッションレベルです。 |
nginx.ingress.kubernetes.io/session-cookie-expires | サービス | 互換性あり | 指定された Cookie が存在しない場合に生成される Cookie の有効期間 (TTL)。単位は秒です。デフォルトはセッションレベルです。 |
IP アクセス制御
アノテーション | スコープ | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/whitelist-source-range | Ingress | 互換性あり | ルートの IP アドレスホワイトリストを指定します。IP アドレスまたは Classless Inter-Domain Routing (CIDR) ブロックをサポートし、コンマ (,) で区切ります。 |
nginx.ingress.kubernetes.io/denylist-source-range | Ingress |
| ルートの IP ブラックリストを指定します。IP アドレスまたは CIDR ブロックをサポートし、コンマ (,) で区切ります。 説明 このアノテーションは、Higress 拡張アノテーション higress.ingress.kubernetes.io/blacklist-source-range よりも優先度が高いです。 |
higress.ingress.kubernetes.io/blacklist-source-range | Ingress | Higress 拡張 | ルートの IP ブラックリストを指定します。IP アドレスまたは CIDR ブロックをサポートし、コンマ (,) で区切ります。 |
higress.ingress.kubernetes.io/domain-whitelist-source-range | Ingress | Higress 拡張 | ドメイン名の IP アドレスホワイトリストを指定します。ドメイン名はルートレベルよりも優先度が低いです。IP アドレスまたは CIDR ブロックをサポートし、コンマ (,) で区切ります。 |
higress.ingress.kubernetes.io/domain-blacklist-source-range | Ingress | Higress 拡張 | ドメイン名の IP ブラックリストを指定します。ドメイン名はルートレベルよりも優先度が低いです。IP アドレスまたは CIDR ブロックをサポートし、コンマ (,) で区切ります。 |
ゲートウェイとバックエンドサービス間の接続プール設定
アノテーション | スコープ | サポートレベル | 説明 |
higress.ingress.kubernetes.io/connection-policy-tcp-max-connection | サービス | Higress 拡張 | ゲートウェイとバックエンドサービス間で確立できる最大接続数。 |
higress.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint | サービス | Higress 拡張 | ゲートウェイとバックエンドサービスの単一ノード間で確立できる最大接続数。 |
higress.ingress.kubernetes.io/connection-policy-http-max-request-per-connection | サービス | Higress 拡張 | ゲートウェイとバックエンドサービス間の単一接続での最大リクエスト数。 |
セキュリティ保護
クライアントとゲートウェイ間の暗号化通信
アノテーション | スコープ | サポートレベル | 説明 |
higress.ingress.kubernetes.io/tls-min-protocol-version | ドメイン名 | Higress 拡張 | 最小 TLS バージョンを指定します。デフォルトは TLSv1.0 です。有効な値は次のとおりです：
|
higress.ingress.kubernetes.io/tls-max-protocol-version | ドメイン名 | Higress 拡張 | 最大 TLS バージョンを指定します。デフォルトは TLSv1.3 です。有効な値は次のとおりです：
|
nginx.ingress.kubernetes.io/ssl-cipher | ドメイン名 | 互換性あり | TLS 暗号スイートを指定します。複数の暗号スイートをコロン (:) で区切って指定できます。これは、TLS ハンドシェイクに TLSv1.0-1.2 が使用される場合にのみ有効です。 デフォルトの暗号スイートは次のとおりです：
|
higress.ingress.kubernetes.io/auth-tls-secret | ドメイン名 | 部分的に互換性あり。Secret 名は次の形式である必要があります： (ドメイン証明書が格納されている Secret の名前) | mTLS ハンドシェイク中にクライアントが提供する証明書をゲートウェイが検証するために使用する CA 証明書。このアノテーションは、主にゲートウェイがクライアント ID を検証する必要があるシナリオで使用されます。 |
ゲートウェイとバックエンドサービス間の暗号化通信
アノテーション | スコープ | サポートレベル | 説明 |
nginx.ingress.kubernetes.io/proxy-ssl-secret | サービス | 互換性あり | バックエンドサービスによる ID 認証のためにゲートウェイが使用するクライアント証明書。 |
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 | 部分的に互換性あり。Basic のみがサポートされています。 | 認証タイプ。 |
nginx.ingress.kubernetes.io/auth-secret | Ingress | 互換性あり | Secret 名。フォーマット |
nginx.ingress.kubernetes.io/auth-secret-type | Ingress | 互換性あり | Secret のコンテンツフォーマット。
|
nginx.ingress.kubernetes.io/auth-realm | Ingress | 互換性あり | 保護ドメイン。同じ保護ドメインはユーザー名とパスワードを共有します。 |
Nginx Ingress のアノテーションに関する詳細については、「公式ドキュメント」をご参照ください。