ext-proc ベースのバックエンド サービスにプラグインまたはコールアウトを使用して拡張機能を構成する場合は、これらのサービスに転送するリクエスト属性と接続属性を指定できます。このページでは、サポートされている属性について説明し、各拡張機能タイプで使用できる属性を指定します。
特定の属性を転送するように拡張機能を構成すると、次のことが可能になります。
- 動的なルーティングの決定を行う。
- クライアント情報でリクエスト ヘッダーを強化する。
- クライアントのロケーションまたは TLS パラメータに基づいてカスタム セキュリティ ポリシーを実装する。
- 詳細なカスタムログを生成する。
プラグイン拡張機能とコールアウト拡張機能の YAML 構成の forwardAttributes フィールドで属性を指定できます。たとえば、トラフィック
拡張機能については、トラフィック拡張機能を構成するをご覧ください。
forwardAttributes を使用した属性の指定は、リージョン アプリケーション ロードバランサで
ext_proc
プロトコルを使用して実装される認可、
ルート、トラフィックの拡張機能でサポートされています。
次の表に、属性と、その属性をサポートする拡張機能を示します。
| 属性 | 説明 | 拡張機能 |
|---|---|---|
request.origin |
クロスオリジン リソース シェアリング（CORS）のユースケースのリクエストに含まれる送信元ヘッダーの値。 | トラフィック |
request.method |
GET や
POST などの HTTP リクエスト メソッド。 |
認可、エッジ、ルート、トラフィック |
request.mcp_method |
GET や
POST などの HTTP リクエスト メソッド。 |
認可 |
request.host |
request.headers['host'] と同じです。 |
認可、エッジ、ルート、トラフィック |
request.path |
リクエストした HTTP URL パス。 | 認可、エッジ、ルート、トラフィック |
request.query |
HTTP リクエストの第 1 行に現れるような、name1=value&name2=value2,
形式の HTTP URL クエリ。デコードは
行われません。 |
認可、エッジ、ルート、トラフィック |
request.scheme |
HTTP URL スキーム。たとえば HTTP または
HTTPS。この属性の値は小文字です。 |
認可、エッジ、ルート、トラフィック |
request.backend_service_name |
リクエストが転送されるバックエンド サービス。 | 認可、トラフィック |
request.backend_service_project_number |
共有 VPC を使用する場合の、リクエストが転送されるバックエンド サービスのプロジェクト番号。 | 認可、トラフィック |
request.mcp_param |
MCP パラメータ。 | 認可 |
source.ip |
クライアントの IP アドレス。 | エッジ、ルート、トラフィック |
source.port |
クライアントの送信元ポート。 | エッジ、ルート、トラフィック |
source.client_region |
クライアントの IP アドレスに関連付けられる国またはリージョン。
値は Unicode CLDR リージョン コード（US
または FR など）です。ほとんどの国では、このコードが
ISO-3166-2 コードに直接対応しています。 |
エッジ、トラフィック |
source.client_region_subdivision |
クライアントの IP アドレスに関連付けられる国
の下位地域区分（都道府県や州など）。これは Unicode CLDR
サブディビジョン ID です（USCA や CAON など）。これらの
Unicode コードは、
ISO-3166-2 標準で定義されている下位地域区分から派生しています。 |
エッジ |
source.client_city |
リクエスト送信元の都市の名前。たとえば、カリフォルニア州マウンテンビューの場合はMountain Viewです。この変数の有効な値の正規リストはありません。
都市名には、US-ASCII 文字、数字、スペース、
!#$%&'*+-.^_`|~ を含めることができます。 |
エッジ |
source.client_city_lat_long |
リクエスト送信元の都市の緯度と経度。たとえば、Mountain View からのリクエストの場合は 37.386051,-122.083851 です。 |
エッジ |
connection.client_encrypted |
クライアントとロードバランサ間の接続が暗号化されている場合（HTTPS、HTTP/2、またはHTTP/3を使用）はtrue、それ以外の場合はfalseです。 |
トラフィック |
connection.protocol |
クライアントと
ロードバランサ間の通信に使用される HTTP プロトコル。HTTP/1.0、
HTTP/1.1、HTTP/2、
のいずれかになります。HTTP/3 |
トラフィック |
destination.ip |
クライアントが接続するロードバランサの IP アドレス。
この値は、複数のロードバランサが共通のバックエンドを共有する場合に便利です。これは、
X-Forwarded-For ヘッダーの最後の IP アドレスと同じです。 |
トラフィック |
destination.port |
クライアントが接続する宛先ポート番号。 | トラフィック |
connection.sni |
RFC 6066 で定義されたサーバー名表示（TLS または QUIC handshake 中にクライアントによって提供された場合）。ホスト名は 小文字に変換され、末尾のドットは削除されます。 | 認可、エッジ、トラフィック |
connection.tls_version |
SSL handshake 中にクライアントとロードバランサの間でネゴシエートされた TLS バージョン。使用できる値は、
TLSv1、TLSv1.1、TLSv1.2、
およびTLSv1.3です。クライアントが TLS ではなく QUIC
を使用して接続した場合、値は QUIC です。 |
エッジ、トラフィック |
connection.sha256_peer_certificate_digest |
ダウンストリーム TLS 接続内のピア証明書の 16 進数でエンコードされた SHA256 ハッシュ（存在する場合）。 | 認可、エッジ、トラフィック |
connection.tls_cipher_suite |
TLS handshake 中にネゴシエートされた暗号スイート。値は、IANA TLS Cipher Suite Registry で定義された 4 桁の 16 進数です。たとえば、TLS_RSA_WITH_AES_128_GCM_SHA256 の場合には 009C となります。この値は、QUIC と暗号化されていないクライアント接続の場合には空です
。 |
トラフィック |
connection.tls_ja3_fingerprint |
JA3 TLS/SSL フィンガープリント（クライアントが
HTTPS、HTTP/2、またはHTTP/3を使用して接続している場合）。 |
トラフィック |
connection.tls_ja4_fingerprint |
JA4 TLS/SSL フィンガープリント（クライアントが HTTPS、
HTTP/2、または HTTP/3 を使用して接続している場合）。 |
エッジ、トラフィック |
connection.client_cert_present |
クライアントが TLS ハンドシェイク中に証明書を提供した場合は true、それ以外は false。 |
認可、トラフィック |
connection.client_cert_chain_verified |
構成された TrustStore に対してクライアント証明書チェーンが
検証された場合は true、それ以外の場合は
false。 |
認可、トラフィック |
connection.client_cert_error |
エラー状態を表す事前定義された文字列。エラー文字列の詳細については、mTLS クライアント検証モードをご覧ください。 | 認可、トラフィック |
connection.client_cert_serial_number |
クライアント証明書のシリアル番号。シリアル番号が 50 バイトを超える場合、client_cert_error は client_cert_serial_number_exceeded_size_limit に設定され、シリアル番号は空の文字列に設定されます。 |
認可、トラフィック |
connection.client_cert_spiffe_id |
サブジェクト代替名（SAN）フィールドの SPIFFE ID。値が無効であるか、2, 048 バイトを超える場合、SPIFFE ID は空の文字列に設定されます。SPIFFE ID が 2, 048
バイトを超える場合、client_cert_error は
client_cert_spiffe_id_exceeded_size_limit に設定されます。 |
認可、トラフィック |
connection.client_cert_uri_sans |
`URI` 型の SAN 拡張機能のカンマ区切り Base64 エンコード リスト。SAN 拡張機能はクライアント証明書から抽出されます。
フィールドに SPIFFE ID は含まれません。client_cert_uri_sans
client_cert_uri_sans が 512 バイトを超える場合、
client_cert_error は
client_cert_uri_sans_exceeded_size_limit に設定され、
カンマ区切りのリストは空の文字列に設定されます。 |
認可、トラフィック |
connection.client_cert_dnsname_sans |
`DNSName` タイプの SAN 拡張機能のカンマ区切り Base64 エンコード リスト。SAN 拡張機能は
クライアント証明書から抽出されます。client_cert_dnsname_sans
が 512 バイトを超える場合、client_cert_error は
client_cert_dnsname_sans_exceeded_size_limit に設定され、
カンマ区切りのリストは空の文字列に設定されます。 |
認可、トラフィック |
connection.client_cert_valid_not_before |
クライアント証明書が無効になる前のタイムスタンプ（RFC 3339 日付文字列形式）。たとえば、2022-07-01T18:05:09+00:00 です。 |
認可、トラフィック |
connection.client_cert_valid_not_after |
クライアント証明書が有効でなくなった後のタイムスタンプ（RFC 3339 日付文字列形式）。たとえば、2022-07-01T18:05:09+00:00 です。 |
認可、トラフィック |
connection.client_cert_issuer_dn |
Base64 でエンコードされた証明書の完全な Issuer
フィールドの DER エンコード。client_cert_issuer_dn
が 512 バイトを超える場合、文字列
client_cert_issuer_dn_exceeded_size_limit が
client_cert_error に追加され、
client_cert_issuer_dn は空の文字列に設定されます。 |
認可、トラフィック |
connection.client_cert_subject_dn |
Base64 でエンコードされた証明書の完全な Subject
フィールドの DER エンコード。client_cert_subject_dn が 512 バイトを超える場合、文字列 client_cert_subject_dn_exceeded_size_limit が client_cert_error に追加され、client_cert_subject_dn は空の文字列に設定されます。 |
認可、トラフィック |
connection.client_cert_leaf |
証明書が検証に合格している確立済みの mTLS 接続のクライアント リーフ証明書
。証明書のエンコードは
RFC 9440 に準拠しています。つまり、バイナリの DER 証明書
は Base64 でエンコードされ、両側がコロンで区切られています。client_cert_leaf がエンコードされていない状態で 16 KB を超える場合、文字列 client_cert_validated_leaf_exceeded_size_limit が client_cert_error に追加され、client_cert_leaf は空の文字列に設定されます。 |
認可、トラフィック |
connection.client_cert_chain |
クライアント証明書が検証に合格している確立済みの mTLS
接続のクライアント証明書チェーンの証明書のリスト。このリストはカンマ区切りで、標準の TLS 順序になっています（リーフ証明書は含みません）。証明書のエンコードは RFC 9440 に準拠しています。
Base64 エンコード前の
client_cert_leaf と client_cert_chain
の合計サイズが 16 KB を超える場合、文字列
client_cert_validated_chain_exceeded_size_limit が
client_cert_error に追加され、
client_cert_chain は空の文字列に設定されます。 |
認可、トラフィック |