ext-proc ベースのバックエンド サービスにプラグインまたはコールアウトを使用して拡張機能を構成する場合は、これらのサービスに転送するリクエスト属性と接続属性を指定できます。このページでは、サポートされている属性と、各拡張機能タイプで使用できる属性について説明します。
特定の属性を転送するように拡張機能を構成すると、次のことが可能になります。
- 動的なルーティングの決定を行う。
- クライアント情報でリクエスト ヘッダーを強化する。
- クライアントのロケーションまたは TLS パラメータに基づいてカスタム セキュリティ ポリシーを実装する。
- 詳細なカスタムログを生成する。
プラグイン拡張機能とコールアウト拡張機能の YAML 構成の forwardAttributes フィールドで属性を指定できます。たとえば、トラフィック
拡張機能については、トラフィック
拡張機能を構成するをご覧ください。
forwardAttributes を使用した属性の指定は、認可、エッジ、ルート、トラフィックの拡張機能でサポートされています。forwardAttributes は、次のプロダクトで Wasm プラグインまたはコールアウト（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 パラメータ。 | 認可 |
request.user_agent_family |
クライアントのブラウザタイプ。User-Agent
ヘッダー
値から取得されます。これらの値は、受信 HTTP
クライアント（ウェブブラウザ、モバイルアプリ、自動化ツールなど）が標準の HTTP User-Agent リクエスト ヘッダーで送信する生のテキスト文字列を指します。 |
エッジ、トラフィック（グローバル外部アプリケーション ロードバランサと リージョン外部アプリケーション ロードバランサのみ） |
request.device_request_type |
クライアントのデバイスタイプ。この属性の有効な値は、APPLE、APPLEWEBKIT、BLACKBERRY、DOCOMO、GECKO、GOOGLE、KHTML、KOREAN、MICROSOFT、MSIE、NETFRONT、NOKIA、OBIGO、OPERA、OPENWAVE、OTHER、POLARIS、SEMC、SMIT、TELECA、またはUSER_DEFINED です。 |
エッジ、トラフィック（グローバル外部アプリケーション ロードバランサと リージョン外部アプリケーション ロードバランサのみ） |
response.cdn_cache_id |
リクエストの処理に使用されるキャッシュ インスタンスのロケーション コードと ID。これは、Cloud CDN リクエストログの
jsonPayload.cacheId フィールドに入力されている値と同じです。
|
トラフィック（グローバル外部アプリケーション ロードバランサのみ） |
response.cdn_cache_status |
リクエストの処理に使用されるキャッシュ インスタンスの現在のステータス。この属性の有効な値は、hit、miss、revalidated、stale、uncacheable、disabled です。 |
トラフィック（グローバル外部アプリケーション ロードバランサのみ） |
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 は 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.client_rtt_msec |
ロードバランサと HTTP(S) クライアント間の推定ラウンドトリップ送信時間（ミリ秒単位）。これは、ロードバランサの TCP スタックによって測定される平滑化された ラウンドトリップ時間（SRTT）パラメータです（RFC 2988 で定義されています）。 | トラフィック（グローバル外部アプリケーション ロードバランサのみ） |
connection.client_protocol |
クライアントと
ロードバランサ間の通信に使用される HTTP プロトコル。HTTP/1.0、
HTTP/1.1、HTTP/2、
のいずれかになります。HTTP/3 |
トラフィック |
connection.server_ip_address |
クライアントが接続するロードバランサの IP アドレス。
この値は、複数のロードバランサが共通のバックエンドを共有する場合に便利です。これは、
X-Forwarded-For ヘッダーの最後の IP アドレスと同じです。 |
トラフィック |
connection.server_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 が空の文字列に設定されます。 |
認可、トラフィック |
制限事項
属性の可用性: すべての属性がすべての 拡張機能タイプでサポートされているわけではありません。詳細については、このページの表をご覧ください。
必要な構成: 属性を拡張機能に送信するには、拡張機能構成の
forwardAttributesフィールドに属性を 明示的にリストする必要があります。このフィールドに属性をリストしない場合、ロードバランサはその特定の属性を拡張機能に転送しません。サイズ上限: 1 つの 拡張機能に対して最大 16 個の属性を構成できます。
mTLS 属性: クライアント証明書属性 (
connection.client_cert_*) は、mTLS を有効にしていて、クライアントが証明書を提示している場合にのみ、拡張機能に渡されるデータに入力されます。