Benutzerdefinierte Header erstellen

Mit benutzerdefinierten Anfrage- und Antwortheadern können Sie zusätzliche Header angeben, die der externe HTTP(S)-Load-Balancer in Anfragen und Antworten einfügt. Diese Header können vom Load-Balancer erfasste Informationen zur Clientverbindung enthalten, einschließlich der Latenz zum Client, des geografischen Standorts der IP-Adresse des Clients sowie der Parameter der TLS-Verbindung.

Benutzerdefinierte Anfrageheader werden für Back-End-Dienste und benutzerdefinierte Antwortheader für Back-End-Dienste und Back-End-Buckets unterstützt.

Das HTTP(S)-Load-Balancing 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 das Cloud SDK auf die neueste Version:

    gcloud components update
    

Funktionsweise benutzerdefinierter Header

Benutzerdefinierte Header funktionieren so:

  • Sendet der externe HTTP(S)-Load-Balancer eine Anfrage an das Back-End, so fügt der Load-Balancer Anfrageheader hinzu.

  • Der externe HTTP(S)-Load-Balancer legt Antwortheader fest, bevor die Antworten an den Client zurückgegeben werden.

Die Anfrage- und Antwortheader haben keinen Einfluss auf das Caching- oder Load-Balancer-Verhalten.

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 haben folgende Properties:

  • Der Headername muss eine gültige HTTP-Header-Namensfelddefinition (gemäß RFC 7230) sein.
  • Der Headername darf nicht X-User-IP oder CDN-Loop sein.
  • Der Headername darf nicht mit X-Google, X-Goog-, X-GFE oder X-Amz- beginnen.
  • Ein Headername darf in der Liste der hinzugefügten Header nicht mehr als einmal vorkommen.

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 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.

Sie können z. B. einen Header mit zwei Variablennamen für die Clientregion und den Clientort angeben. Das Befehlszeilentool gcloud enthält ein Flag zum Angeben von Anfrageheadern, --custom-request-header. Beispiel:

    --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

Das allgemeine Format für das Flag lautet:

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

Die Headerwerte müssen in geschweiften Klammern angegeben werden. Beispiel:

    --custom-request-header='X-PLACE:{client_city},{client_city_lat_long}'

Verwenden Sie für diesen Befehl nur gerade Anführungszeichen (').

Variablen, die im Headerwert vorkommen können

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.
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.
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.

Der Load-Balancer erweitert Variablen zu leeren Strings, wenn keine Werte ermittelt werden können. Beispiele:

  • 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
  • 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.

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 (}).

Mit benutzerdefinierten Anfrageheadern arbeiten

Console

So fügen Sie einem vorhandenen Back-End-Dienst benutzerdefinierte Anfrage-Header hinzu:

  1. Wechseln Sie zur Seite der Load-Balancing-Zusammenfassung.
    Zur Seite "Load-Balancing"
  2. Klicken Sie auf Back-Ends.
  3. Klicken Sie auf den Namen eines Back-End-Dienstes.
  4. Klicken Sie auf Bearbeiten .
  5. Klicken Sie auf Erweiterte Konfigurationen (Sitzungsaffinität, Zeitlimit für Verbindungsausgleich, Sicherheitsrichtlinien).
  6. Klicken Sie unter Benutzerdefinierter Anfrageheader auf Header hinzufügen.
  7. Geben Sie für Namen des Headers und Header-Wert entsprechende Werte für den benutzerdefinierten Anfrageheader ein.
  8. Geben Sie bei Bedarf weitere benutzerdefinierte Anfrageheader ein.
  9. Klicken Sie auf Speichern.

So entfernen Sie einen benutzerdefinierten Anfrage-Header aus einem Back-End-Dienst:

  1. Wechseln Sie zur Seite der Load-Balancing-Zusammenfassung.
    Zur Seite "Load-Balancing"
  2. Klicken Sie auf Back-Ends.
  3. Klicken Sie auf den Namen eines Back-End-Dienstes.
  4. Klicken Sie auf Bearbeiten .
  5. Klicken Sie auf Erweiterte Konfigurationen (Sitzungsaffinität, Zeitlimit für Verbindungsausgleich, Sicherheitsrichtlinien).
  6. Klicken Sie auf X neben dem Namen des benutzerdefinierten Anfrageheaders, den Sie entfernen möchten.
  7. Klicken Sie auf Speichern.

gcloud

Verwenden Sie zum Angeben benutzerdefinierter Anfrage-Header 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_NAME:[HEADER_VALUE]' \
    --custom-request-header='HEADER_NAME:[HEADER_VALUE]'

Im vorherigen Schritt werden alle Header, die bereits im Back-End-Dienst vorhanden sind, durch die im Befehl angegebenen Anfrageheader ersetzt.

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"
]

Mit benutzerdefinierten Antwortheadern arbeiten

Console

So fügen Sie einem vorhandenen Back-End-Dienst benutzerdefinierte Antwortheader hinzu:

  1. Wechseln Sie zur Seite der Load-Balancing-Zusammenfassung.
    Zur Seite "Load-Balancing"
  2. Klicken Sie auf Back-Ends.
  3. Klicken Sie auf den Namen eines Back-End-Dienstes.
  4. Klicken Sie auf Bearbeiten .
  5. Klicken Sie auf Erweiterte Konfigurationen (Sitzungsaffinität, Zeitlimit für Verbindungsausgleich, Sicherheitsrichtlinien).
  6. Klicken Sie unter Benutzerdefinierter Anfrageheader auf Header hinzufügen.
  7. Geben Sie für Name des Headers und Headerwert entsprechende Werte für den benutzerdefinierten Antwortheader ein.
  8. Geben Sie bei Bedarf weitere benutzerdefinierte Antwortheader ein.
  9. Klicken Sie auf Speichern.

So entfernen Sie einen benutzerdefinierten Antwortheader aus einem Back-End-Dienst:

  1. Wechseln Sie zur Seite der Load-Balancing-Zusammenfassung.
    Zur Seite "Load-Balancing"
  2. Klicken Sie auf Back-Ends.
  3. Klicken Sie auf den Namen eines Back-End-Dienstes.
  4. Klicken Sie auf Bearbeiten .
  5. Klicken Sie auf Erweiterte Konfigurationen (Sitzungsaffinität, Zeitlimit für Verbindungsausgleich, Sicherheitsrichtlinien).
  6. Klicken Sie auf das X neben dem Namen des benutzerdefinierten Antwortheaders, den Sie entfernen möchten.
  7. 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 Back-End-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:

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

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:

"cdnPolicy": {
  "customResponseHeaders":HEADER_NAME:[HEADER_VALUE]
}

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-Back-End-Buckets, wie auf dieser Seite beschrieben.

Beschränkungen

Für benutzerdefinierte Header gelten folgende Beschränkungen:

  • Für jeden Back-End-Dienst können maximal 16 benutzerdefinierte Anfrageheader angegeben werden.
  • Für jeden Back-End-Dienst können maximal 16 benutzerdefinierte Antwortheader angegeben werden.
  • Die Gesamtgröße aller benutzerdefinierten Anfrageheader pro Back-End-Dienst darf 8 KB nicht überschreiten. Dies gilt für Headername und -wert und vor der Variablenerweiterung.
  • Die Gesamtgröße aller benutzerdefinierten Antwortheader pro Back-End-Dienst darf 8 KB nicht überschreiten. Dies gilt für Headername und -wert und vor der Variablenerweiterung.

Nächste Schritte