이 페이지에서는 리전 외부 애플리케이션 부하 분산기, 리전 내부 애플리케이션 부하 분산기, 리전 간 내부 애플리케이션 부하 분산기에서 사용되는 URL 맵에서 커스텀 헤더가 작동하는 방식을 설명합니다.
커스텀 요청과 응답 헤더를 사용하면 부하 분산기가 HTTP(S) 요청 및 응답에 추가할 수 있는 추가 헤더를 지정할 수 있습니다. 부하 분산기에서 감지된 정보에 따라 헤더에는 다음 정보가 포함될 수 있습니다.
- 클라이언트에 대한 지연 시간
- 클라이언트 IP 주소의 지리적 위치
- TLS 연결 매개변수
시작하기 전에
필요한 경우 Google Cloud CLI를 최신 버전으로 업데이트합니다.
gcloud components update
커스텀 헤더 작동 방식
커스텀 헤더는 다음과 같이 작동합니다.
부하 분산기가 백엔드에 요청을 하면 부하 분산기가 요청 헤더를 추가합니다.
부하 분산기는 클라이언트에 응답을 반환하기 전에 응답 헤더를 설정합니다.
리전 외부 애플리케이션 부하 분산기, 리전 내부 애플리케이션 부하 분산기, 리전 간 내부 애플리케이션 부하 분산기에 커스텀 헤더를 사용 설정하려면 URL 맵 구성 파일에 헤더 이름과 헤더 값 목록을 지정합니다.
헤더 이름에는 다음 속성이 있어야 합니다.
- 헤더 이름은 유효한 HTTP 헤더 필드 이름 정의여야 합니다(RFC 7230에 따름).
- 헤더 이름은
X-User-IP가 아니어야 합니다. - 헤더 이름은
X-Google,X-Goog-,X-GFE또는X-Amz-로 시작되지 않아야 합니다. - 헤더 이름은
Host또는authority가 아니어야 합니다.Host와authority모두 Google Cloud에 예약된 특수 키워드입니다. Envoy 기반 부하 분산기의 헤더를 수정할 수 없습니다. 대신 예약된 헤더 이름을 방해하지 않도록 다른 커스텀 헤더(예:MyHost)를 만드는 것이 좋습니다. - 헤더 이름은 헤더 목록에 두 번 이상 나타나지 않아야 합니다.
헤더 이름은 대소문자를 구분하지 않습니다. 헤더 이름이 HTTP/2 백엔드로 전달되면 HTTP/2 프로토콜은 헤더 이름을 소문자로 인코딩합니다.
헤더 값에는 다음 속성이 있어야 합니다.
- 헤더 값은 올바른 HTTP 헤더 필드 정의여야 합니다(RFC 7230에 따라, 사용되지 않는 양식은 허용되지 않음).
- 헤더 값은 비워 둘 수 없습니다. 빈 헤더는 거부됩니다.
- 헤더 값에는 부하 분산기가 제공하는 값으로 확장되는 중괄호로 묶인 하나 이상의 변수가 포함될 수 있습니다. 헤더 값에 허용되는 전체 변수 목록은 헤더 값에 표시될 수 있는 변수를 참조하세요.
헤더 값에서 선행 공백과 후행 공백은 유의하지 않으며 백엔드로 전달되지 않습니다. 부하 분산기는 헤더 값에 중괄호를 허용하기 위해 두 개의 여는 중괄호({{)를 하나의 여는 중괄호({)로 해석하고, 두 개의 닫는 중괄호(}})를 하나의 닫는 중괄호(})로 해석합니다.
요청 또는 응답 헤더 추가
요청 또는 응답 헤더를 추가하려면 gcloud CLI를 사용하여 다음과 같이 URL 맵을 수정합니다.
리전
gcloud compute url-maps edit URL_MAP_NAME \
--region=REGION
다음은 커스텀 헤더에서 변수를 사용하는 방법을 보여주는 샘플 YAML 파일입니다.
defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1
name: regional-lb-map
region: region/REGION
hostRules:
- hosts:
- '*'
pathMatcher: matcher1
pathMatchers:
- defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1
name: matcher1
routeRules:
- matchRules:
- prefixMatch: /PREFIX
priority: PRIORITY # 0 is highest
routeAction:
weightedBackendServices:
- backendService: regions/REGION/backendServices/BACKEND_SERVICE_1
weight: 100
headerAction:
requestHeadersToAdd:
- headerName: X-header-1-client-region
headerValue: "{client_region}"
- headerName: X-header-2-client-ip-port
headerValue: "{client_ip_address}, {client_port}"
replace: True
requesteHeadersToRemove:
- header-3-name
responseHeadersToAdd:
- headerName: X-header-4-server-ip-port
headerValue: "{server_ip_address}, {server_port}"
replace: True
responseHeadersToRemove:
- header-5-name
- header-6-name
리전 간
gcloud compute url-maps edit URL_MAP_NAME \
--global
다음은 커스텀 헤더에서 변수를 사용하는 방법을 보여주는 샘플 YAML 파일입니다.
defaultService: global/backendServices/BACKEND_SERVICE_1
name: global-lb-map
hostRules:
- hosts:
- '*'
pathMatcher: matcher1
pathMatchers:
- defaultService: global/backendServices/BACKEND_SERVICE_1
name: matcher1
routeRules:
- matchRules:
- prefixMatch: /PREFIX
priority: PRIORITY # 0 is highest
routeAction:
weightedBackendServices:
- backendService: global/backendServices/BACKEND_SERVICE_1
weight: 100
headerAction:
requestHeadersToAdd:
- headerName: X-header-1-client-region
headerValue: "{client_region}"
- headerName: X-header-2-client-ip-port
headerValue: "{client_ip_address}, {client_port}"
replace: True
requesteHeadersToRemove:
- header-3-name
responseHeadersToAdd:
- headerName: X-header-4-server-ip-port
headerValue: "{server_ip_address}, {server_port}"
replace: True
responseHeadersToRemove:
- header-5-name
- header-6-name
다음 동작을 확인합니다.
- 커스텀 변수가 포함된 응답 헤더가 빈 문자열로 확인되면 삭제됩니다.
- 커스텀 변수가 포함된 요청 헤더가 빈 문자열로 확인되면 빈 문자열 자리표시자와 함께 유지됩니다.
- 커스텀 요청 헤더에 커스텀 변수가 포함되어 있고 수신되는 클라이언트 요청에도 동일한 헤더가 포함되어 있으면 클라이언트 요청 헤더 값이 부하 분산기의 커스텀 헤더에서 제공된 새 값으로 대체됩니다.
헤더 값에 나타날 수 있는 변수
커스텀 헤더 값에 다음 변수가 나타날 수 있습니다.
| 변수 | 설명 |
|---|---|
client_region |
클라이언트의 IP 주소와 연관된 국가(또는 리전)입니다. US 또는 FR과 같은 유니코드 CLDR 리전 코드입니다. 대부분의 국가에서 이 코드는 ISO-3166-2 코드와 바로 대응합니다.
|
client_rtt_msec |
부하 분산기와 HTTP(S) 클라이언트 간의 예상 왕복 전송 시간(밀리초)입니다. 이는 RFC 2988에 따라 부하 분산기의 TCP 스택으로 측정된 평활 왕복 시간(Smoothed Round Trip Time, SRTT) 매개변수입니다. 평활 RTT는 RTT 측정에서 발생할 수 있는 변이와 이상을 처리하는 알고리즘입니다. |
client_ip_address |
클라이언트의 IP 주소입니다. 클라이언트에서 프록시를 사용하지 않거나 X-Forwarded-For 헤더가 조작되지 않는 한 이는 일반적으로 X-Forwarded-For 헤더의 다음으로 가까운 주소인 클라이언트 IP 주소와 동일합니다. |
client_port |
클라이언트의 소스 포트입니다. |
client_encrypted |
클라이언트와 부하 분산기 간의 연결이 암호화된 경우(HTTPS, HTTP/2 또는 HTTP/3 사용) true, 그렇지 않으면 false입니다.
|
client_protocol |
클라이언트와 부하 분산기 간의 통신에 사용되는 HTTP 프로토콜입니다. HTTP/1.0, HTTP/1.1, HTTP/2 또는 HTTP/3 중 하나입니다.
|
origin_request_header |
교차 출처 리소스 공유(CORS) 사용 사례의 경우 요청에서 Origin 헤더 값을 반영합니다.
|
server_ip_address |
클라이언트가 연결되는 부하 분산기의 IP 주소입니다. 부하 분산기 여러 개에서 공통 백엔드를 공유할 때 유용합니다. X-Forwarded-For 헤더의 마지막 IP 주소와 동일합니다.
|
server_port |
클라이언트가 연결되는 대상 포트 번호입니다. |
tls_sni_hostname |
TLS 또는 QUIC 핸드셰이크 중에 클라이언트가 제공한 경우 서버 이름 표시(RFC 6066에 정의된 대로)입니다. 호스트 이름은 소문자로 변환되고 후행 점은 모두 삭제됩니다. |
tls_version |
SSL 핸드셰이크 중에 클라이언트와 부하 분산기 간에 협상된 TLS 버전입니다. 가능한 값에는 TLSv1, TLSv1.1, TLSv1.2, TLSv1.3이 포함됩니다. 클라이언트가 TLS 대신 QUIC를 사용하여 연결하면 값은 QUIC입니다.
|
tls_cipher_suite |
TLS 핸드셰이크 중에 협상된 암호 모음입니다. 값은 IANA TLS Cipher Suite 레지스트리에서 정의한 네 자리 16진수입니다(예: TLS_RSA_WITH_AES_128_GCM_SHA256의 경우 009C). QUIC 및 암호화되지 않은 클라이언트 연결의 경우 이 값은 비어 있습니다.
|
tls_ja3_fingerprint |
클라이언트가 HTTPS, HTTP/2 또는 HTTP/3을 사용하여 연결하는 경우 JA3 TLS/SSL 디지털 지문입니다. |
부하 분산기는 값을 확인할 수 없는 경우 변수를 빈 문자열로 확장합니다. 예를 들면 다음과 같습니다.
- IP 주소의 위치를 알 수 없는 경우의 지리적 위치 변수
- TLS를 사용하지 않는 경우의 TLS 매개변수
- 요청에
Origin헤더가 포함되지 않은 경우의{origin_request_header}
지리적 값은 클라이언트의 IP 주소를 기반으로 한 추정치입니다. 때때로 Google은 정확도를 개선하고 지리적, 정치적 변화를 반영하기 위해 이러한 값을 제공하는 데이터를 업데이트합니다. 원래 X-Forwarded-For 헤더에 유효한 위치 정보가 포함되어 있더라도 Google은 부하 분산기에서 수신한 패킷에 포함된 소스 IP 주소 정보를 사용하여 클라이언트 위치를 추정합니다.
상호 TLS 커스텀 헤더
부하 분산기의 TargetHttpsProxy에 상호 TLS(mTLS)가 구성된 경우 다음과 같은 추가적인 헤더 변수가 제공됩니다.
| 변수 | 설명 |
|---|---|
client_cert_present |
TLS 핸드셰이크 중 클라이언트가 인증서를 제공한 경우 true이고 그렇지 않으면 false입니다.
|
client_cert_chain_verified |
클라이언트 인증서 체인이 구성된 TrustStore에 대해 확인된 경우 true이고 그렇지 않으면 false입니다.
|
client_cert_error |
오류 조건을 나타내는 사전 정의된 문자열입니다. 오류 문자열에 대한 자세한 내용은 mTLS 클라이언트 검증 모드를 참조하세요. |
client_cert_sha256_fingerprint |
클라이언트 인증서의 Base64로 인코딩된 SHA-256 지문입니다. |
client_cert_serial_number |
클라이언트 인증서의 일련번호입니다.
일련번호가 50바이트보다 길면 client_cert_serial_number_exceeded_size_limit 문자열이 client_cert_error에 추가되고 일련번호는 빈 문자열로 설정됩니다. |
client_cert_spiffe_id |
제목 대체 이름(SAN) 필드의 SPIFFE ID입니다. 값이 유효하지 않거나 2,048바이트를 초과할 경우 SPIFFE ID가 빈 문자열로 설정됩니다. SPIFFE ID가 2048바이트보다 길면 |
client_cert_uri_sans |
쉼표로 구분된 Base64로 인코딩된 URI 유형의 SAN 확장 프로그램 목록입니다.
SAN 확장 프로그램은 클라이언트 인증서에서 추출됩니다.
SPIFFE ID는
|
client_cert_dnsname_sans |
쉼표로 구분된 Base64로 인코딩된 DNSName 유형의 SAN 확장 프로그램 목록입니다. SAN 확장 프로그램은 클라이언트 인증서에서 추출됩니다.
|
client_cert_valid_not_before |
클라이언트 인증서가 유효하지 않은 이전의 타임스탬프(RFC 3339 날짜 문자열 형식)입니다.
예를 들면 2022-07-01T18:05:09+00:00입니다.
|
client_cert_valid_not_after |
클라이언트 인증서가 유효하지 않은 이후의 타임스탬프(RFC 3339 날짜 문자열 형식)입니다.
예를 들면 2022-07-01T18:05:09+00:00입니다.
|
client_cert_issuer_dn |
인증서에서 Base64로 인코딩된 전체 발급기관 필드입니다.
|
client_cert_subject_dn |
인증서에서 Base64로 인코딩된 전체 주체 필드입니다.
|
client_cert_leaf |
인증서가 유효성 검사를 통과한 설정된 mTLS 연결의 클라이언트 리프 인증서입니다. 인증서 인코딩은 RFC 9440을 준수합니다. 바이너리 DER 인증서가 Base64로 인코딩되며(줄바꿈, 공백, Base64 알파벳 이외의 기타 문자 없음) 양쪽에서 콜론으로 구분됩니다.
|
client_cert_chain |
리프 인증서를 포함하지 않은 클라이언트 인증서가 검증을 통과한 설정된 mTLS 연결의 클라이언트 인증서 체인에 대한 표준 TLS 순서의 쉼표로 구분된 인증서 목록입니다. 인증서 인코딩은 RFC 9440을 준수합니다. Base64 인코딩 전의 |
제한사항
다음 제한사항은 리전별 부하 분산기에 사용되는 커스텀 헤더에 적용됩니다.
- 리전 외부 애플리케이션 부하 분산기, 리전 내부 애플리케이션 부하 분산기에서 사용하는 리전별 백엔드 서비스와 리전 간 내부 애플리케이션 부하 분산기에서 사용하는 전역 백엔드 서비스에는 커스텀 헤더를 구성할 수 없습니다.
- 다음 커스텀 헤더 변수는 리전 외부 애플리케이션 부하 분산기에서 지원되지 않습니다.
cdn_cache_idcdn_cache_statusclient_region_subdivisionclient_cityclient_city_lat_long