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
Benutzerdefinierte Anfrageheader werden für Backend-Dienste und benutzerdefinierte Antwortheader für Backend-Dienste und Backend-Buckets unterstützt.
Der Load-Balancer fügt standardmäßig allen HTTP(S)-Anfragen und -Antworten bestimmte Header hinzu, die zwischen Back-Ends und Clients weitergeleitet werden. Weitere Informationen finden Sie unter Zielproxys.
Vorbereitung
Aktualisieren Sie bei Bedarf auf die neueste Version der Google Cloud CLI:
gcloud components update
Funktionsweise benutzerdefinierter Header
Benutzerdefinierte Header funktionieren so:
Leitet der Load-Balancer eine Anfrage an das Backend weiter, so fügt er Anfrageheader hinzu.
Der Load Balancer fügt benutzerdefinierte Anfrageheader nur 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 die Antworten an den Client zurückgegeben werden.
Zum Aktivieren benutzerdefinierter Header geben Sie in einem Attribut des Back-End-Dienstes oder Back-End-Buckets eine Liste von Headern an.
Geben Sie jeden Header als header-name:header-value-String an. Der Header muss einen Doppelpunkt enthalten, durch den der Name und der Wert des Headers voneinander getrennt werden.
Headernamen müssen die folgenden Anforderungen erfüllen:
- Der Headername muss eine gültige HTTP-Header-Namensfelddefinition (gemäß RFC 7230) sein.
- Der Headername darf nicht
X-User-IPoderCDN-Loopsein. - Die folgenden Hop-by-Hop-Header dürfen nicht verwendet werden:
Keep-Alive,Transfer-Encoding,TE,Connection,Trailer,Upgrade,Proxy-AuthorizationundProxy-Authenticate. Gemäß RFC 2616 werden diese Header nicht in Caches gespeichert oder von Zielproxies weitergegeben. - Der Headername darf nicht mit
X-Google,X-Goog-,X-GFEoderX-Amz-beginnen. - Ein Headername darf in der Liste der hinzugefügten Header nicht mehr als einmal vorkommen.
Headerwerte müssen die folgenden Anforderungen erfüllen:
- Der Header-Wert muss einer gültigen HTTP-Header-Felddefinition gemäß RFC 7230 entsprechen. Ältere Formate sind nicht zulässig.
- Der Headerwert kann leer sein.
- 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 Liste der im Headerwert zulässigen Variablen finden Sie im nächsten Abschnitt.
Das Befehlszeilentool gcloud enthält ein Flag zum Angeben von Anfrageheadern, --custom-request-header. Achten Sie darauf, dass Sie den Headernamen und den Headerwert in geraden Anführungszeichen (') mit diesem Flag einschließen.
Das allgemeine Format für das Flag lautet:
--custom-request-header='HEADER_NAME:[HEADER_VALUE]'
Im folgenden Beispiel wird ein Headerwert mit zwei Variablen, client_region und client_city, in geschweifte Klammern gesetzt.
--custom-request-header='X-Client-Geo-Location:{client_region},{client_city}'
Für Clients im kalifornischen Mountain View fügt der Load-Balancer dann beispielsweise folgenden Header hinzu:
X-Client-Geo-Location:US,Mountain View
Mit Headerwerten unterstützte Variablen
Die folgenden Variablen können in benutzerdefinierten Headerwerten verwendet werden.
| Variable | Beschreibung |
|---|---|
| cdn_cache_id | Standortcode und ID der Cache-Instanz, die zur Verarbeitung der Anfrage verwendet wurde.
Dies ist der gleiche Wert, der im Feld jsonPayload.cacheId der Cloud CDN-Anfragelogs in Logging steht.
|
| cdn_cache_status | Aktueller Cache-Status. Für jedes Objekt, das von einem Cloud CDN-fähigen Back-End bereitgestellt wird, können die Werte hit, miss, revalidated, stale, uncacheable oder disabled sein.
|
| origin_request_header | Zeigt den Wert des Headers Origin in der Anfrage für Anwendungsfälle mit CORS (Cross-Origin Resource Sharing) an. |
| 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_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_region_subdivision | Eine Unterteilung des Landes, z. B. eine Region oder ein Bundesstaat, die bzw. der der IP-Adresse des Clients zugeordnet ist. Dies ist eine Unicode-CLDR-Unterteilungs-ID, z. B. USCA oder CAON. Diese Unicode-Codes werden von den durch den ISO-Standard 3166-2 definierten Unterteilungen abgeleitet.
|
| client_city | Der Name der Stadt, aus der die Anfrage stammt, z. B. Mountain View für Mountain View, Kalifornien. Für diese Variable gibt es keine offizielle Liste gültiger Werte. Die Namen der Orte können US-ASCII-Buchstaben, Zahlen, Leerzeichen und die folgenden Zeichen enthalten: !#$%&'*+-.^_`|~
|
| client_city_lat_long | Der Breiten- und Längengrad des Orts, aus dem die Anfrage stammt, z. B. 37.386051,-122.083851 für eine Anfrage aus Mountain View. |
| 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
|
| 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 - Den
{cdn_cache_status}-Header, wenn er in einem Anfrageheader enthalten ist
Geografische Werte (Regionen, Unterteilungen und Orte) sind auf der IP-Adresse des Clients beruhende Annahmen. 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 den Paketen, die vom Load Balancer empfangen werden.
Vom Load-Balancer hinzugefügte Header überschreiben vorhandene Header gleichen Namens. Für Header-Namen muss die Groß-/Kleinschreibung nicht berücksichtigt werden. Bei der Übergabe an ein HTTP/2-Back-End werden Header-Namen durch das HTTP/2-Protokoll in Kleinbuchstaben codiert.
Führende und nachgestellte Leerzeichen werden in Header-Werten ignoriert und nicht an das Back-End ü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 (}).
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-Client-Validierungsmodi. |
| 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 client_cert_error auf client_cert_serial_number_exceeded_size_limit 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 |
| 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 (Datumsstringformat gemäß RFC 3339), vor dem das Clientzertifikat ungültig ist.
Beispiel: 2022-07-01T18:05:09+00:00.
|
| client_cert_valid_not_after | Zeitstempel (Datumsstringformat gemäß RFC 3339), nach dem das Clientzertifikat ungültig ist.
Beispiel: 2022-07-01T18:05:09+00:00.
|
| client_cert_issuer_dn | Base64-codierte DER-Codierung des vollständigen Ausstellerfelds aus dem Zertifikat. Wenn |
| client_cert_subject_dn | Base64-codierte DER-Codierung des vollständigen Subject-Felds 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 bedeutet, dass das binäre DER-Zertifikat mit Base64 codiert und durch Doppelpunkte auf beiden Seiten begrenzt wird. 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 |
Benutzerdefinierte Anfrageheader konfigurieren
Console
So fügen Sie einem vorhandenen Back-End-Dienst benutzerdefinierte Anfrage-Header hinzu:
- Wechseln Sie zur Seite der Load-Balancing-Zusammenfassung.
Zur Seite "Load-Balancing" - Klicken Sie auf Backends.
- Klicken Sie auf den Namen eines Back-End-Dienstes.
- Klicken Sie auf Bearbeiten .
- Klicken Sie auf Erweiterte Konfigurationen (Sitzungsaffinität, Zeitlimit für Verbindungsausgleich, Sicherheitsrichtlinien).
- Klicken Sie unter Benutzerdefinierter Anfrageheader auf Header hinzufügen.
- Geben Sie für Namen des Headers und Header-Wert entsprechende Werte für den benutzerdefinierten Anfrageheader ein.
- Geben Sie bei Bedarf weitere benutzerdefinierte Anfrageheader ein.
- Klicken Sie auf Speichern.
So entfernen Sie einen benutzerdefinierten Anfrage-Header aus einem Back-End-Dienst:
- Wechseln Sie zur Seite der Load-Balancing-Zusammenfassung.
Zur Seite "Load-Balancing" - Klicken Sie auf Backends.
- Klicken Sie auf den Namen eines Back-End-Dienstes.
- Klicken Sie auf Bearbeiten .
- Klicken Sie auf Erweiterte Konfigurationen (Sitzungsaffinität, Zeitlimit für Verbindungsausgleich, Sicherheitsrichtlinien).
- Klicken Sie auf X neben dem Namen des benutzerdefinierten Anfrageheaders, den Sie entfernen möchten.
- Klicken Sie auf Speichern.
gcloud
Verwenden Sie zum Angeben benutzerdefinierter Anfrageheader den Befehl gcloud compute backend-services
create oder gcloud compute backend-services
update mit dem Flag --custom-request-header.
So erstellen Sie einen Back-End-Dienst mit benutzerdefinierten Anfrageheadern:
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]'
Zum Hinzufügen weiterer Anfrageheader legen Sie einen eindeutigen Headernamen und -wert durch nochmalige Angabe des Flags --custom-request-header fest.
So fügen Sie einem vorhandenen Back-End-Dienst benutzerdefinierte Header hinzu:
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]'
Der vorherige Schritt ersetzt alle Header, die bereits im Back-End-Dienst vorhanden sind, durch die im Befehl angegebenen Anfrageheader.
So entfernen Sie alle Header aus einem Back-End-Dienst:
gcloud compute backend-services update BACKEND_SERVICE_NAME \
--global \
--no-custom-request-headers
API
Stellen Sie eine PATCH-Anfrage an die Methode backendServices.patch.
PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME "customRequestHeaders": [ "client_city:Mountain View" ]
Terraform
Informationen zu einem Terraform-Script, das einen Load-Balancer mit benutzerdefinierten Headern erstellt, finden Sie unter Terraform-Beispiele für globale externe Application Load Balancer.
Benutzerdefinierte Antwortheader konfigurieren
Console
So fügen Sie einem vorhandenen Back-End-Dienst benutzerdefinierte Antwortheader hinzu:
- Wechseln Sie zur Seite der Load-Balancing-Zusammenfassung.
Zur Seite "Load-Balancing" - Klicken Sie auf Backends.
- Klicken Sie auf den Namen eines Back-End-Dienstes.
- Klicken Sie auf Bearbeiten .
- Klicken Sie auf Erweiterte Konfigurationen (Sitzungsaffinität, Zeitlimit für Verbindungsausgleich, Sicherheitsrichtlinien).
- Klicken Sie unter Benutzerdefinierter Anfrageheader auf Header hinzufügen.
- Geben Sie für Name des Headers und Headerwert entsprechende Werte für den benutzerdefinierten Antwortheader ein.
- Geben Sie bei Bedarf weitere benutzerdefinierte Antwortheader ein.
- Klicken Sie auf Speichern.
So entfernen Sie einen benutzerdefinierten Antwortheader aus einem Back-End-Dienst:
- Wechseln Sie zur Seite der Load-Balancing-Zusammenfassung.
Zur Seite "Load-Balancing" - Klicken Sie auf Backends.
- Klicken Sie auf den Namen eines Back-End-Dienstes.
- Klicken Sie auf Bearbeiten .
- Klicken Sie auf Erweiterte Konfigurationen (Sitzungsaffinität, Zeitlimit für Verbindungsausgleich, Sicherheitsrichtlinien).
- Klicken Sie auf das X neben dem Namen des benutzerdefinierten Antwortheaders, den Sie entfernen möchten.
- Klicken Sie auf Speichern.
gcloud
Verwenden Sie für Back-End-Dienste den Befehl gcloud compute backend-services
create oder gcloud compute backend-services
update mit dem Flag --custom-response-header.
Verwenden Sie für Backend-Buckets den Befehl gcloud compute backend-buckets
create oder gcloud compute backend-buckets
update mit dem Flag --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]'
Beispiel mit X-Frame-Options-Header:
gcloud compute backend-buckets update gaming-lab \
--custom-response-header='X-Frame-Options: DENY'
Beispiel mit Strict-Transport-Security-Header:
Das folgende Beispiel zeigt, wie Sie einen benutzerdefinierten Antwortheader hinzufügen, um HTTP Strict Transport Security (HSTS) zu unterstützen:
gcloud compute backend-services update customer-bs-name \
--global \
--custom-response-header='Strict-Transport-Security: max-age=63072000'
API
Verwenden Sie für Back-End-Buckets den API-Aufruf Method: backendBuckets.insert oder Method: backendBuckets.update.
Verwenden Sie für Back-End-Dienste den API-Aufruf Method: backendServices.insert oder Method: backendServices.update.
Verwenden Sie einen der folgenden API-Aufrufe:
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
Fügen Sie dem JSON-Anfragetext folgendes Snippet hinzu:
"customResponseHeaders":HEADER_NAME:[HEADER_VALUE]
Terraform
Informationen zu einem Terraform-Script, das einen Load-Balancer mit benutzerdefinierten Headern erstellt, finden Sie unter Terraform-Beispiele für globale externe Application Load Balancer.
Antwortheader für Cloud Storage festlegen
Wenn Sie HTTP-Header für Antworten aus Cloud Storage festlegen müssen, z. B. Cross-Origin Resource Policy-, X-Frame-Options- oder X-XSS-Protection-Header, können Sie in Google Cloud benutzerdefinierte Header für Cloud CDN mit Cloud Storage verwenden. Dazu konfigurieren Sie benutzerdefinierte Header auf der Ebene des Load-Balancer-Backend-Buckets, wie auf dieser Seite beschrieben.
Benutzerdefinierte Antwortheader, die auf der Backend-Bucket-Ebene konfiguriert wurden, werden nur zu Antworten hinzugefügt, wenn die Client-Anfrage an die IP-Adresse des Load-Balancers gesendet wird. Benutzerdefinierte Header werden den Antworten nicht hinzugefügt, wenn die Anfrage des Clients direkt an die Cloud Storage API gesendet wurde.
Benutzerdefinierte Header mit Google Cloud Armor verwenden
Wenn Sie eine Google Cloud Armor-Sicherheitsrichtlinie konfigurieren, können Sie Google Cloud Armor so konfigurieren, dass ein benutzerdefinierter Header und Wert eingefügt wird. Wenn Ihre Google Cloud Armor-Sicherheitsrichtlinie so konfiguriert ist, dass derselbe benutzerdefinierte Headername wie der für Ihren globalen externen Application Load Balancer oder Ihren klassischen Application Load Balancer genutzte eingefügt wird, dann wird der in Ihrer Google Cloud Armor-Sicherheitsrichtlinie angegebene Header-Wert durch den Wert überschrieben, der vom Load-Balancer ausgefüllt wird. Wenn Sie nicht möchten, dass die Google Cloud Armor-Richtlinie überschrieben wird, verwenden Sie nicht denselben Namen.
Beschränkungen
Die folgenden Einschränkungen gelten für benutzerdefinierte Header, die mit globalen Load-Balancern verwendet werden:
- Die Gesamtgröße aller benutzerdefinierten Anfrageheader (Name und Wert kombiniert, vor der Variablenerweiterung) für jeden Backend-Dienst darf 8 KB oder 16 Anfrageheader nicht überschreiten.
- Die Gesamtgröße aller benutzerdefinierten Antwortheader (Name und Wert kombiniert, vor der Variablenerweiterung) für jeden Backend-Dienst darf 8 KB oder 16 Antwortheader nicht überschreiten.
Nächste Schritte
- Ein Beispiel für einen Anwendungsfall finden Sie unter Load-Balancer mit einem externen Back-End konfigurieren.