플러그인 또는 콜아웃을 사용하여 확장 프로그램을 구성할 때 확장 프로그램 서비스로 전달할 요청 및 연결 속성을 지정할 수 있습니다. 이 페이지에서는 지원되는 속성을 설명하고 각 확장 프로그램 유형에 사용할 수 있는 속성을 식별합니다.
특정 속성을 전달하도록 확장 프로그램을 구성하면 다음을 수행할 수 있습니다.
- 동적 라우팅 결정을 내립니다.
- 클라이언트 정보로 요청 헤더를 보강합니다.
- 클라이언트 위치 또는 TLS 매개변수를 기반으로 커스텀 보안 정책을 구현합니다.
- 자세한 커스텀 로그를 생성합니다.
플러그인 및 콜아웃 확장 프로그램의 YAML 구성에서 forwardAttributes 필드를 사용하여 속성을 지정할 수 있습니다. 예를 들어 트래픽 확장 프로그램은 트래픽 확장 프로그램 구성을 참조하세요.
다음 유형의 확장 프로그램에 대해 forwardAttributes로 속성을 지정합니다.
- 전역 외부 애플리케이션 부하 분산기의 Cloud Load Balancing 에지 확장 프로그램 (
LbEdgeExtension) - 애플리케이션 부하 분산기의 Cloud Load Balancing 경로 및 트래픽 확장 프로그램(
LbRouteExtension,LbTrafficExtension) - 애플리케이션 부하 분산기에서
ext_proc를 사용하는 승인 확장 프로그램 (AuthzExtension) - Media CDN 에지 캐시 서비스의 Media CDN 에지 확장 프로그램 (
CdnEdgeExtension)
요청 속성
요청에서 다음 속성을 추출하고 전달할 수 있습니다.
| 속성 | 유형 | LbEdge |
LbRoute |
LbTraffic |
Authz |
CdnEdge |
설명 및 동작 차이점 |
|---|---|---|---|---|---|---|---|
request.method |
문자열 | ✓ | ✓ | ✓ | ✓ | ✓ | GET 또는 POST와 같은 HTTP 요청 메서드입니다. |
request.host |
문자열 | ✓ | ✓ | ✓ | ✓ | ✓ | 편의상 request.headers['host']와 동일합니다. |
request.path |
문자열 | ✓ | ✓ | ✓ | ✓ | ✓ | 요청한 HTTP URL 경로입니다. |
request.query |
문자열 | ✓ | ✓ | ✓ | ✓ | ✓ | name1=value&name2=value2 형식의 HTTP URL 쿼리입니다. |
request.scheme |
문자열 | ✓ | ✓ | ✓ | ✓ | ✓ | HTTP URL 스키마 (http 또는 https)입니다. 값은 소문자입니다. |
request.origin |
문자열 | — | — | ✓ | ✓ | — | 교차 출처 리소스 공유 (CORS) 사용 사례의 Origin 요청 헤더 값입니다. |
request.user_agent_family |
문자열 | ✓ | — | ✓ | — | — | 파싱된 사용자 에이전트 제품군 문자열입니다. 전역 외부 애플리케이션 부하 분산기에서만 지원됩니다. |
request.device_request_type |
문자열 | ✓ | — | ✓ | — | — | 기기 분류 카테고리입니다. 전역 외부 애플리케이션 부하 분산기에서만 지원됩니다. |
request.backend_service_name |
문자열 | — | — | ✓ | ✓ | — | 대상 백엔드 서비스입니다. 에지 확장 프로그램 (LbEdgeExtension 또는 CdnEdgeExtension)에는 적용되지 않습니다. |
request.backend_service_project_number |
int | — | — | ✓ | ✓ | — | 공유 VPC에 있는 백엔드 서비스의 프로젝트 번호입니다. 에지 확장 프로그램에는 적용되지 않습니다. |
request.mcp_method |
문자열 | — | — | — | ✓ | — | 모델 컨텍스트 프로토콜 (MCP) 메서드 이름입니다. |
연결 속성
연결에서 다음 속성을 추출하고 전달할 수 있습니다.
| 속성 | 유형 | LbEdge |
LbRoute |
LbTraffic |
Authz |
CdnEdge |
설명 및 동작 차이점 |
|---|---|---|---|---|---|---|---|
source.ip |
문자열 | ✓ | ✓ | ✓ | ✓ | — | 클라이언트 IP 주소입니다. |
source.port |
int | ✓ | ✓ | ✓ | ✓ | ✓ | 클라이언트 소스 포트 번호입니다. |
source.client_region |
문자열 | ✓ | — | ✓ | — | ✓ | 클라이언트 IP 주소와 연결된 두 자리 ISO-3166-1 또는 CLDR 리전 코드입니다 (예: US 또는 DE). |
source.client_region_subdivision |
문자열 | ✓ | — | ✓ | — | — | 지역 하위 구분 코드입니다(예: 주 또는 도). 전역 외부 애플리케이션 부하 분산기에서만 지원됩니다. |
source.client_city |
문자열 | ✓ | — | ✓ | — | — | 클라이언트 IP 주소와 연결된 도시입니다. 전역 외부 애플리케이션 부하 분산기에서만 지원됩니다. |
source.client_city_lat_long |
문자열 | ✓ | — | ✓ | — | — | 클라이언트 도시와 연결된 위도 및 경도입니다. 전역 외부 애플리케이션 부하 분산기에서만 지원됩니다. |
destination.ip |
문자열 | — | — | ✓ | ✓ | — | 클라이언트가 연결되는 부하 분산기의 IP 주소입니다. |
destination.port |
int | — | — | ✓ | ✓ | — | 클라이언트가 연결되는 대상 포트 번호입니다. |
connection.client_encrypted |
부울 | — | — | ✓ | ✓ | — | 클라이언트와 부하 분산기 간의 연결이 암호화된 경우 (HTTPS, HTTP/2 또는 HTTP/3 사용) 값은 true이고, 그렇지 않으면 false입니다. |
connection.protocol |
문자열 | — | — | ✓ | ✓ | — | 통신에 사용되는 HTTP 프로토콜 (HTTP/1.0, HTTP/1.1, HTTP/2 또는 HTTP/3)입니다. |
connection.sni |
문자열 | ✓ | — | ✓ | ✓ | ✓ | 다운스트림 TLS 연결의 요청된 서버 이름 표시 (SNI)입니다. |
connection.tls_version |
문자열 | ✓ | — | ✓ | ✓ | ✓ | 클라이언트와 협상된 TLS 버전 (TLSv1, TLSv1.1, TLSv1.2, TLSv1.3, QUIC)입니다. |
connection.tls_cipher_suite |
문자열 | — | — | ✓ | ✓ | — | TLS 핸드셰이크 중에 협상된 4자리 16진수 암호화 스위트입니다(예: 009C). |
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_rtt_msec |
int | — | — | ✓ | ✓ | — | 밀리초 단위로 측정된 클라이언트 왕복 시간 (RTT)입니다. |
connection.sha256_peer_certificate_digest |
문자열 | ✓ | — | ✓ | ✓ | — | 16진수로 인코딩된 SHA-256 피어 인증서 해시입니다. |
connection.client_cert_present |
부울 | — | — | ✓ | ✓ | — | TLS 핸드셰이크 중 클라이언트가 인증서를 제공한 경우 값은 true이고 그렇지 않으면 false입니다. |
connection.client_cert_chain_verified |
부울 | — | — | ✓ | ✓ | — | 클라이언트 인증서 체인이 구성된 TrustStore에 대해 확인된 경우 값은 true이고 그렇지 않으면 false입니다. |
connection.client_cert_error |
문자열 | — | — | ✓ | ✓ | — | mTLS 오류 조건을 나타내는 사전 정의된 문자열입니다. 자세한 내용은 mTLS 클라이언트 검증 모드를 참조하세요. |
connection.client_cert_serial_number |
문자열 | — | — | ✓ | ✓ | — | 클라이언트 인증서의 일련번호입니다. |
connection.client_cert_spiffe_id |
문자열 | — | — | ✓ | ✓ | — | 주체 대체 이름 (SAN) 필드의 SPIFFE ID입니다. |
connection.client_cert_uri_sans |
문자열 | — | — | ✓ | ✓ | — | 클라이언트 인증서에서 추출된 URI SAN 확장 프로그램의 쉼표로 구분된 Base64 인코딩 목록입니다. |
connection.client_cert_dnsname_sans |
문자열 | — | — | ✓ | ✓ | — | 클라이언트 인증서에서 추출된 DNSName SAN 확장 프로그램의 쉼표로 구분된 Base64 인코딩 목록입니다. |
connection.client_cert_valid_not_before |
문자열 | — | — | ✓ | ✓ | — | 클라이언트 인증서가 유효하지 않은 이전의 타임스탬프 (RFC 3339 형식)입니다. |
connection.client_cert_valid_not_after |
문자열 | — | — | ✓ | ✓ | — | 클라이언트 인증서가 유효하지 않은 이후의 타임스탬프 (RFC 3339 형식)입니다. |
connection.client_cert_issuer_dn |
문자열 | — | — | ✓ | ✓ | — | 인증서 Issuer 필드의 Base64로 인코딩된 DER 인코딩입니다. |
connection.client_cert_subject_dn |
문자열 | — | — | ✓ | ✓ | — | 인증서 Subject 필드의 Base64로 인코딩된 DER 인코딩입니다. |
connection.client_cert_leaf |
문자열 | — | — | ✓ | ✓ | — | 설정되고 검증된 mTLS 연결의 Base64로 인코딩된 클라이언트 리프 인증서입니다 (RFC 9440). |
connection.client_cert_chain |
문자열 | — | — | ✓ | ✓ | — | 리프 인증서를 제외한 표준 TLS 순서의 쉼표로 구분된 Base64로 인코딩된 클라이언트 인증서 체인입니다 (RFC 9440). |
제한사항
속성 사용 가능 여부: 일부 속성은 일부 확장 프로그램 유형에서 지원되지 않습니다. 자세한 내용은 이 페이지의 표를 참고하세요.
필수 구성: 확장 프로그램에 속성을 전송하려면 확장 프로그램 구성의
forwardAttributes필드에 속성을 명시적으로 나열해야 합니다. 이 필드에 속성을 나열하지 않으면 부하 분산기 또는 Media CDN이 해당 속성을 확장 프로그램에 전달하지 않습니다.크기 제한: 단일 확장 프로그램에 최대 16개의 속성을 구성할 수 있습니다.
mTLS 속성: 클라이언트 인증서 속성(
connection.client_cert_*)은 mTLS를 사용 설정하고 클라이언트가 인증서를 제공하는 경우에만 확장 프로그램에 전달된 데이터에 채워집니다.