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
Header request kustom didukung untuk layanan backend, sedangkan header respons kustom didukung untuk layanan backend dan bucket backend.
Load balancer menambahkan header tertentu secara default ke semua permintaan dan respons HTTP(S) yang dijadikan proxy antara backend dan klien. Untuk informasi selengkapnya, lihat Menargetkan proxy.
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 Aplikasi eksternal global membuat permintaan ke backend, load balancer akan menambahkan header permintaan.
Load Balancer Aplikasi eksternal global menetapkan header respons sebelum menampilkan respons ke klien.
Untuk mengaktifkan header kustom, tentukan daftar header di properti layanan backend atau bucket backend.
Anda menentukan setiap header sebagai string header-name:header-value
. Header harus
berisi titik dua yang memisahkan nama header dan nilai header.
Nama header harus memenuhi persyaratan berikut:
- Nama header harus berupa definisi nama kolom header HTTP yang valid (sesuai RFC 7230).
- Nama header tidak boleh
X-User-IP
atauCDN-Loop
. - Header hop-by-hop berikut tidak boleh digunakan:
Keep-Alive
,Transfer-Encoding
,TE
,Connection
,Trailer
,Upgrade
,Proxy-Authorization
, danProxy-Authenticate
. Sesuai dengan RFC 2616, header ini tidak disimpan oleh cache atau disebarkan oleh proxy target. - Nama header tidak boleh diawali dengan
X-Google
,X-Goog-
,X-GFE
, atauX-Amz-
. - Nama header tidak boleh muncul lebih dari sekali dalam daftar header yang ditambahkan.
Nilai header harus memenuhi persyaratan berikut:
- Nilai header harus berupa definisi kolom header HTTP yang valid (sesuai RFC 7230, dengan formulir yang sudah tidak berlaku tidak diizinkan).
- Nilai header boleh kosong.
- Nilai header dapat menyertakan satu atau beberapa variabel, yang diapit oleh tanda kurung kurawal, yang akan diperluas ke nilai yang disediakan load balancer. Daftar variabel yang diizinkan pada nilai header ada di bagian berikutnya.
Misalnya, Anda dapat menentukan header dengan dua nama variabel, untuk region klien dan kota klien. Alat command line gcloud
memiliki flag untuk menentukan
header permintaan, --custom-request-header
. Pastikan untuk hanya menggunakan tanda kutip lurus ('
) dengan flag ini.
Format umum flag adalah:
--custom-request-header='HEADER_NAME:[HEADER_VALUE]'
Setiap variabel harus diapit dalam tanda kurung kurawal. Contoh:
--custom-request-header 'X-Client-Geo-Location:{client_region},{client_city}'
Untuk klien yang berada di Mountain View, California, load balancer akan menambahkan header sebagai berikut:
X-Client-Geo-Location:US,Mountain View
Variabel yang didukung dengan nilai header
Variabel berikut dapat muncul di nilai header kustom.
Variabel | Deskripsi |
---|---|
cdn_cache_id | Kode lokasi dan ID instance cache yang digunakan untuk menayangkan permintaan.
Ini adalah nilai yang sama yang diisi di kolom jsonPayload.cacheId pada log permintaan Cloud CDN di Logging.
|
cdn_cache_status | Status cache saat ini. Nilai dapat berupa hit , miss , revalidated , stale , uncacheable , atau disabled untuk setiap objek yang disalurkan oleh backend berkemampuan Cloud CDN.
|
origin_request_header | Mencerminkan nilai header Origin dalam permintaan
untuk kasus penggunaan Cross-Origin Resource Sharing (CORS).
|
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_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_region_subdivision | Subdivisi, misalnya provinsi atau negara bagian, dari negara yang terkait dengan alamat IP klien. ID ini adalah ID subdivisi CLDR Unicode, seperti
USCA atau CAON . (Kode Unicode ini
berasal dari subdivisi yang ditentukan oleh standar ISO-3166-2.)
|
client_city | Nama kota tempat permintaan berasal, misalnya, Mountain View untuk Mountain View, California. Tidak ada daftar kanonis nilai valid untuk variabel ini. Nama kota dapat
berisi huruf US-ASCII, angka, spasi, dan karakter berikut:
!#$%&'*+-.^_`|~ .
|
client_city_lat_long | Lintang dan Bujur kota tempat permintaan berasal,
misalnya, 37.386051,-122.083851 untuk permintaan dari
Mountain View.
|
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 .
|
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 headerOrigin
- Header
{cdn_cache_status}
saat disertakan dalam header permintaan
Nilai geografis (wilayah, subdivisi, dan kota) adalah estimasi berdasarkan alamat IP klien. Dari waktu ke waktu, Google memperbarui data yang memberikan nilai ini untuk meningkatkan akurasi dan mencerminkan perubahan geografis dan politik.
Header yang ditambahkan oleh load balancer akan menimpa header yang ada dengan nama yang sama. Nama header tidak peka huruf besar/kecil. Ketika nama header diteruskan ke backend HTTP/2, protokol HTTP/2 akan mengenkode nama header sebagai huruf kecil.
Dalam nilai header, spasi kosong di awal dan di akhir spasi kosong 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 (}
).
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, client_cert_error
akan disetel ke client_cert_serial_number_exceeded_size_limit , dan
nomor seri disetel 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 panjang dari 2.048 byte, |
client_cert_uri_sans | Daftar ekstensi SAN URI jenis yang dipisahkan koma.
Ekstensi SAN diekstrak dari sertifikat klien.
ID SPIFFE tidak disertakan dalam kolom Jika |
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_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 | Encoding DER berenkode base64 pada kolom Penerbit lengkap dari sertifikat. Jika |
client_cert_subject_dn | Encoding DER berenkode Base64 untuk kolom Subjek lengkap dari sertifikat. Jika |
client_cert_leaf | leaf certificate klien untuk koneksi mTLS yang terbentuk tempat sertifikat lulus validasi. Encoding sertifikat mematuhi RFC 9440. Artinya, sertifikat DER biner dienkode menggunakan Base64 dan dipisahkan dengan titik dua di kedua sisinya. Jika |
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 |
Mengonfigurasi header permintaan kustom
Konsol
Untuk menambahkan header permintaan kustom ke layanan backend yang ada:
- Buka halaman ringkasan load balancing.
Buka halaman Load balancing - Click Backends.
- Klik nama layanan backend.
- Klik Edit .
- Klik Konfigurasi lanjutan (Afinitas sesi, waktu tunggu penghentian koneksi, kebijakan keamanan).
- Di bagian Header permintaan kustom, klik Tambahkan header.
- Masukkan Nama header dan Nilai header untuk header permintaan kustom.
- Masukkan header permintaan kustom tambahan.
- Klik Save.
Untuk menghapus header permintaan kustom dari layanan backend:
- Buka halaman ringkasan load balancing.
Buka halaman Load balancing - Click Backends.
- Klik nama layanan backend.
- Klik Edit .
- Klik Konfigurasi lanjutan (Afinitas sesi, waktu tunggu penghentian koneksi, kebijakan keamanan).
- Klik X di samping nama header permintaan kustom yang ingin Anda hapus.
- Klik Save.
gcloud
Untuk menentukan header permintaan kustom, gunakan perintah gcloud compute backend-services
create
atau
gcloud compute backend-services
update
dengan flag --custom-request-header
.
Untuk membuat layanan backend dengan header permintaan kustom:
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]'
Untuk menambahkan lebih banyak header permintaan, tentukan nama dan nilai header yang unik dengan
mengulangi flag --custom-request-header
.
Untuk menambahkan header kustom ke layanan backend yang ada:
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]'
Langkah sebelumnya mengganti header apa pun yang sudah ada di layanan backend dengan header permintaan yang Anda tentukan dalam perintah.
Untuk menghapus semua header dari layanan backend:
gcloud compute backend-services update BACKEND_SERVICE_NAME \ --global \ --no-custom-request-headers
API
Buat permintaan PATCH
ke
metode
backendServices.patch
:
PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME "customRequestHeaders": [ "client_city:Mountain View" ]
Terraform
Untuk skrip Terraform yang membuat load balancer dengan header kustom, baca artikel Contoh Terraform untuk Load Balancer Aplikasi eksternal global.
Mengonfigurasi header respons kustom
Konsol
Untuk menambahkan header respons kustom ke layanan backend yang ada:
- Buka halaman ringkasan load balancing.
Buka halaman Load balancing - Click Backends.
- Klik nama layanan backend.
- Klik Edit .
- Klik Konfigurasi lanjutan (Afinitas sesi, waktu tunggu penghentian koneksi, kebijakan keamanan).
- Di bagian Header respons kustom, klik Tambahkan header.
- Masukkan Nama header dan Nilai header untuk header respons kustom.
- Masukkan header respons kustom tambahan.
- Klik Save.
Untuk menghapus header respons kustom dari layanan backend:
- Buka halaman ringkasan load balancing.
Buka halaman Load balancing - Click Backends.
- Klik nama layanan backend.
- Klik Edit .
- Klik Konfigurasi lanjutan (Afinitas sesi, waktu tunggu penghentian koneksi, kebijakan keamanan).
- Klik X di samping nama header respons kustom yang ingin Anda hapus.
- Klik Save.
gcloud
Untuk layanan backend, gunakan perintah gcloud compute backend-services
create
atau
gcloud compute backend-services
update
dengan flag --custom-response-header
.
Untuk bucket backend, gunakan perintah gcloud compute backend-buckets
create
atau gcloud compute backend-buckets
update
dengan 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]'
Contoh dengan header X-Frame-Options
:
gcloud compute backend-buckets update gaming-lab \ --custom-response-header='X-Frame-Options: DENY'
Contoh dengan header Strict-Transport-Security
:
Contoh berikut menunjukkan cara menambahkan header respons kustom untuk mendukung HTTP Strict Transport Security (HSTS):
gcloud compute backend-services update customer-bs-name \ --global \ --custom-response-header='Strict-Transport-Security: max-age=63072000'
API
Untuk bucket backend, gunakan
panggilan API
Method: backendBuckets.insert
atau
Method: backendBuckets.update
.
Untuk layanan backend, gunakan
panggilan API
Method: backendServices.insert
atau
Method: backendServices.update
.
Gunakan salah satu panggilan API berikut:
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
Tambahkan cuplikan berikut ke isi permintaan JSON:
"customResponseHeaders":HEADER_NAME:[HEADER_VALUE]
Terraform
Untuk skrip Terraform yang membuat load balancer dengan header kustom, baca artikel Contoh Terraform untuk Load Balancer Aplikasi eksternal global.
Menyetel header respons untuk Cloud Storage
Jika Anda perlu menetapkan header HTTP pada respons dari Cloud Storage—seperti Cross-Origin Resource Policy,
X-Frame-Options
, atau header X-XSS-Protection
—Google Cloud menawarkan
opsi untuk menggunakan header kustom untuk Cloud CDN dengan
Cloud Storage. Anda dapat melakukannya dengan mengonfigurasi header kustom pada level bucket backend load balancer, seperti yang dijelaskan di halaman ini.
Header respons kustom yang dikonfigurasi pada level bucket backend hanya ditambahkan ke respons jika permintaan klien dikirim ke alamat IP load balancer. Header kustom tidak ditambahkan ke respons jika permintaan klien dibuat langsung ke Cloud Storage API.
Menggunakan header kustom dengan Google Cloud Armor
Saat mengonfigurasi kebijakan keamanan Google Cloud Armor, Anda dapat mengonfigurasi Google Cloud Armor untuk menyisipkan header dan nilai kustom. Jika kebijakan keamanan Google Cloud Armor Anda dikonfigurasi untuk memasukkan nama header kustom yang sama dengan Load Balancer Aplikasi eksternal global atau header kustom Load Balancer Aplikasi klasik, nilai header yang ditentukan dalam kebijakan keamanan Google Cloud Armor Anda akan ditimpa oleh nilai yang diisi oleh load balancer. Jika Anda tidak ingin kebijakan Google Cloud Armor ditimpa, pastikan Anda tidak menggunakan nama yang sama.
Batasan
Batasan berikut berlaku untuk header kustom yang digunakan dengan load balancer global:
- Anda dapat menentukan maksimal 16 header permintaan kustom untuk setiap layanan backend.
- Anda dapat menentukan maksimal 16 header respons kustom untuk setiap layanan backend.
- Ukuran total semua header permintaan kustom per layanan backend (nama dan nilai digabungkan, sebelum perluasan variabel) tidak boleh melebihi 8 KB.
- Ukuran total semua header respons kustom per layanan backend (nama dan nilai digabungkan, sebelum perluasan variabel) tidak boleh melebihi 8 KB.
Langkah selanjutnya
- Untuk contoh kasus penggunaan, lihat Mengonfigurasi load balancer dengan backend eksternal.