Microservices Engine:MSE Ingress ゲートウェイでサポートされるアノテーション

スコープ

各アノテーションは、以下の 3 つのレベルのいずれかで適用されます：

プレフィックス

MSE Ingress ゲートウェイは、互換性のあるアノテーションに対して nginx.ingress.kubernetes.io/ と mse.ingress.kubernetes.io/ の両方のプレフィックスを受け入れます。お好みに応じていずれかのプレフィックスを使用してください。

MSE 専用のアノテーションは mse.ingress.kubernetes.io/ プレフィックスのみをサポートします。

アノテーション値のフォーマット

Kubernetes のアノテーションは常に文字列です。以下のエンコーディング規則が適用されます：

優先順位とインタラクションルール

互換性に関する注意事項

• NGINX 変数：MSE は NGINX とは異なる方法で機能を実装しています。アノテーションやコードスニペットで設定された NGINX 変数は、MSE と互換性がありません。

• proxy-body-size の動作：MSE クラウドネイティブゲートウェイはチャンク転送エンコーディングを使用しており、大きなリクエストボディを自動的にチャンクに分割します。大きなファイルの転送を処理するには、ご利用の MSE ゲートウェイの [パラメーター設定] で DownstreamConnectionBufferLimits パラメーターを調整してください。

カナリアリリース

# カナリアリリース：ヘッダー値に基づいてトラフィックをルーティング
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: canary-ingress
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "x-canary"
    nginx.ingress.kubernetes.io/canary-by-header-value: "true"
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: my-service-canary
                port:
                  number: 80

複数サービスへのルーティング

重み付けディストリビューションを使用して、複数のバックエンドサービスにトラフィックをルーティングします。

構文： {weight}% {serviceName}.{serviceNamespace}.svc.cluster.local:{port}

annotations:
  # トラフィックの 60% を foo に、40% を bar にルーティング
  mse.ingress.kubernetes.io/destination: |
    60% foo.default.svc.cluster.local:8080
    40% bar.default.svc.cluster.local:9090

このアノテーションを設定すると、Ingress 上のすべてのルーティングルールが指定されたサービスに向けられます。構文が無効な場合、アノテーションは無視され、元のルーティングルールは変更されません。

サービスサブセット

1 つのサービスが複数のデプロイメントを管理する場合に便利な、サービス内の Pod のサブセットにトラフィックをルーティングします。

service-subset がトラフィックをルーティングする方法：

• subset-labels が設定されていない場合：

  • "" または base に設定：opensergo.io/canary: "" というラベルが付いた Pod、または opensergo.io/canary ラベルキーがない Pod にルーティングします。

  • その他の値 (例：gray) に設定：opensergo.io/canary-gray: gray というラベルが付いた Pod にルーティングします。

• subset-labels が設定されている場合：subset-labels で定義されたキーと値のペアに一致するラベルを持つ Pod にのみルーティングします。

指定されたラベルに一致する Pod がない場合、トラフィックは自動的にサービス内のすべての Pod にルーティングされます。

annotations:
  # "gray" サブセットとしてラベル付けされた Pod にトラフィックをルーティング
  mse.ingress.kubernetes.io/service-subset: "gray"

フォールバック

正規表現一致

書き換え

リダイレクト

一部の NGINX Ingress バージョンではリダイレクトに NGINX 変数をサポートしていますが、これは公式の アノテーションリファレンスには記載されておらず、互換性の問題を引き起こす可能性があります。リダイレクトに NGINX 変数を使用しないでください。

CORS

ヘッダー制御

ゲートウェイレベルでリクエストヘッダーとレスポンスヘッダーを操作します。ベースルートとカナリアルートのヘッダー制御アノテーションは独立しています。それぞれに異なるヘッダーポリシーを設定してください。

リクエストヘッダー：

レスポンスヘッダー：

追加および更新アノテーションの構文：

• 単一ヘッダー：key value

• 複数ヘッダー：YAML パイプ (|) を使用し、1 行に 1 つのキーと値のペアを記述します。

削除アノテーションの構文：

• 単一ヘッダー：key

• 複数ヘッダー：カンマ (,) で区切ります。

annotations:
  # リクエストにカスタムヘッダーを追加
  mse.ingress.kubernetes.io/request-header-control-add: "x-request-id 12345"
  # レスポンスに複数のヘッダーを追加
  mse.ingress.kubernetes.io/response-header-control-add: |
    x-custom-header value1
    x-another-header value2
  # レスポンスからヘッダーを削除
  mse.ingress.kubernetes.io/response-header-control-remove: "x-powered-by,server"

タイムアウト

このタイムアウトは TCP トランスポート層ではなく、アプリケーション層で適用されます。

annotations:
  mse.ingress.kubernetes.io/timeout: "30"

リトライ

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

mirror-target-service パラメーター：

annotations:
  # トラフィックの 50% をシャドウサービスにミラーリング
  mse.ingress.kubernetes.io/mirror-target-service: "default/shadow-service:8080"
  mse.ingress.kubernetes.io/mirror-percentage: "50"

ドメインエイリアス

レート制限

annotations:
  # 100 RPS に制限し、カスタム JSON レスポンスを返す
  mse.ingress.kubernetes.io/rate-limit: "100"
  mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code: "429"
  mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type: "JSON"
  mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body: '{"error":"rate limit exceeded"}'

同時実行制御

グローバル同時実行制御は、ルートで同時に処理されるリクエストの数を制限します。

annotations:
  # 50 の同時リクエストに制限し、オーバーフロー時にリダイレクト
  mse.ingress.kubernetes.io/concurrency-limit: "50"
  mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url: "https://example.com/busy"

バックエンドプロトコル

負荷分散

サポートされている一貫性ハッシュメソッド：

• NGINX 変数：$request_uri (パラメーターを含むリクエストパス)、$host (リクエストホスト)、$remote_addr (クライアント IP アドレス)

• リクエストヘッダー：$http_headerName

• リクエストパスパラメーター：$arg_varName

グレースフルスタート (サービスプリフェッチ)

annotations:
  # 新しい Pod を 60 秒かけてウォームアップ
  mse.ingress.kubernetes.io/warmup: "60"

Cookie アフィニティ

IP アクセス制御

優先順位ルール：

• ルートレベルの IP リストはドメインレベルの IP リストより優先されます。

• nginx.ingress.kubernetes.io/denylist-source-range は mse.ingress.kubernetes.io/blacklist-source-range より優先されます。

annotations:
  # ルートレベルで特定の IP のみを許可
  nginx.ingress.kubernetes.io/whitelist-source-range: "10.0.0.0/8,192.168.1.100"

ゲートウェイとバックエンド間の接続プール

annotations:
  # バックエンドへの接続プールを制限
  mse.ingress.kubernetes.io/connection-policy-tcp-max-connection: "1024"
  mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint: "100"
  mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection: "500"

クライアントとゲートウェイ間の 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

annotations:
  # 最小 TLS 1.2 を強制
  mse.ingress.kubernetes.io/tls-min-protocol-version: "TLSv1.2"
  mse.ingress.kubernetes.io/tls-max-protocol-version: "TLSv1.2"

ゲートウェイとバックエンド間の TLS

認証

annotations:
  # Kubernetes シークレットによる基本認証
  nginx.ingress.kubernetes.io/auth-type: "basic"
  nginx.ingress.kubernetes.io/auth-secret: "default/my-auth-secret"
  nginx.ingress.kubernetes.io/auth-secret-type: "auth-file"
  nginx.ingress.kubernetes.io/auth-realm: "Protected Area"