[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-25。"],[],[],null,["# Create custom headers in URL maps\n\nThis page describes how custom headers work in URL maps used by\nregional internal Application Load Balancers and cross-region internal Application Load Balancers.\n\nCustom request and response headers let you specify additional headers that\nthe load balancer can add to HTTP(S) requests and responses. Depending on the\ninformation that the load balancer detects, these headers can include the\nfollowing information:\n\n- Latency to the client\n- Parameters of the TLS connection\n\n| **Important:** Global external Application Load Balancers support header transformations in the [URL\n| map](/load-balancing/docs/https/setting-up-global-traffic-mgmt#request-response-headers) as well as in the [backend\n| service](/load-balancing/docs/https/custom-headers-global). However, the regional internal Application Load Balancers and cross-region internal Application Load Balancers only support header transformations in URL maps.\n\nBefore you begin\n----------------\n\nIf necessary, update to the latest version of the Google Cloud CLI: \n\n```\ngcloud components update\n```\n\nHow custom headers work\n-----------------------\n\nCustom headers work as follows:\n\n- When the load balancer makes a request to the backend, the load\n balancer adds request headers.\n\n The load balancer adds custom request headers only to the client requests, not\n to the health check probes. If your backend requires a specific header for\n authorization that is missing from the health check packet, the health check\n might fail.\n- The load balancer sets response headers before returning a\n response to the client.\n\nTo enable custom headers for regional internal Application Load Balancers and cross-region internal Application Load Balancers,\nyou specify a list of header names and header values in the URL map\nconfiguration file.\n\n**Header names** must have the following properties:\n\n- The header name must be a valid HTTP header-field name definition per [RFC 7230](https://tools.ietf.org/html/rfc7230).\n- The header name must not be `X-User-IP`.\n- The header name must not begin with `X-Google`, `X-Goog-`, `X-GFE`, or `X-Amz-`.\n- The following hop-by-hop headers must not be used: `Keep-Alive`, `Transfer-Encoding`, `TE`, `Connection`, `Trailer`, and `Upgrade`. In accordance with [RFC 2616](https://datatracker.ietf.org/doc/html/rfc2616#page-92), these headers are not stored by caches or propagated by the target proxies.\n- The header name must not be `Host` or `authority`. Both `Host` and `authority` are special keywords reserved by Google Cloud. You can't modify these headers for Envoy-based load balancers. Instead, we recommend that you create other custom headers (for example, `MyHost`) so that you don't interfere with the reserved header names.\n- A header name must not appear more than once in the list of headers.\n\nHeader names are case-insensitive. When header names are passed to an HTTP/2\nbackend, the HTTP/2 protocol encodes header names as lowercase.\n\n**Header values** must have the following properties:\n\n- The header value must be a valid HTTP header field definition per [RFC 7230](https://tools.ietf.org/html/rfc7230), with obsolete forms disallowed.\n- The header value can't be blank. Blank headers are rejected.\n- The header value can include one or more variables, enclosed by curly braces, that expand to values that the load balancer provides. For a complete list of variables allowed in the header value, see [Variables that\n can appear in the header value](#variables).\n\nIn header values, leading whitespace and trailing whitespace are insignificant\nand are not passed to the backend. To allow for curly braces in header values,\nthe load balancer interprets two opening curly braces (`{{`) as\na single opening brace (`{`), and two closing curly braces (`}}`) as a single\nclosing brace (`}`).\n\nAdd request or response headers\n-------------------------------\n\nTo add request or response headers, use the gcloud CLI to edit\nthe URL map as follows:\n**Note:** If you are using the Google Cloud console to add the request and response headers in the URL map, you need to enter the host address in the **Hosts** field and the path matcher section of the following YAML in the **Path matcher** field. \n\n### Regional\n\n```\n gcloud compute url-maps edit URL_MAP_NAME \\\n --region=REGION\n \n```\n\nFollowing is a sample YAML file that shows you how to use variables in custom\nheaders: \n\n```yaml\n defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1\n name: regional-lb-map\n region: region/REGION\n hostRules:\n - hosts:\n - '*'\n pathMatcher: matcher1\n pathMatchers:\n - defaultService: regions/REGION/backendServices/BACKEND_SERVICE_1\n name: matcher1\n routeRules:\n - matchRules:\n - prefixMatch: /PREFIX\n priority: PRIORITY # 0 is highest\n routeAction:\n weightedBackendServices:\n - backendService: regions/REGION/backendServices/BACKEND_SERVICE_1\n weight: 100\n headerAction:\n requestHeadersToAdd:\n - headerName: X-header-1-client-region\n headerValue: \"{client_region}\"\n - headerName: X-header-2-client-ip-port\n headerValue: \"{client_ip_address}, {client_port}\"\n replace: True\n requestHeadersToRemove:\n - header-3-name\n responseHeadersToAdd:\n - headerName: X-header-4-server-ip-port\n headerValue: \"{server_ip_address}, {server_port}\"\n replace: True\n responseHeadersToRemove:\n - header-5-name\n - header-6-name\n \n```\n\n### Cross-region\n\n```\n gcloud compute url-maps edit URL_MAP_NAME \\\n --global\n \n```\n\nFollowing is a sample YAML file that shows you how to use variables in custom\nheaders: \n\n```yaml\n defaultService: global/backendServices/BACKEND_SERVICE_1\n name: global-lb-map\n hostRules:\n - hosts:\n - '*'\n pathMatcher: matcher1\n pathMatchers:\n - defaultService: global/backendServices/BACKEND_SERVICE_1\n name: matcher1\n routeRules:\n - matchRules:\n - prefixMatch: /PREFIX\n priority: PRIORITY # 0 is highest\n routeAction:\n weightedBackendServices:\n - backendService: global/backendServices/BACKEND_SERVICE_1\n weight: 100\n headerAction:\n requestHeadersToAdd:\n - headerName: X-header-1-client-region\n headerValue: \"{client_region}\"\n - headerName: X-header-2-client-ip-port\n headerValue: \"{client_ip_address}, {client_port}\"\n replace: True\n requesteHeadersToRemove:\n - header-3-name\n responseHeadersToAdd:\n - headerName: X-header-4-server-ip-port\n headerValue: \"{server_ip_address}, {server_port}\"\n replace: True\n responseHeadersToRemove:\n - header-5-name\n - header-6-name\n \n```\n\nNote the following behaviors:\n\n- If a response header with custom variables resolves to an empty string, it is removed.\n- If a request header with custom variables resolves to an empty string, it is retained with an empty string placeholder.\n- If a custom request header includes a custom variable, and an incoming client request also includes the same header, the client request header value will be replaced with the new value provided by the load balancer's custom header.\n\nVariables that can appear in the header value\n---------------------------------------------\n\nThe following variables can appear in custom header values.\n\nThe load balancer expands variables to empty strings when it can't determine\ntheir values. For example:\n\n- TLS parameters when TLS is not in use\n- The `{origin_request_header}` when the request does not include an `Origin`\n header\n\nGeographic values are estimates based on the client's IP address. From time to\ntime, Google updates the data that provides these values in order to improve\naccuracy and to reflect geographic and political changes. Even if the original\n`X-Forwarded-For` header contains valid location information, Google estimates\nclient locations by using the source IP address information contained in packets\nreceived by the load balancer.\n\nMutual TLS custom headers\n-------------------------\n\nThe following additional header variables are available if mutual TLS (mTLS) is\nconfigured on the load balancer's TargetHttpsProxy.\n\nLimitations\n-----------\n\nThe following limitations apply:\n\n- You can't configure custom headers on backend services used by regional internal Application Load Balancers and cross-region internal Application Load Balancers."]]
