在後端服務中建立自訂標頭

本頁面說明如何在傳統應用程式負載平衡器使用的後端服務中設定自訂標頭。

您可以使用自訂要求和回應標頭，指定負載平衡器可新增至 HTTP(S) 要求和回應的其他標頭。視負載平衡器偵測到的資訊而定，這些標頭可能包含下列資訊：

  • 用戶端的延遲時間
  • 用戶端 IP 位址的地理位置
  • TLS 連線的參數

後端服務支援自訂要求標頭，而後端服務和後端值區則支援自訂回應標頭。

負載平衡器會預設為代理新增特定標頭，用於後端和用戶端之間的所有 HTTP(S) 要求和回應。詳情請參閱「目標 Proxy」。

事前準備

  • 視需要更新至最新版 Google Cloud CLI：

    gcloud components update

自訂標頭的運作方式

自訂標頭的運作方式如下：

  • 負載平衡器將要求轉送至後端時，會新增要求標頭。

    負載平衡器只會將自訂要求標頭新增至用戶端要求，而不會新增至健康狀態檢查探測。如果後端需要特定的授權標頭，而健康狀態檢查封包中缺少該標頭，健康狀態檢查可能會失敗。

  • 負載平衡器會在將回應傳回用戶端前設定回應標頭。

如要啟用自訂標頭，您必須在後端服務或後端值區的屬性中指定一份標頭清單。

您可以將標題當做 header-name:header-value 字串來指定。標頭必須包含一個冒號，用於分隔標頭名稱和標頭值。

標頭名稱必須符合下列規定：

  • 標頭名稱必須是有效的 HTTP 標頭欄位名稱定義 (根據 RFC 7230)。
  • 標頭名稱不得為 X-User-IP 或 CDN-Loop。
  • 請勿使用下列逐跳式標頭：Keep-Alive、Transfer-Encoding、TE、Connection、Trailer 和 Upgrade。根據 RFC 2616 規定，這些標頭不會儲存在快取中，也不會由目標 Proxy 傳播。
  • 標頭名稱不得以 X-Google、X-Goog-、X-GFE 或 X-Amz- 開頭。
  • 標頭名稱在新增標頭清單中不可出現超過一次。

標頭值必須符合下列規定：

  • 標頭值必須是有效的 HTTP 標頭欄位定義 (根據 RFC 7230 的規定，您將無法使用已過時的表單)。
  • 標題值可以空白。
  • 標頭值可以包含一個或多個變數 (由大括號括住)，以囊括負載平衡器提供的值。標題值中允許包含的變數清單將於下節進一步說明。

gcloud 指令列工具有一個可用於指定要求標頭的標記，即 --custom-request-header。請務必使用此標記，將標頭名稱和標頭值括在直立的單引號 (') 中。

標記的格式大致如下：

    --custom-request-header='HEADER_NAME:[HEADER_VALUE]'

以下是標頭值範例，其中包含兩個變數 client_region 和 client_city，並以大括號包住。

    --custom-request-header='X-Client-Geo-Location:{client_region},{client_city}'

負載平衡器會對位於加州山景城的用戶端新增以下的標頭：

X-Client-Geo-Location:US,Mountain View

如要建立含自訂標頭的後端服務，請參閱「設定自訂要求標頭」。

支援標頭值的變數

以下變數可出現在自訂標頭值中。

變數 說明
cdn_cache_id 用於處理要求的快取執行個體位置代碼和 ID。這個值與 Logging 中 Cloud CDN 要求記錄檔的 jsonPayload.cacheId 欄位填入的值相同。
cdn_cache_status 目前的快取狀態。對於由支援 Cloud CDN 的後端提供的任何物件，值可以是 hit、miss、revalidated、stale、uncacheable 或 disabled。
origin_request_header 反映跨來源資源共享 (CORS) 用途的 Origin 標頭在要求中的值。
client_rtt_msec 負載平衡器與 HTTP(S) 用戶端之間的預估往返傳輸時間，以毫秒為單位。這是負載平衡器的 TCP 堆疊根據 RFC 2988 測量出的順暢往返時間 (SRTT) 參數。經過平滑處理的 RTT 是一種演算法，可處理 RTT 測量中可能發生的變化和異常情形。
client_region 與用戶端 IP 位址關聯的國家 (或地區)。這是 Unicode CLDR 地區代碼，例如 US 或 FR。(大部分國家的代碼都可以與 ISO-3166-2 代碼直接對應)。
client_region_subdivision 與客戶 IP 位址關聯的國家分區，例如省或州。這是 Unicode CLDR 分區 ID，例如 USCA 或 CAON。(這些 Unicode 代碼是從 ISO-3166-2 標準所定義的分區衍生出來的)。
client_city 發出要求的城市名稱，例如，Mountain View 代表加州山景城。這個變數沒有有效值的標準清單。城市名稱可包含 US-ASCII 字母、數字、空格和下列字元：!#$%&'*+-.^_`|~。
client_city_lat_long 發出要求的城市經緯度，例如，以 37.386051,-122.083851 表示來自山景城的要求。
client_ip_address 用戶端的 IP 位址。除非用戶端使用 Proxy，或 X-Forwarded-For 標頭遭到竄改，否則這通常會與用戶端 IP 位址相同，也就是 X-Forwarded-For 標頭中的倒數第二個位址。
client_port 用戶端的來源通訊埠。
client_encrypted true 如果用戶端和負載平衡器之間的連線已加密 (使用 HTTPS、HTTP/2 或 HTTP/3)；否則為 false。
client_protocol 用於用戶端與負載平衡器之間通訊的 HTTP 通訊協定。只能設為 HTTP/1.0、HTTP/1.1、HTTP/2 或 HTTP/3 之一。
device_request_type

用戶端的裝置，取自 User-Agent 標頭值。

可能的值如下：DESKTOP、GAME_CONSOLE、GAME_CONSOLE、MOBILE、SET_TOP_BOX、SMART_SPEAKER、SMART_TV、TABLET、UNDETERMINED、WEARABLE。
server_ip_address 用戶端連線的負載平衡器 IP 位址。當多個負載平衡器共用相同的後端時，這項功能就很實用。這與 X-Forwarded-For 標頭中的最後一個 IP 位址相同。
server_port 用戶端連線的目的地通訊埠編號。
tls_sni_hostname 伺服器名稱指標 (如 RFC 6066 中的定義)，如果用戶端在 TLS 或 QUIC 交握期間提供。系統會將主機名稱轉換為小寫，並移除任何的尾隨點。
tls_version 在 SSL 交握期間，用戶端與負載平衡器之間協商的 TLS 版本。可能的值包括：TLSv1、TLSv1.1、TLSv1.2 和 TLSv1.3。如果用戶端使用 QUIC 而非 TLS 進行連線，值會是 QUIC。
tls_cipher_suite 在 TLS 交握期間協商的加密套件。這個值是由 IANA TLS 加密套件登錄檔定義的四個十六進位數字，例如 TLS_RSA_WITH_AES_128_GCM_SHA256 的 009C。對於 QUIC 和未加密的用戶端連線，這個值為空白。
tls_ja3_fingerprint 如果用戶端使用 HTTPS、HTTP/2 或 HTTP/3 連線，則為 JA3 TLS/SSL 指紋。
user_agent_family

客戶的瀏覽器類型，取自 User-Agent 標頭值。

可能的值如下：APPLE、APPLEWEBKIT、BLACKBERRY、DOCOMO、GECKO、GOOGLE、KHTML、KOREAN、MICROSOFT、MSIE、NETFRONT、NOKIA、OBIGO、OPERA、OPENWAVE、OTHER、POLARIS、SEMC、SMIT、TELECA、USER_DEFINED。

當負載平衡器無法判斷變數的值時，會將其代換為空字串。例如：

  • IP 位址位置不明時的地理位置變數
  • 未使用 TLS 時的 TLS 參數
  • 要求不含 Origin 標頭時的 {origin_request_header}
  • {cdn_cache_status} 標頭 (當納入要求標頭時)

地理值 (地區、分區和城市) 是根據用戶端 IP 位址判斷的預估值。Google 會不時更新這些值的資料，以提高準確度及反映地理和政治上的變化。即使原始 X-Forwarded-For 標頭包含有效的位置資訊，Google 仍會使用負載平衡器收到的封包中所含的原始 IP 位址資訊，估算用戶端位置。

負載平衡器新增的標頭會覆寫任何名稱相同的既有標頭。標頭名稱不區分大小寫。標頭名稱傳送至 HTTP/2 後端時，HTTP/2 通訊協定會將標頭名稱轉換成小寫編碼。

標頭值中的前置空格及後置空格無關緊要，系統並不會將其傳送至後端。為了能在標頭值中使用大括號，負載平衡器會將雙左大括號 ({{) 解譯成單左括號 ({)，並將雙右大括號 (}}) 解譯成單右括號 (})。

相互傳輸層安全性 (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_error 會設為 client_cert_serial_number_exceeded_size_limit，而序號會設為空字串。
client_cert_spiffe_id

主體別名 (SAN) 欄位中的 SPIFFE ID。如果值無效或超過 2048 個位元組，SPIFFE ID 會設為空白字串。

如果 SPIFFE ID 長度超過 2048 個位元組，client_cert_error 會設為 client_cert_spiffe_id_exceeded_size_limit。
client_cert_uri_sans

以逗號分隔的 Base64 編碼清單，其中包含 URI 類型的 SAN 擴充功能。系統會從用戶端憑證中擷取 SAN 擴充欄位。client_cert_uri_sans 欄位中不包含 SPIFFE ID。

如果 client_cert_uri_sans 長度超過 512 個位元組，client_cert_error 會設為 client_cert_uri_sans_exceeded_size_limit，而以半形逗號分隔的清單則會設為空白字串。
client_cert_dnsname_sans

以逗號分隔的 Base64 編碼清單，其中包含 DNSName 類型的 SAN 擴充功能。系統會從用戶端憑證中擷取 SAN 擴充欄位。

如果 client_cert_dnsname_sans 長度超過 512 個位元組，client_cert_error 會設為 client_cert_dnsname_sans_exceeded_size_limit，而以半形逗號分隔的清單則會設為空字串。
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 編碼 DER 編碼。

如果 client_cert_issuer_dn 長度超過 512 位元組，字串 client_cert_issuer_dn_exceeded_size_limit 會新增至 client_cert_error，而 client_cert_issuer_dn 會設為空字串。
client_cert_subject_dn

憑證中「Subject」欄位的完整 Base64 編碼 DER 編碼。

如果 client_cert_subject_dn 長度超過 512 位元組，字串 client_cert_subject_dn_exceeded_size_limit 會新增至 client_cert_error，而 client_cert_subject_dn 會設為空字串。
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 設為空字串。
client_cert_chain

以逗號分隔的憑證清單，以標準 TLS 順序列出已建立 mTLS 連線的用戶端憑證鏈結 (用戶端憑證已通過驗證)，不含葉片憑證。憑證編碼符合 RFC 9440 標準。

如果 client_cert_leaf 和 client_cert_chain 在 Base64 編碼前總大小超過 16 KB，字串 client_cert_validated_chain_exceeded_size_limit 會新增至 client_cert_error，而 client_cert_chain 會設為空字串。

設定自訂要求標頭

主控台

如要將自訂要求標頭新增至現有的後端服務：

  1. 前往「Load balancing」(負載平衡) 摘要頁面。
    前往「負載平衡」頁面
  2. 點選「後端」。
  3. 按一下後端服務的名稱。
  4. 按一下「編輯」圖示 。
  5. 按一下 [Advanced configurations (Session affinity, connection draining timeout, security policies)] (進階設定 (工作階段相依性、連線排除逾時、安全性政策))。
  6. 在「Custom request headers」(自訂要求標頭) 下方，按一下 [Add header] (新增標頭)。
  7. 輸入自訂要求標頭的「Header name」(標頭名稱) 和「Header value」(標頭值)。
  8. 輸入任何其他自訂要求標頭。
  9. 按一下 [Save] (儲存)。

如要從後端服務移除自訂要求標頭：

  1. 前往「Load balancing」(負載平衡) 摘要頁面。
    前往「負載平衡」頁面
  2. 點選「後端」。
  3. 按一下後端服務的名稱。
  4. 按一下「編輯」圖示 。
  5. 按一下 [Advanced configurations (Session affinity, connection draining timeout, security policies)] (進階設定 (工作階段相依性、連線排除逾時、安全性政策))。
  6. 按一下要移除的自訂要求標頭名稱旁的「X」。
  7. 按一下 [儲存]。

gcloud

如要指定自訂要求標頭，請使用 gcloud compute backend-services create 或 gcloud compute backend-services update 指令，並加上 --custom-request-header 標記。

如要建立含自訂要求標頭的後端服務：

gcloud compute backend-services create BACKEND_SERVICE_NAME \
    --global-health-checks \
    --global \
    --protocol HTTPS \
    --health-checks https-basic-check \
    --custom-request-header='HEADER_NAME:[HEADER_VALUE]'

如要新增更多要求標頭，請重複使用 --custom-request-header 標記來指定專屬的標頭名稱和值。

如要將自訂標頭新增至現有的後端服務：

gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --global \
    --custom-request-header='HEADER_1_NAME:[HEADER_1_VALUE]' \
    --custom-request-header='HEADER_2_NAME:[HEADER_2_VALUE]'

上一個步驟會將後端服務中已存在的標頭，替換為您在指令中指定的要求標頭。

如要從後端服務移除所有標頭：

gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --global \
    --no-custom-request-headers

API

對 backendServices.patch 方法發出 PATCH 要求：

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME
"customRequestHeaders": [
   "client_city:Mountain View"
]

Terraform

如需使用自訂標頭建立負載平衡器的 Terraform 指令碼，請參閱「全球外部應用程式負載平衡器的 Terraform 範例」。

設定自訂回應標頭

主控台

如要將自訂回應標頭新增至現有的後端服務：

  1. 前往「Load balancing」(負載平衡) 摘要頁面。
    前往「負載平衡」頁面
  2. 點選「後端」。
  3. 按一下後端服務的名稱。
  4. 按一下「編輯」圖示 。
  5. 按一下 [Advanced configurations (Session affinity, connection draining timeout, security policies)] (進階設定 (工作階段相依性、連線排除逾時、安全性政策))。
  6. 在「Custom response headers」(自訂回應標頭) 下方，按一下「Add header」(新增標頭)。
  7. 輸入自訂回應標頭的「Header name」(標頭名稱) 和「Header value」(標頭值)。
  8. 輸入任何其他自訂回應標頭。
  9. 按一下 [儲存]。

如要從後端服務移除自訂回應標頭：

  1. 前往「Load balancing」(負載平衡) 摘要頁面。
    前往「負載平衡」頁面
  2. 點選「後端」。
  3. 按一下後端服務的名稱。
  4. 按一下「編輯」圖示 。
  5. 按一下 [Advanced configurations (Session affinity, connection draining timeout, security policies)] (進階設定 (工作階段相依性、連線排除逾時、安全性政策))。
  6. 按一下要移除的自訂回應標頭名稱旁的「X」。
  7. 按一下 [儲存]。

gcloud

針對後端服務，請使用 gcloud compute backend-services create 或 gcloud compute backend-services update 指令，並加上 --custom-response-header 旗標。

如為後端資料集，請使用 gcloud compute backend-buckets create 或 gcloud compute backend-buckets update 指令搭配 --custom-response-header 旗標。

gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME
    --custom-response-header='HEADER_NAME:[HEADER_VALUE]'

gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --custom-response-header='HEADER_NAME:[HEADER_VALUE]'

使用 X-Frame-Options 標頭的範例：

gcloud compute backend-buckets update gaming-lab \
    --custom-response-header='X-Frame-Options: DENY'

使用 Strict-Transport-Security 標頭的範例：

以下範例說明如何新增自訂回應標頭，以支援 HTTP 嚴格傳輸安全性 (HSTS)：

gcloud compute backend-services update customer-bs-name \
    --global \
    --custom-response-header='Strict-Transport-Security: max-age=63072000'

API

如要使用後端資料集，請使用 Method: backendBuckets.insert 或 Method: backendBuckets.update API 呼叫。

如為後端服務，請使用 Method: backendServices.insert 或 Method: backendServices.update API 呼叫。

請使用下列其中一個 API 呼叫：

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets

PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BACKEND_BUCKET_NAME

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices

PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME

將以下程式碼片段新增至 JSON 要求主體：

"customResponseHeaders":HEADER_NAME:[HEADER_VALUE]

Terraform

如需使用自訂標頭建立負載平衡器的 Terraform 指令碼，請參閱「全球外部應用程式負載平衡器的 Terraform 範例」。

設定 Cloud Storage 的回應標頭

如果您需要設定 Cloud Storage 回應的 HTTP 標頭 (例如跨來源資源政策、X-Frame-Options 或 X-XSS-Protection 標頭)，Google Cloud 提供使用 Cloud CDN 自訂標頭的選項，並搭配 Cloud Storage 使用。如要這麼做，請按照本頁所述，在負載平衡器後端桶層級設定自訂標頭。

只有在用戶端要求傳送至負載平衡器 IP 位址時，系統才會在回應中加入在後端叢集層級設定的自訂回應標頭。如果用戶端要求是直接傳送至 Cloud Storage API，回應中就不會加入自訂標頭。

搭配 Google Cloud Armor 使用自訂標頭

設定 Google Cloud Armor 安全性政策時，您可以設定 Google Cloud Armor 插入自訂標頭和值。如果 Google Cloud Armor 安全性政策已設定為插入與全域外部應用程式負載平衡器或傳統應用程式負載平衡器相同的自訂標頭名稱，則 Google Cloud Armor 安全性政策中指定的標頭值會被負載平衡器填入的值覆寫。如果不想覆寫 Google Cloud Armor 政策，請務必使用不同的名稱。

限制

下列限制適用於與全域負載平衡器搭配使用的自訂標頭：

  • 每個後端服務的所有自訂要求標頭 (變數擴充前名稱和值的總和) 總大小不得超過 8 KB 或 16 個要求標頭。
  • 每個後端服務所有自訂回應標頭的總大小 (變數擴充前名稱和值的總和) 不得超過 8 KB 或 16 個回應標頭。

後續步驟