Auf dieser Seite wird beschrieben, wie benutzerdefinierte Header in URL-Zuordnungen funktionieren, die von regionalen externen Application Load Balancern, regionalen internen Application Load Balancern und regionenübergreifenden internen Application Load Balancern verwendet werden.
Mit benutzerdefinierten Anfrage- und Antwortheadern können Sie zusätzliche Header angeben, die vom Load-Balancer zu HTTP(S)-Anfragen und -Antworten hinzugefügt werden können. Abhängig von den vom Load-Balancer erkannten Informationen können diese Header die folgenden Informationen enthalten:
- Latenz zum Client
- Geografischer Standort der IP-Adresse des Clients
- Parameter der TLS-Verbindung
Hinweise
Aktualisieren Sie bei Bedarf auf die neueste Version der Google Cloud CLI:
gcloud components update
Funktionsweise benutzerdefinierter Header
Benutzerdefinierte Header funktionieren so:
Sendet der Load-Balancer eine Anfrage an das Backend, so fügt er Anfrageheader hinzu.
Der Load Balancer fügt benutzerdefinierte Anfrageheader nur den Clientanfragen hinzu, nicht den Systemdiagnoseprüfungen. Wenn Ihr Backend einen bestimmten Header für die Autorisierung erfordert, der im Systemdiagnosepaket fehlt, schlägt die Systemdiagnose möglicherweise fehl.
Der Load-Balancer legt Antwortheader fest, bevor eine Antwort an den Client zurückgegeben wird.
Wenn Sie benutzerdefinierte Header für regionale externe Application Load Balancer, regionale interne Application Load Balancer und regionenübergreifende interne Application Load Balancer aktivieren möchten, geben Sie eine Liste an Header-Namen und Header-Werten in der Konfigurationsdatei der URL-Zuordnung an.
Header-Namen müssen die folgenden Attribute haben:
- Der Headername muss eine gültige HTTP-Header-Namensfelddefinition (gemäß RFC 7230) sein.
- Der Headername darf nicht
X-User-IPsein. - Der Headername darf nicht mit
X-Google,X-Goog-,X-GFEoderX-Amz-beginnen. - Der Headername darf nicht
Hostoderauthoritysein. SowohlHostals auchauthoritysind spezielle, von Google Cloud reservierte Schlüsselwörter. Sie können diese Header nicht für Envoy-basierte Load-Balancer ändern. Stattdessen empfehlen wir, andere benutzerdefinierte Header (z. B.MyHost) zu erstellen, damit Sie die reservierten Headernamen nicht beeinträchtigen. - Ein Headername darf in der Liste der Header nicht mehr als einmal vorkommen.
Für Header-Namen muss die Groß-/Kleinschreibung nicht berücksichtigt werden. Bei der Übergabe an ein HTTP/2-Backend werden Header-Namen durch das HTTP/2-Protokoll in Kleinbuchstaben codiert.
Für Header-Werte gelten die folgenden Regeln:
- Der Header-Wert muss einer gültigen HTTP-Header-Felddefinition gemäß RFC 7230 entsprechen. Ältere Formate sind nicht zulässig.
- Der Headerwert darf nicht leer sein. Leere Header werden abgelehnt.
- Der Headerwert kann eine oder mehrere Variablen enthalten, die in geschweifte Klammern eingeschlossen sind und Werte repräsentieren, die vom Load Balancer bereitgestellt werden. Eine vollständige Liste der im Headerwert zulässigen Variablen finden Sie unter Variablen, die im Headerwert vorkommen können.
Führende und nachgestellte Leerzeichen sind in Headerwerten unbedeutend und werden nicht an das Backend übergeben. Für die Verwendung von geschweiften Klammern in Headerwerten interpretiert der Load Balancer zwei öffnende geschweifte Klammern ({{) als eine öffnende Klammer ({) und zwei schließende geschweifte Klammern (}}) als eine schließende Klammer (}).
Anfrage- oder Antwortheader hinzufügen
Verwenden Sie zum Hinzufügen von Anfrage- oder Antwortheadern die gcloud CLI, um die URL-Zuordnung so zu bearbeiten:
regional
gcloud compute url-maps edit URL_MAP_NAME \
--region=REGION
Im Folgenden finden Sie eine YAML-Beispieldatei, die zeigt, wie Variablen in benutzerdefinierten Headern verwendet werden:
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
Regionenübergreifend
gcloud compute url-maps edit URL_MAP_NAME \
--global
Im Folgenden finden Sie eine YAML-Beispieldatei, die zeigt, wie Variablen in benutzerdefinierten Headern verwendet werden:
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
Achten Sie auf das folgende Verhalten:
- Wenn ein Antwortheader mit benutzerdefinierten Variablen in einen leeren String aufgelöst wird, wird er entfernt.
- Wenn ein Anfrageheader mit benutzerdefinierten Variablen in einen leeren String aufgelöst wird, wird er mit einem leeren Stringplatzhalter beibehalten.
- Wenn ein benutzerdefinierter Anfrageheader eine benutzerdefinierte Variable enthält und eine eingehende Clientanfrage auch denselben Header enthält, wird der Header der Clientanfrage durch den neuen Wert ersetzt, der vom benutzerdefinierten Header des Load-Balancers bereitgestellt wird.
Variablen, die im Headerwert vorkommen können
Die folgenden Variablen können in benutzerdefinierten Headerwerten verwendet werden.
| Variable | Beschreibung |
|---|---|
client_region |
Das Land oder die Region, das bzw. die der IP-Adresse des Clients zugeordnet ist. Dies ist ein Unicode-CLDR-Regionscode wie US oder FR. Für die meisten Länder entsprechen diese Codes den ISO-3166-2-Codes.
|
client_rtt_msec |
Die geschätzte Übertragungszeit zwischen dem Load-Balancer und dem HTTP(S)-Client in Millisekunden. Dies ist der Parameter der ausgeglichenen Umlaufzeit (Smoothed Round-Trip Time, SRTT), der vom TCP-Stack des Load Balancers gemäß RFC 2988 ermittelt wird. Die ausgeglichene RTT ist ein Algorithmus, der Varianten und Anomalien behandelt, die bei RTT-Messungen auftreten können. |
client_ip_address |
IP-Adresse des Clients Diese ist in der Regel mit der Client-IP-Adresse identisch, die die nächstletzte Adresse im X-Forwarded-For-Header ist, es sei denn, der Client verwendet einen Proxy oder der Header X-Forwarded-For wurde manipuliert. |
client_port |
Der Quellport des Clients |
client_encrypted |
true, wenn die Verbindung zwischen dem Client und dem Load-Balancer über HTTPS, HTTP/2 oder HTTP/3 verschlüsselt ist; andernfalls false.
|
client_protocol |
Das HTTP-Protokoll, das für die Kommunikation zwischen dem Client und dem Load-Balancer verwendet wird Entweder HTTP/1.0, HTTP/1.1,
HTTP/2, oder HTTP/3
|
origin_request_header |
Zeigt den Wert des Headers Origin in der Anfrage für Anwendungsfälle mit CORS (Cross-Origin Resource Sharing) an. |
server_ip_address |
Die IP-Adresse des Load-Balancers, zu dem der Client eine Verbindung herstellt Dies kann nützlich sein, wenn mehrere Load-Balancer gemeinsame Back-Ends haben. Dies entspricht der letzten IP-Adresse im Header X-Forwarded-For.
|
server_port |
Die Zielportnummer, zu der der Client eine Verbindung herstellt. |
tls_sni_hostname |
Der Servername (gemäß RFC 6066) für die Bereitstellung vom Client während des TLS- oder QUIC-Handshakes. Der Hostname wird in Kleinbuchstaben konvertiert und alle nachgestellten Punkte werden entfernt. |
tls_version |
Die TLS-Version, die während des SSL-Handshakes zwischen Client und Load-Balancer ausgehandelt wird. Mögliche-Werte sind TLSv1, TLSv1.1, TLSv1.2 und TLSv1.3. Stellt der Client eine Verbindung mit QUIC statt TLS her, so lautet der Wert QUIC.
|
tls_cipher_suite |
Die Chiffresammlung, die während des TLS-Handshakes ausgehandelt wird. Der Wert besteht aus vier Hexadezimalziffern, die von der IANA TLS Cipher Suite Registry definiert werden, z. B. 009C für TLS_RSA_WITH_AES_128_GCM_SHA256. Bei QUIC und unverschlüsselten Clientverbindungen ist dieser Wert leer.
|
tls_ja3_fingerprint |
JA3-TLS/SSL-Fingerabdruck, wenn der Client eine Verbindung über HTTPS, HTTP/2 oder HTTP/3 herstellt. |
Der Load-Balancer erweitert Variablen zu leeren Strings, wenn keine Werte ermittelt werden können. Beispiel:
- Geografische Standortvariablen, wenn der Standort der IP-Adresse unbekannt ist
- TLS-Parameter, wenn TLS nicht verwendet wird
- Den
{origin_request_header}, wenn die Anfrage keinenOrigin-Header enthält
Geografische Werte sind Schätzungen, die auf der IP-Adresse des Clients basieren. Von Zeit zu Zeit aktualisiert Google die Daten, die diese Werte enthalten, um die Genauigkeit zu verbessern und um geografische bzw. politische Änderungen zu berücksichtigen. Auch wenn der ursprüngliche X-Forwarded-For-Header gültige Standortinformationen enthält, schätzt Google die Standorte von Clients anhand der Informationen zur Quell-IP-Adresse in Paketen, die vom Load Balancer empfangen werden.
Benutzerdefinierte Header mit gegenseitigem TLS
Die folgenden zusätzlichen Headervariablen sind verfügbar, wenn gegenseitiges TLS (mTLS) im TargetHttpsProxy des Load Balancers konfiguriert ist.
| Variable | Beschreibung |
|---|---|
client_cert_present |
true, wenn der Client während des TLS-Handshakes ein Zertifikat bereitgestellt hat. Andernfalls false.
|
client_cert_chain_verified |
true, wenn die Clientzertifikatskette mit einem konfigurierten TrustStore verglichen wird. Andernfalls false.
|
client_cert_error |
Vordefinierte Strings, die die Fehlerbedingungen darstellen. Weitere Informationen zu den Fehlerstrings finden Sie unter mTLS-Clientvalidierungsmodi. |
client_cert_sha256_fingerprint |
Base64-codierter SHA-256-Fingerabdruck des Clientzertifikats. |
client_cert_serial_number |
Die Seriennummer des Clientzertifikats.
Wenn die Seriennummer länger als 50 Byte ist, wird der String client_cert_serial_number_exceeded_size_limit zu client_cert_error hinzugefügt und die Seriennummer auf einen leeren String gesetzt. |
client_cert_spiffe_id |
Die SPIFFE-ID aus dem Feld „Alternativer Antragstellername“ (SAN) Wenn der Wert ungültig ist oder 2.048 Byte überschreitet, wird die SPIFFE-ID auf einen leeren String gesetzt. Wenn die SPIFFE-ID länger als 2.048 Byte ist, wird der String |
client_cert_uri_sans |
Durch Kommas getrennte Liste mit Base64-codierten SAN-Erweiterungen vom Typ URI.
Die SAN-Erweiterungen werden aus dem Clientzertifikat extrahiert.
Die SPIFFE-ID ist nicht im Feld Wenn |
client_cert_dnsname_sans |
Durch Kommas getrennte Liste mit Base64-codierten SAN-Erweiterungen vom Typ DNSName. Die SAN-Erweiterungen werden aus dem Clientzertifikat extrahiert. Wenn |
client_cert_valid_not_before |
Zeitstempel (RFC 3339-Datumsstring-Format), vor dem das Clientzertifikat ungültig ist.
Beispiel: 2022-07-01T18:05:09+00:00.
|
client_cert_valid_not_after |
Zeitstempel (RFC 3339-Datumsstring-Format), nach dem das Clientzertifikat ungültig ist.
Beispiel: 2022-07-01T18:05:09+00:00.
|
client_cert_issuer_dn |
Base64-codiertes vollständiges Ausstellerfeld aus dem Zertifikat. Wenn |
client_cert_subject_dn |
Base64-codiertes vollständiges Subject-Feld aus dem Zertifikat. Wenn |
client_cert_leaf |
Das untergeordnete Clientzertifikat für eine hergestellte mTLS-Verbindung, bei der das Zertifikat die Validierung bestanden hat. Die Zertifikatscodierung ist RFC 9440-konform: Das binäre DER-Zertifikat wird mit Base64 codiert (ohne Zeilenumbrüche, Leerzeichen oder andere Zeichen außerhalb des Base64-Alphabets) und durch Doppelpunkte auf beiden Seiten getrennt. Wenn |
client_cert_chain |
Die durch Kommas getrennte Liste der Zertifikate in Standard-TLS-Reihenfolge der Clientzertifikatskette für eine hergestellte mTLS-Verbindung, bei der das Clientzertifikat die Validierung bestanden hat, ohne das untergeordnete Zertifikat. Die Zertifikatscodierung ist konform mit RFC 9440. Wenn die Gesamtgröße von |
Beschränkungen
Die folgende Einschränkung gilt für benutzerdefinierte Header, die mit regionalen Load-Balancern verwendet werden:
- Sie können keine benutzerdefinierten Header für regionale Backend-Dienste konfigurieren, die von regionalen externen Application Load Balancern, regionalen internen Application Load Balancern und globalen Backend-Diensten verwendet werden, die von regionenübergreifenden internen Application Load Balancern verwendet werden.
- Die folgenden benutzerdefinierten Header-Variablen werden mit regionalen externen Application Load Balancern nicht unterstützt:
cdn_cache_idcdn_cache_statusclient_region_subdivisionclient_cityclient_city_lat_long