URL マップでカスタム ヘッダーを作成する

このページでは、リージョン外部アプリケーション ロードバランサ、リージョン内部アプリケーション ロードバランサ、クロスリージョン内部アプリケーション ロードバランサで使用される URL マップでカスタム ヘッダーがどのように機能するかについて説明します。

カスタム リクエスト ヘッダーとカスタム レスポンス ヘッダーを使用すると、ロードバランサが HTTP(S) のリクエストとレスポンスに追加できる追加のヘッダーを指定できます。ロードバランサで検出された情報に応じて、これらのヘッダーには次の情報が含まれます。

• クライアントまでのレイテンシ
• クライアントの IP アドレスの地理的位置
• TLS 接続のパラメータ

始める前に

必要に応じて、次のコマンドで Google Cloud CLI を最新バージョンに更新します。

gcloud components update

カスタム ヘッダーの動作

カスタム ヘッダーは次のように動作します。

• ロードバランサがバックエンドにリクエストを行うと、ロードバランサはリクエスト ヘッダーを追加します。

  ロードバランサは、カスタム リクエスト ヘッダーをクライアント リクエストにのみ追加します。ヘルスチェック プローブには追加しません。バックエンドで認可に特定のヘッダーが必要であり、ヘルスチェック パケットにヘッダーが含まれていない場合、ヘルスチェックが失敗する可能性があります。

• ロードバランサはレスポンス ヘッダーを設定してから、クライアントにレスポンスを返します。

リージョン外部アプリケーション ロードバランサ、リージョン内部アプリケーション ロードバランサ、クロスリージョン内部アプリケーション ロードバランサでカスタム ヘッダーを有効にするには、URL マップ構成でヘッダー名とヘッダー値のリストを指定します。

ヘッダー名のプロパティは次のとおりです。

• ヘッダー名は、有効な HTTP ヘッダー フィールド名の定義でなければなりません（RFC 7230 に遵守）。
• ヘッダー名を X-User-IP にすることはできません。
• ヘッダー名を X-Google、X-Goog-、X-GFE、または X-Amz- で始めることはできません。
• ヘッダー名を Host または authority にすることはできません。Host と authority はどちらも Google Cloud が予約する特殊なキーワードです。これらのヘッダーは Envoy ベースのロードバランサでは変更できません。代わりに、予約されたヘッダー名が干渉しないように、他のカスタム ヘッダー（MyHost など）を作成することをおすすめします。
• ヘッダーのリストに、ヘッダー名を複数回使用することはできません。

ヘッダー名では、大文字と小文字は区別されません。ヘッダー名が HTTP/2 バックエンドに渡されると、HTTP/2 プロトコルによりヘッダー名は小文字としてエンコードされます。

ヘッダー値のプロパティは次のとおりです。

• ヘッダー値は、HTTP ヘッダー フィールドで有効な定義でなければなりません（RFC 7230 に準拠、古いフォームは使用不可）。
• ヘッダー値は空白にできません。空白のヘッダーは拒否されます。
• ヘッダー値には、中括弧で囲まれた 1 つ以上の変数を含めることができます。この変数は、ロードバランサで提供される値に展開されます。ヘッダー値で使用できる変数の一覧については、ヘッダー値に表示できる変数をご覧ください。

ヘッダー値では、先頭の空白と末尾の空白は重要ではなく、バックエンドには渡されません。ヘッダー値で中括弧を許可するために、ロードバランサでは 2 つの左中括弧（{{）を単一の左中括弧（{）に変換し、2 つの右中括弧（}}）を単一の右中括弧（}）に変換します。

リクエスト ヘッダーまたはレスポンス ヘッダーを追加する

リクエスト ヘッダーまたはレスポンス ヘッダーを追加するには、gcloud CLI を使用して URL マップを次のように編集します。

    gcloud compute url-maps edit URL_MAP_NAME \
        --region=REGION
    

   defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1
   name: regional-lb-map
   region: region/REGION
   hostRules:
   - hosts:
     - '*'
     pathMatcher: matcher1
   pathMatchers:
   - defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1
     name: matcher1
     routeRules:
       - matchRules:
           - prefixMatch: /PREFIX
         priority: PRIORITY # 0 is highest
         routeAction:
           weightedBackendServices:
             - backendService: regions/REGION/backendServices/BACKEND_SERVICE_1
               weight: 100
               headerAction:
                 requestHeadersToAdd:
                 - headerName: X-header-1-client-region
                   headerValue: "{client_region}"
                 - headerName: X-header-2-client-ip-port
                   headerValue: "{client_ip_address}, {client_port}"
                   replace: True
                 requesteHeadersToRemove:
                 - header-3-name
                 responseHeadersToAdd:
                 - headerName: X-header-4-server-ip-port
                   headerValue: "{server_ip_address}, {server_port}"
                   replace: True
                 responseHeadersToRemove:
                 - header-5-name
                 - header-6-name
    

    gcloud compute url-maps edit URL_MAP_NAME \
        --global
    

   defaultService: global/backendServices/BACKEND_SERVICE_1
   name: global-lb-map
   hostRules:
   - hosts:
     - '*'
     pathMatcher: matcher1
   pathMatchers:
   - defaultService: global/backendServices/BACKEND_SERVICE_1
     name: matcher1
     routeRules:
       - matchRules:
           - prefixMatch: /PREFIX
         priority: PRIORITY # 0 is highest
         routeAction:
           weightedBackendServices:
             - backendService: global/backendServices/BACKEND_SERVICE_1
               weight: 100
               headerAction:
                 requestHeadersToAdd:
                 - headerName: X-header-1-client-region
                   headerValue: "{client_region}"
                 - headerName: X-header-2-client-ip-port
                   headerValue: "{client_ip_address}, {client_port}"
                   replace: True
                 requesteHeadersToRemove:
                 - header-3-name
                 responseHeadersToAdd:
                 - headerName: X-header-4-server-ip-port
                   headerValue: "{server_ip_address}, {server_port}"
                   replace: True
                 responseHeadersToRemove:
                 - header-5-name
                 - header-6-name
    

次の動作に注意してください。

• カスタム変数を含むレスポンス ヘッダーが空の文字列に解決されると、削除されます。
• カスタム変数のリクエスト ヘッダーが空の文字列に解決されると、空の文字列プレースホルダで保持されます。
• カスタム リクエスト ヘッダーにカスタム変数が含まれ、受信クライアント リクエストに同じヘッダーが含まれている場合、クライアント リクエスト ヘッダーの値は、ロードバランサのカスタム ヘッダーによって提供された新しい値に置き換えられます。

ヘッダー値に使用可能な変数

カスタム ヘッダー値には、以下の変数を使用できます。

ロードバランサで値を決定できない場合、変数は空の文字列に展開されます。例:

• IP アドレスのロケーションが不明な場合の地理的なロケーションの変数
• TLS が使用されていない場合の TLS パラメータ
• リクエストに Origin ヘッダーが含まれていない場合の {origin_request_header}

地理的な値は、クライアントの IP アドレスに基づく推定値です。Google では、正確性を高め、地理的、政治的な変化を反映させるため、これらの値を提供するデータを随時更新しています。元の X-Forwarded-For ヘッダーに有効な位置情報が含まれている場合でも、Google はロードバランサで受信したパケットに含まれる送信元 IP アドレス情報を使用して、クライアントの位置を推定します。

相互 TLS カスタム ヘッダー

ロードバランサの TargetHttpsProxy で相互 TLS（mTLS）が構成されている場合、次の追加のヘッダー変数を使用できます。

制限事項

リージョン ロードバランサで使用されるカスタム ヘッダーには、次の制限が適用されます。

• リージョン外部アプリケーション ロードバランサで使用されるリージョン バックエンド サービス、リージョン内部アプリケーション ロードバランサ、クロスリージョン内部アプリケーション ロードバランサで使用されるグローバル バックエンド サービスにカスタム ヘッダーを構成することはできません。
• 次のカスタム ヘッダー変数は、リージョン外部アプリケーション ロードバランサではサポートされていません。
  • cdn_cache_id
  • cdn_cache_status
  • client_region_subdivision
  • client_city
  • client_city_lat_long