ユーザー定義のリクエスト ヘッダーの作成

ユーザー定義のリクエスト ヘッダーを使用すると、ヘッダーをさらに追加し、ロードバランサによってリクエストに追加できます。これらのヘッダーには、クライアントへのレイテンシ、クライアントの IP アドレスの地理的なロケーション、TLS 接続のパラメータなど、クライアント接続に関してロードバランサで認識されている情報を含めることができます。

ユーザー定義のリクエスト ヘッダーは、HTTP(S) ロードバランサに関連付けられたバックエンド サービスでサポートされます。

HTTP(S) ロードバランサは、バックエンドにプロキシするすべての HTTP リクエストにデフォルトで特定のヘッダーを追加します。詳細については、ターゲット プロキシをご覧ください。

ユーザー定義のリクエスト ヘッダーの仕組み

ユーザー定義のリクエスト ヘッダーを有効にするには、バックエンド サービス リソースのプロパティにヘッダーのリストを指定します。ロードバランサは、バックエンドに転送するリクエストにヘッダーを追加します。

各ヘッダーを header-name:header-value 文字列として指定します。ヘッダーには、ヘッダー名とヘッダー値を区切るコロンを含める必要があります。ヘッダー名のプロパティは次のとおりです。

  • ヘッダー名は、HTTP ヘッダー フィールドで有効な定義でなければなりません(RFC 7230 に準拠、古いフォームは使用不可)。
  • ヘッダー名を X-User-IP にすることはできません。X-Google または X-GFE で開始することもできません。
  • 追加されたヘッダーのリストに、ヘッダー名を複数回使用することはできません。

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

  • ヘッダー値は、HTTP ヘッダー フィールドで有効な定義でなければなりません(RFC 7230 に準拠、古いフォームは使用不可)。
  • ヘッダー値は空白にできます。
  • ヘッダー値には、中括弧で囲まれた 1 つ以上の変数を含めることができます。この変数は、ロードバランサで提供される値に展開されます。ヘッダー値に使用できる変数のリストについては、次のセクションで説明します。

たとえば、クライアントのリージョンとクライアントの都市に対して、2 つの変数名を含む 1 つのヘッダーを指定できます。gcloud コマンドライン ツールには、リクエスト ヘッダーを指定するフラグ --custom-request-header があります。例:

        --custom-request-header 'X-Client-Geo-Location:{client_region},{client_city}'
    

カリフォルニア州のマウンテン ビューに存在するクライアントの場合、ロードバランサにより次のようなヘッダーが追加されます。

X-Client-Geo-Location:US,Mountain View

フラグの一般的な形式は次のとおりです。

        --custom-request-header='HEADER_NAME:[HEADER_VALUE]'
    

ヘッダー値は中かっこで囲む必要があります。例:

        --custom-request-header='X-PLACE:{client_city},{client_city_lat_long}'
    

このコマンドでは一重引用符(')のみ使用してください。

カスタム リクエスト ヘッダーの構成の詳細については、ユーザー定義リクエスト ヘッダーの処理をご覧ください。

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

リクエスト ヘッダー値には、次の変数を使用できます。

変数 説明
client_rtt_msec ロードバランサと HTTP(S) クライアント間の推定ラウンドトリップ送信時間(ミリ秒単位)。これは、ロードバランサの TCP スタックによって測定される平滑化されたラウンドトリップ時間(SRTT)パラメータです(RFC 2988 に準拠)。
client_region クライアントの IP アドレスに関連付けられる国(またはリージョン)。これは「US」や「FR」などの Unicode CLDR リージョン コードです(ほとんどの国では、これらのコードは ISO-3166-2 コードに直接対応しています)。
client_region_subdivision 都道府県や州など、クライアントの IP アドレスに関連付けられる国の下位地域区分。これは Unicode の CLDR サブディビジョン ID です。たとえば、「USCA」や「CAON」です(これらの Unicode コードは、ISO-3166-2 標準で定義されている下位地域区分から派生しています)。
client_city リクエスト送信元の市区町村の名前。たとえば、Mountain View はカリフォルニア州マウンテンビューを表します。この変数について有効な値の正規リストはありません。市区町村名には US-ASCII 文字、数字、スペース、!#$%&'*+-.^_`|~ を使用できます。
client_city_lat_long リクエストの送信元である都市の緯度と経度。たとえば、マウンテン ビューからのリクエストの場合には「37.386051,-122.083851」となります。
tls_sni_hostname RFC 6066 で定義されたサーバー名表示(TLS または QUIC handshake 中にクライアントによって提供された場合)。ホスト名は小文字に変換され、末尾のドットはすべて削除されます。
tls_version SSL handshake 中にクライアントとロードバランサの間でネゴシエートされた TLS バージョン。使用可能な値は、「TLSv1」、「TLSv1.1」、「TLSv1.2」があり、クライアントが TLS ではなく QUIC を使用して接続された場合には「QUIC」となります。
tls_cipher_suite TLS handshake 中にネゴシエートされた暗号スイート。値は、IANA TLS Cipher Suite Registry で定義された 4 桁の 16 進数です。たとえば、TLS_RSA_WITH_AES_128_GCM_SHA256 の場合には「009C」となります。この値は、QUIC と暗号化されていないクライアント接続の場合には空です。

IP アドレスのロケーションが不明な場合の地理的なロケーションの変数や、TLS が使用されていない場合の TLS パラメータなど、ロードバランサで値を決定できない場合、変数は空の文字列に展開されます。

地理的な値(リージョン、下位地域区分、都市)は、クライアントの IP アドレスに基づく推定値です。Google では、正確性を高め、地理的、政治的な変化を反映させるため、これらの値を提供するデータを更新しています。

ロードバランサによって追加されたヘッダーにより、同じ名前の既存のヘッダーはすべて上書きされます。ヘッダー名では、大文字と小文字は区別されません。ヘッダー名が HTTP/2 バックエンドに渡されると、HTTP/2 プロトコルによりヘッダー名は小文字としてエンコードされます。

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

ユーザー定義のリクエスト ヘッダーの操作

ユーザー定義のリクエスト ヘッダーには、次の制限が適用されます。

  • バックエンド サービスごとに、最大 16 個のカスタム リクエスト ヘッダーを指定できます。
  • バックエンド サービスごとのすべてのユーザー定義リクエスト ヘッダーの合計サイズ(変数を展開する前の名前と値の組み合わせ)は、8 KB を超えることはできません。

Console

既存のバックエンド サービスにカスタム リクエスト ヘッダーを追加するには:

  1. 負荷分散の概要ページに移動します。
    [負荷分散] ページに移動
  2. [バックエンド] をクリックします。
  3. バックエンド サービスの名前をクリックします。
  4. [編集] 鉛筆アイコンをクリックします。
  5. [高度な構成(セッション アフィニティ、接続ドレインのタイムアウト、セキュリティ ポリシー)] をクリックします。
  6. [カスタム リクエスト ヘッダー] で、[ヘッダーを追加] をクリックします。
  7. カスタム リクエスト ヘッダーのヘッダー名ヘッダー値を入力します。
  8. その他のカスタム リクエスト ヘッダーを入力します。
  9. [保存] をクリックします。

カスタム リクエスト ヘッダーをバックエンド サービスから削除するには:

  1. 負荷分散の概要ページに移動します。[負荷分散] ページに移動
  2. [バックエンド] をクリックします。
  3. バックエンド サービスの名前をクリックします。
  4. [編集] 鉛筆アイコンをクリックします。
  5. [高度な構成(セッション アフィニティ、接続ドレインのタイムアウト、セキュリティ ポリシー)] をクリックします。
  6. 削除するカスタム リクエスト ヘッダーの名前の横にある X をクリックします。
  7. [保存] をクリックします。

gcloud

ユーザー定義のリクエスト ヘッダーを使用してバックエンド サービスを作成するには:

    gcloud compute backend-services create NAME \
      --global \
      --protocol HTTPS \
      --https-health-check https-basic-check \
      --custom-request-header 'HEADER_NAME:[HEADER_VALUE]'
    

リクエスト ヘッダーをさらに追加するには、--custom-request-header フラグを繰り返して、固有のヘッダー名と値を指定します。

既存のバックエンド サービスにユーザー定義のリクエスト ヘッダーを追加するには:

    gcloud compute backend-services update NAME \
      --global \
      --custom-request-header 'HEADER_NAME:[HEADER_VALUE]' \
      --custom-request-header 'HEADER_NAME:[HEADER_VALUE]'
    

上記では、コマンドで指定したリクエスト ヘッダーでバックエンド サービス内のヘッダーを置き換えています。

バックエンド サービスからすべてのヘッダーを削除するには:

    gcloud compute backend-services update NAME \
      --global \
      --no-custom-request-headers
    

API

backendServices.patch メソッドに PATCH リクエストを送信します。

PATCH https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/backendServices/[BACKEND_SERVICE_NAME]
    "customRequestHeaders": [
      "client_city:Mountain View"
    ]
    

次のステップ