ext-proc ベースのバックエンド サービスにプラグインまたはコールアウトを使用して拡張機能を構成する場合は、それらのサービスに転送するリクエスト属性と接続属性を指定できます。このページでは、サポートされている属性と、各拡張機能タイプで使用できる属性について説明します。
特定の属性を転送するように拡張機能を構成すると、次のことが可能になります。
- 動的ルーティングの決定を行います。
- クライアント情報でリクエスト ヘッダーを拡充します。
- クライアントの場所または TLS パラメータに基づいてカスタム セキュリティ ポリシーを実装します。
- 詳細なカスタムログを生成します。
プラグイン拡張機能とコールアウト拡張機能の YAML 構成で forwardAttributes フィールドを使用して属性を指定できます。たとえば、トラフィック拡張機能については、トラフィック拡張機能を構成するをご覧ください。
forwardAttributes を使用した属性の指定は、リージョン アプリケーション ロードバランサで ext_proc プロトコルを使用して実装された認可、ルート、トラフィック拡張機能でサポートされています。
次の表に、属性と、それらをサポートする拡張機能を示します。
| 属性 | 説明 | 拡張機能 |
|---|---|---|
request.origin |
クロスオリジン リソース シェアリング（CORS）のユースケースのリクエストに含まれる送信元ヘッダーの値。 | 交通状況 |
request.method |
GET や POST などの HTTP リクエスト メソッド。 |
authorization、route、traffic |
request.mcp_method |
GET や POST などの HTTP リクエスト メソッド。 |
authorization |
request.host |
request.headers['host'] と同等の利便性。 |
authorization、route、traffic |
request.path |
リクエストした HTTP URL パス。 | authorization、route、traffic |
request.query |
HTTP リクエストの第 1 行に現れるような、name1=value&name2=value2 形式の HTTP URL クエリ。デコードは行われません。 |
authorization、route、traffic |
request.scheme |
HTTP URL スキーム（HTTP、HTTPS など）。この属性の値は小文字です。 |
authorization、route、traffic |
request.backend_service_name |
リクエストが転送されるバックエンド サービス。 | 承認、トラフィック |
request.backend_service_project_number |
共有 VPC を使用する場合の、リクエストが転送されるバックエンド サービスのプロジェクト番号。 | 承認、トラフィック |
request.mcp_param |
MCP パラメータ。 | authorization |
source.ip |
クライアントの IP アドレス。 | ルート、交通状況 |
source.port |
クライアントの送信元ポート。 | ルート、交通状況 |
source.client_region |
クライアントの IP アドレスに関連付けられる国または地域。値は、US や FR などの Unicode CLDR リージョン コードです。ほとんどの国では、このコードが ISO-3166-2 コードに直接対応しています。 |
交通状況 |
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 接続内のピア証明書の SHA256 ハッシュ（存在する場合）。16 進数でエンコードされます。 | 承認、トラフィック |
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 |
クライアントが HTTPS、HTTP/2、HTTP/3 を使用して接続している場合の JA3 TLS/SSL フィンガープリント。 |
交通状況 |
connection.tls_ja4_fingerprint |
クライアントが HTTPS、HTTP/2、HTTP/3 を使用して接続している場合の JA4 TLS/SSL フィンガープリント。 |
交通状況 |
connection.client_cert_present |
TLS handshake 中にクライアントが証明書を提供した場合は 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 拡張機能はクライアント証明書から抽出されます。client_cert_uri_sans フィールドに SPIFFE ID は含まれません。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 が空の文字列に設定されます。 |
承認、トラフィック |