Membuat header kustom di peta URL

Halaman ini menjelaskan cara kerja header kustom di peta URL yang digunakan oleh Load Balancer Aplikasi eksternal regional.

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 load balancer, header ini dapat mencakup informasi berikut:

  • Latensi ke klien

  • Parameter koneksi TLS

  • Lokasi geografis alamat IP klien

Sebelum memulai

Jika perlu, update ke Google Cloud CLI versi terbaru:

gcloud components update

Cara kerja header kustom

Header kustom berfungsi sebagai berikut:

  • Saat load balancer membuat permintaan ke backend, load balancer akan menambahkan header permintaan.

    Load balancer menambahkan header permintaan kustom hanya ke permintaan klien, bukan ke pemeriksaan health check. Jika backend Anda memerlukan header tertentu untuk otorisasi yang tidak ada dalam paket health check, health check mungkin gagal.

  • Load balancer menetapkan header respons sebelum menampilkan respons ke klien.

Untuk mengaktifkan header kustom bagi Load Balancer Aplikasi eksternal regional, tentukan daftar nama header dan nilai header dalam file konfigurasi peta URL.

Nama header harus memiliki properti berikut:

  • Nama header harus berupa definisi nama kolom header HTTP yang valid sesuai dengan RFC 7230.
  • Nama header tidak boleh X-User-IP.
  • Nama header tidak boleh diawali dengan X-Google, X-Goog-, X-GFE, atau X-Amz-.
  • Header hop-by-hop berikut tidak boleh digunakan: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer, dan Upgrade. Sesuai dengan RFC 2616, header ini tidak disimpan oleh cache atau dipropagasi oleh proxy target.
  • Nama header tidak boleh Host atau authority. Host dan authority adalah kata kunci khusus yang dicadangkan oleh Cloud de Confiance. Anda tidak dapat mengubah header ini untuk load balancer berbasis Envoy. Sebagai gantinya, sebaiknya buat header kustom lainnya (misalnya, MyHost) agar Anda tidak mengganggu nama header yang dicadangkan.
  • Nama header tidak boleh muncul lebih dari sekali dalam daftar header.

Nama header tidak peka huruf besar/kecil. Saat 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 dengan RFC 7230, dengan bentuk yang sudah tidak digunakan tidak diizinkan.
  • Nilai header tidak boleh kosong. Header kosong ditolak.
  • Nilai header dapat mencakup satu atau beberapa variabel, yang diapit oleh tanda kurung kurawal, yang diperluas ke nilai yang disediakan load balancer. Untuk mengetahui daftar lengkap variabel yang diizinkan dalam nilai header, lihat Variabel yang dapat muncul dalam 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 tanda kurung kurawal buka ({{) sebagai satu tanda kurung kurawal buka ({), dan dua tanda kurung kurawal tutup (}}) sebagai satu tanda kurung kurawal tutup (}).

Menambahkan 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 di 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
                 requestHeadersToRemove:
                 - 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 diubah menjadi string kosong, header tersebut akan dihapus.
  • Jika header permintaan dengan variabel kustom diselesaikan ke string kosong, header tersebut akan dipertahankan dengan placeholder string kosong.
  • Jika header permintaan kustom menyertakan variabel kustom, dan permintaan klien masuk juga menyertakan header yang sama, nilai header permintaan klien akan diganti dengan nilai baru yang diberikan oleh header kustom load balancer.

Variabel yang dapat muncul di nilai header

Variabel berikut dapat muncul dalam 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 berhubungan langsung dengan kode ISO-3166-2.)
client_rtt_msec Perkiraan waktu transmisi round-trip antara load balancer dan klien HTTP(S), dalam milidetik. Ini adalah parameter waktu perjalanan pulang-pergi yang di-smoothing (SRTT) yang diukur oleh stack TCP load balancer, per RFC 2988. RTT yang dihaluskan adalah algoritma yang menangani variasi dan anomali yang dapat terjadi dalam pengukuran RTT.
client_ip_address Alamat IP klien. Ini biasanya sama dengan alamat IP klien yang merupakan alamat kedua dari belakang di header X-Forwarded-For, kecuali jika klien menggunakan proxy atau header X-Forwarded-For telah dirusak.
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 ke klien. Hal ini dapat berguna saat beberapa load balancer berbagi backend yang sama. Nilai ini sama dengan alamat IP terakhir di header X-Forwarded-For.
server_port Nomor port tujuan yang dihubungkan klien.
tls_sni_hostname Indikasi nama server (seperti yang ditentukan dalam RFC 6066), jika diberikan oleh klien selama TLS atau QUIC handshake. Nama host dikonversi menjadi huruf kecil dan dengan titik di akhir dihapus.
tls_version Versi TLS yang dinegosiasikan antara klien dan load balancer selama handshake SSL. Nilai yang mungkin mencakup: TLSv1, TLSv1.1, TLSv1.2, dan TLSv1.3. Jika klien terhubung menggunakan QUIC, bukan TLS, nilainya adalah QUIC.
tls_cipher_suite Cipher suite yang dinegosiasikan selama TLS handshake. Nilainya adalah empat digit hex 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 dienkripsi.
tls_ja3_fingerprint JA3 Sidik jari TLS/SSL jika klien terhubung menggunakan HTTPS, HTTP/2, atau HTTP/3.

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

  • Parameter TLS saat TLS tidak digunakan

  • {origin_request_header} saat permintaan tidak menyertakan header Origin

  • Variabel lokasi geografis saat lokasi alamat IP tidak diketahui

Nilai geografis adalah perkiraan berdasarkan alamat IP klien. Dari waktu ke waktu, Google memperbarui data yang memberikan nilai ini untuk meningkatkan akurasi dan mencerminkan perubahan geografis dan politik. Meskipun header X-Forwarded-For asli berisi informasi lokasi yang valid, Google memperkirakan lokasi klien dengan menggunakan informasi alamat IP sumber yang terdapat dalam paket yang diterima oleh load balancer.

Header kustom TLS bersama

Variabel header tambahan berikut tersedia jika TLS bersama (mTLS) dikonfigurasi di 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 berdasarkan TrustStore yang dikonfigurasi ; jika tidak, false.
client_cert_error String yang telah ditentukan sebelumnya yang merepresentasikan kondisi error. Untuk mengetahui informasi selengkapnya tentang string error, lihat Mode validasi klien mTLS.
client_cert_sha256_fingerprint Sidik jari SHA-256 bersandi 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 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 nilai tidak valid atau melebihi 2.048 byte, SPIFFE ID akan disetel ke string kosong.

Jika SPIFFE ID lebih panjang dari 2048 byte, string client_cert_spiffe_id_exceeded_size_limit ditambahkan ke client_cert_error.
client_cert_uri_sans

Daftar ekstensi SAN berenkode Base64 yang dipisahkan koma dengan jenis URI. Ekstensi SAN diekstrak dari sertifikat klien. SPIFFE ID 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 ditambahkan ke client_cert_error, dan daftar yang dipisahkan koma disetel ke string kosong.
client_cert_dnsname_sans

Daftar ekstensi SAN berenkode Base64 yang dipisahkan koma dengan jenis DNSName. 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) sebelum sertifikat klien tidak valid. Contoh, 2022-07-01T18:05:09+00:00.
client_cert_valid_not_after Stempel waktu (format string tanggal RFC 3339) setelah sertifikat klien tidak valid. Contoh, 2022-07-01T18:05:09+00:00.
client_cert_issuer_dn

Kolom Penerbit lengkap yang dienkode base64 dari sertifikat.

Jika client_cert_issuer_dn lebih panjang dari 512 byte, string client_cert_issuer_dn_exceeded_size_limit ditambahkan ke client_cert_error, dan client_cert_issuer_dn ditetapkan 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 ditetapkan ke string kosong.
client_cert_leaf

Sertifikat leaf klien untuk koneksi mTLS yang sudah dibuat dengan sertifikat yang lulus validasi. Encoding sertifikat sesuai dengan RFC 9440: sertifikat DER biner dienkode menggunakan Base64 (tanpa jeda baris, spasi, atau karakter lain di luar alfabet Base64) dan dibatasi 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 dibatasi koma, dalam urutan TLS standar, dari rantai sertifikat klien untuk koneksi mTLS yang sudah dibuat dan sertifikat klien lulus validasi, tidak termasuk sertifikat leaf. Encoding sertifikat sesuai dengan 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 akan disetel ke string kosong.

Batasan

Batasan berikut berlaku:

  • Anda tidak dapat mengonfigurasi header kustom pada layanan backend yang digunakan oleh Load Balancer Aplikasi eksternal regional.

  • 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