Benutzerdefinierte Header in URL-Zuordnungen erstellen

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-IP sein.
Der Headername darf nicht mit X-Google, X-Goog-, X-GFE oder X-Amz- beginnen.
Der Headername darf nicht Host oder authority sein. Sowohl Host als auch authority sind 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

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 keinen Origin-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 Kunden 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_spiffe_id_exceeded_size_limit` zu `client_cert_error` hinzugefügt.
`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 `client_cert_uri_sans` enthalten. Wenn `client_cert_uri_sans` länger als 512 Byte ist, wird `client_cert_uri_sans_exceeded_size_limit` zu `client_cert_error` hinzugefügt und die durch Kommas getrennte Liste auf einen leeren String gesetzt.
`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_dnsname_sans` länger als 512 Byte ist, wird `client_cert_dnsname_sans_exceeded_size_limit` zu `client_cert_error` hinzugefügt und die durch Kommas getrennte Liste auf einen leeren String gesetzt.
`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_issuer_dn` länger als 512 Byte ist, wird der String `client_cert_issuer_dn_exceeded_size_limit` zu `client_cert_error` hinzugefügt und `client_cert_issuer_dn` auf einen leeren String gesetzt.
`client_cert_subject_dn`	Base64-codiertes vollständiges Subject-Feld aus dem Zertifikat. Wenn `client_cert_subject_dn` länger als 512 Byte ist, wird der String `client_cert_subject_dn_exceeded_size_limit` zu `client_cert_error` hinzugefügt und `client_cert_subject_dn` auf einen leeren String gesetzt.
`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_leaf` 16 KB uncodiert überschreitet, wird der String `client_cert_validated_leaf_exceeded_size_limit` zu `client_cert_error` hinzugefügt und `client_cert_leaf` auf einen leeren String gesetzt.
`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 `client_cert_leaf` und `client_cert_chain` vor der Base64-Codierung 16 KB überschreitet, wird der String `client_cert_validated_chain_exceeded_size_limit` zu `client_cert_error` hinzugefügt und `client_cert_chain` auf einen leeren String festgelegt.

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_id
- cdn_cache_status
- client_region_subdivision
- client_city
- client_city_lat_long