Membuat header kustom di peta URL

Halaman ini menjelaskan cara kerja header kustom di peta URL yang digunakan oleh Load Balancer Aplikasi eksternal regional, Load Balancer Aplikasi internal regional, dan Load Balancer Aplikasi internal lintas region.

Header permintaan dan respons kustom memungkinkan Anda menentukan header tambahan yang dapat ditambahkan load balancer ke permintaan dan respons HTTP(S). Bergantung pada informasi yang terdeteksi oleh load balancer, header ini dapat menyertakan informasi berikut:

Latensi ke klien
Lokasi geografis alamat IP klien
Parameter koneksi TLS

Sebelum memulai

Jika perlu, update Google Cloud CLI ke versi terbaru:

gcloud components update

Cara kerja header kustom

Header kustom berfungsi sebagai berikut:

Saat load balancer membuat permintaan ke backend, load balancer menambahkan header permintaan.
Load balancer menetapkan header respons sebelum menampilkan respons ke klien.

Agar dapat mengaktifkan header kustom untuk Load Balancer Aplikasi eksternal regional, Load Balancer Aplikasi internal regional, dan Load Balancer Aplikasi internal lintas region, Anda harus menentukan daftar nama header dan nilai header di file konfigurasi peta URL.

Nama header harus memiliki properti berikut:

Nama header harus berupa definisi nama kolom header HTTP yang valid per RFC 7230.
Nama header tidak boleh X-User-IP.
Nama header tidak boleh diawali dengan X-Google, X-Goog-, X-GFE, atau X-Amz-.
Nama header tidak boleh Host atau authority. Host dan authority adalah kata kunci khusus yang direservasi oleh Google Cloud. Anda tidak dapat mengubah header ini untuk load balancer berbasis Envoy. Sebagai gantinya, sebaiknya Anda membuat header kustom lainnya (misalnya, MyHost) agar tidak mengganggu nama header yang dicadangkan.
Nama header tidak boleh muncul lebih dari sekali dalam daftar header.

Nama header tidak peka huruf besar/kecil. Ketika nama header diteruskan ke backend HTTP/2, protokol HTTP/2 mengenkode nama header sebagai huruf kecil.

Nilai header harus memiliki properti berikut:

Nilai header harus berupa definisi kolom header HTTP yang valid sesuai RFC 7230, dengan formulir yang tidak digunakan lagi tidak diizinkan.
Nilai header tidak boleh kosong. Header kosong akan ditolak.
Nilai header dapat menyertakan satu atau beberapa variabel, yang diapit oleh tanda kurung kurawal, yang akan diperluas ke nilai yang disediakan load balancer. Untuk mengetahui daftar lengkap variabel yang diizinkan dalam nilai header, baca bagian Variabel yang dapat muncul di nilai header.

Dalam nilai header, spasi kosong di awal dan spasi kosong di akhir tidak signifikan dan tidak diteruskan ke backend. Untuk mengizinkan tanda kurung kurawal dalam nilai header, load balancer menafsirkan dua kurung kurawal buka ({{) sebagai satu kurung kurawal buka ({), dan dua kurung kurawal tutup (}}) sebagai kurung kurawal tunggal (}).

Tambahkan header permintaan atau respons

Untuk menambahkan header permintaan atau respons, gunakan gcloud CLI untuk mengedit peta URL sebagai berikut:

regional

    gcloud compute url-maps edit URL_MAP_NAME \
        --region=REGION

Berikut adalah contoh file YAML yang menunjukkan cara menggunakan variabel dalam header kustom:

   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

lintas region

    gcloud compute url-maps edit URL_MAP_NAME \
        --global

Berikut adalah contoh file YAML yang menunjukkan cara menggunakan variabel dalam header kustom:

   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

Perhatikan perilaku berikut:

Jika header respons dengan variabel kustom di-resolve menjadi string kosong, header tersebut akan dihapus.
Jika header permintaan dengan variabel kustom di-resolve menjadi string kosong, header tersebut akan dipertahankan dengan placeholder string kosong.
Jika header permintaan kustom menyertakan variabel kustom, dan permintaan klien yang masuk juga menyertakan header yang sama, nilai header permintaan klien akan diganti dengan nilai baru yang disediakan oleh header kustom load balancer.

Variabel yang dapat muncul di nilai header

Variabel berikut dapat muncul di nilai header kustom.

Variabel	Deskripsi
`client_region`	Negara (atau wilayah) yang terkait dengan alamat IP klien. Ini adalah kode wilayah CLDR Unicode, seperti `US` atau `FR`. (Untuk sebagian besar negara, kode ini berkaitan langsung dengan kode ISO-3166-2.)
`client_rtt_msec`	Perkiraan waktu transmisi bolak-balik antara load balancer dan klien HTTP(S), dalam milidetik. Ini adalah parameter waktu round-trip yang lancar (SRTT) yang diukur oleh stack TCP load balancer, sesuai dengan RFC 2988. Smoothed RTT adalah algoritma yang menangani variasi dan anomali yang mungkin terjadi dalam pengukuran RTT.
`client_ip_address`	Alamat IP klien. Alamat ini sama dengan alamat IP klien yang merupakan alamat berikutnya di header `X-Forwarded-For`.
`client_port`	Port sumber klien.
`client_encrypted`	`true` jika koneksi antara klien dan load balancer dienkripsi (menggunakan HTTPS, HTTP/2, atau HTTP/3); jika tidak, `false`.
`client_protocol`	Protokol HTTP yang digunakan untuk komunikasi antara klien dan load balancer. Salah satu dari `HTTP/1.0`, `HTTP/1.1`, `HTTP/2`, atau `HTTP/3`.
`origin_request_header`	Mencerminkan nilai header `Origin` dalam permintaan untuk kasus penggunaan Cross-Origin Resource Sharing (CORS).
`server_ip_address`	Alamat IP load balancer yang terhubung dengan klien. Hal ini dapat berguna ketika beberapa load balancer berbagi backend yang sama. Ini sama dengan alamat IP terakhir di header `X-Forwarded-For`.
`server_port`	Nomor port tujuan yang terhubung ke klien.
`tls_sni_hostname`	Indikasi nama server (seperti yang didefinisikan dalam RFC 6066), jika disediakan oleh klien selama TLS atau handshake QUIC. Nama host diubah menjadi huruf kecil dan tanpa tanda titik di akhir.
`tls_version`	Versi TLS yang dinegosiasikan antara klien dan load balancer selama handshake SSL. Nilai yang memungkinkan mencakup: `TLSv1`, `TLSv1.1`, `TLSv1.2`, dan `TLSv1.3`. Jika klien terhubung menggunakan QUIC, bukan TLS, nilainya adalah `QUIC`.
`tls_cipher_suite`	Rangkaian cipher yang dinegosiasikan selama TLS handshake. Nilainya adalah empat digit heksadesimal yang ditentukan oleh IANA TLS Cipher Suite Registry, misalnya, `009C` untuk TLS_RSA_WITH_AES_128_GCM_SHA256. Nilai ini kosong untuk QUIC dan untuk koneksi klien yang tidak terenkripsi.
`tls_ja3_fingerprint`	Sidik jari TLS/SSL JA3 jika klien terhubung menggunakan HTTPS, HTTP/2, atau HTTP/3.

Load balancer memperluas variabel ke string kosong jika tidak dapat menentukan nilainya. Contoh:

Variabel lokasi geografis saat lokasi alamat IP tidak diketahui
Parameter TLS saat TLS tidak digunakan
{origin_request_header} saat permintaan tidak menyertakan header Origin

Nilai geografis adalah perkiraan berdasarkan alamat IP klien. Dari waktu ke waktu, Google memperbarui data yang memberikan nilai-nilai ini untuk meningkatkan akurasi dan mencerminkan perubahan geografis dan politik.

Header kustom TLS bersama

Variabel header tambahan berikut tersedia jika TLS bersama (mTLS) dikonfigurasi pada TargetHttpsProxy load balancer.

Variabel	Deskripsi
`client_cert_present`	`true` jika klien telah memberikan sertifikat selama handshake TLS; jika tidak, `false`.
`client_cert_chain_verified`	`true` jika rantai sertifikat klien diverifikasi terhadap `TrustStore` yang dikonfigurasi; jika tidak, `false`.
`client_cert_error`	String yang telah ditentukan sebelumnya yang mewakili kondisi error. Untuk informasi selengkapnya tentang string error, lihat Mode validasi klien mTLS.
`client_cert_sha256_fingerprint`	Sidik jari SHA-256 berenkode base64 dari sertifikat klien.
`client_cert_serial_number`	Nomor seri sertifikat klien. Jika nomor seri lebih panjang dari 50 byte, string `client_cert_serial_number_exceeded_size_limit` akan ditambahkan ke `client_cert_error`, dan nomor seri ditetapkan ke string kosong.
`client_cert_spiffe_id`	ID SPIFFE dari kolom Nama Alternatif Subjek (SAN). Jika nilainya tidak valid atau melebihi 2.048 byte, ID SPIFFE akan disetel ke string kosong. Jika ID SPIFFE lebih dari 2.048 byte, string `client_cert_spiffe_id_exceeded_size_limit` akan ditambahkan ke `client_cert_error`.
`client_cert_uri_sans`	Daftar ekstensi SAN URI jenis yang dipisahkan koma. Ekstensi SAN diekstrak dari sertifikat klien. ID SPIFFE tidak disertakan dalam kolom `client_cert_uri_sans`. Jika `client_cert_uri_sans` lebih panjang dari 512 byte, string `client_cert_uri_sans_exceeded_size_limit` akan ditambahkan ke `client_cert_error`, dan daftar yang dipisahkan koma akan disetel ke string kosong.
`client_cert_dnsname_sans`	Daftar ekstensi SAN DNSName jenis yang dienkode menggunakan Base64 yang dipisahkan koma. Ekstensi SAN diekstrak dari sertifikat klien. Jika `client_cert_dnsname_sans` lebih panjang dari 512 byte, string `client_cert_dnsname_sans_exceeded_size_limit` akan ditambahkan ke `client_cert_error`, dan daftar yang dipisahkan koma akan disetel ke string kosong.
`client_cert_valid_not_before`	Stempel waktu (format string tanggal RFC 3339) yang sebelumnya tidak valid untuk sertifikat klien. Contoh, `2022-07-01T18:05:09+00:00`.
`client_cert_valid_not_after`	Stempel waktu (format string tanggal RFC 3339) yang setelahnya sertifikat klien tidak valid. Contoh, `2022-07-01T18:05:09+00:00`.
`client_cert_issuer_dn`	Kolom Penerbit penuh berenkode Base64 dari sertifikat. Jika `client_cert_issuer_dn` lebih panjang dari 512 byte, string `client_cert_issuer_dn_exceeded_size_limit` akan ditambahkan ke `client_cert_error`, dan `client_cert_issuer_dn` disetel ke string kosong.
`client_cert_subject_dn`	Kolom Subjek lengkap berenkode Base64 dari sertifikat. Jika `client_cert_subject_dn` lebih panjang dari 512 byte, string `client_cert_subject_dn_exceeded_size_limit` akan ditambahkan ke `client_cert_error`, dan `client_cert_subject_dn` disetel ke string kosong.
`client_cert_leaf`	leaf certificate klien untuk koneksi mTLS yang terbentuk tempat sertifikat lulus validasi. Encoding sertifikat mematuhi RFC 9440: sertifikat DER biner dienkode menggunakan Base64 (tanpa jeda baris, spasi, atau karakter lain di luar alfabet Base64) dan dipisahkan dengan titik dua di kedua sisinya. Jika `client_cert_leaf` melebihi 16 KB yang tidak dienkode, string `client_cert_validated_leaf_exceeded_size_limit` akan ditambahkan ke `client_cert_error`, dan `client_cert_leaf` akan ditetapkan ke string kosong.
`client_cert_chain`	Daftar sertifikat yang dipisahkan koma, dalam urutan TLS standar, dari rantai sertifikat klien untuk koneksi mTLS yang terbentuk tempat sertifikat klien lulus validasi, tidak termasuk leaf certificate. Encoding sertifikat mematuhi RFC 9440. Jika ukuran gabungan `client_cert_leaf` dan `client_cert_chain` sebelum encoding Base64 melebihi 16 KB, string `client_cert_validated_chain_exceeded_size_limit` akan ditambahkan ke `client_cert_error`, dan `client_cert_chain` disetel ke string kosong.

Batasan

Batasan berikut berlaku untuk header kustom yang digunakan dengan load balancer regional:

Anda tidak dapat mengonfigurasi header kustom di layanan backend regional yang digunakan oleh Load Balancer Aplikasi eksternal regional, Load Balancer Aplikasi internal regional, dan layanan backend global yang digunakan oleh Load Balancer Aplikasi internal lintas region.
Variabel header kustom berikut tidak didukung dengan Load Balancer Aplikasi eksternal regional:
- cdn_cache_id
- cdn_cache_status
- client_region_subdivision
- client_city
- client_city_lat_long