Membuat header kustom di layanan backend

Halaman ini menjelaskan cara mengonfigurasi header kustom di layanan backend yang digunakan oleh Load Balancer Aplikasi eksternal global.

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 permintaan 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 di-proxy-kan antara backend dan klien. Untuk mengetahui informasi selengkapnya, lihat Proxy target.

Penting: Load Balancer Aplikasi eksternal global juga mendukung transformasi header di peta URL. Anda dapat mengelola header kustom di layanan backend (seperti yang dijelaskan di halaman ini) atau di peta URL. Kemampuannya serupa. Sebaiknya tempatkan transformasi header Anda di peta URL sehingga semua transformasi header Anda dipertahankan di satu lokasi. Jika konfigurasi header kustom ada di peta URL dan layanan backend, kedua konfigurasi tersebut akan diterapkan. Namun, jika header yang sama ditetapkan di layanan backend dan peta URL, peta URL akan diprioritaskan dan setelan layanan backend akan diabaikan. Untuk contoh berbasis peta URL, lihat Menyiapkan pengelolaan traffic untuk Load Balancer Aplikasi eksternal global.

Sebelum memulai

• Jika perlu, update ke Google Cloud CLI versi terbaru:

  gcloud components update
  

  Catatan: Pastikan Anda menggunakan gcloud CLI versi 309.0.0 atau yang lebih baru.

Cara kerja header kustom

Header kustom berfungsi sebagai berikut:

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

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

• Load balancer 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).
• Header Host dapat dikonfigurasi, tetapi tunduk pada batasan tertentu.
• Nama header tidak boleh authority. Ini adalah kata kunci khusus yang dicadangkan oleh Google Cloud. Anda tidak dapat mengubah header ini untuk load balancer berbasis Envoy seperti Load Balancer Aplikasi eksternal global. Sebagai gantinya, sebaiknya Anda membuat header kustom lain agar tidak mengganggu nama header yang dicadangkan.
• Nama header tidak boleh X-User-IP atau CDN-Loop.
• Header hop-by-hop berikut tidak boleh digunakan: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer, Upgrade, Proxy-Authorization, dan Proxy-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, atau X-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 bentuk yang tidak digunakan lagi tidak diizinkan).
• Nilai header dapat kosong.
• Nilai header dapat mencakup satu atau beberapa variabel, yang diapit oleh tanda kurung kurawal, yang diperluas ke nilai yang disediakan load balancer. Daftar variabel yang diizinkan dalam nilai header ada di bagian berikutnya.

Alat command line gcloud memiliki flag untuk menentukan header permintaan, yaitu --custom-request-header. Pastikan untuk mengapit nama header dan nilai header dalam tanda kutip tunggal lurus (') dengan flag ini.

Format umum untuk flag adalah:

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

Berikut adalah contoh nilai header dengan dua variabel, client_region dan client_city, yang diapit dalam tanda kurung kurawal.

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

Untuk membuat layanan backend dengan header kustom, lihat Mengonfigurasi header permintaan kustom.

Header host

Batasan berikut berlaku saat Anda mengonfigurasi header Host kustom dengan Load Balancer Aplikasi eksternal global:

• Anda hanya dapat mengonfigurasi header permintaan Host kustom jika mengganti header permintaan Host yang ada.
• Anda tidak dapat mengonfigurasi header respons Host kustom dengan menggunakan tindakan header dalam peta URL. Namun, Anda masih dapat mengonfigurasi header respons Host kustom di layanan backend.
• Selain itu, hal berikut berlaku untuk header permintaan dan respons:
  • Anda tidak dapat menambahkan atau menghapus header Host kustom.
  • Anda tidak dapat menggunakan variabel dengan header Host kustom.

Catatan: Kami mengumumkan perubahan perilaku untuk header kustom yang dikonfigurasi di peta URL dan layanan backend. Perubahan ini tidak memengaruhi project yang sudah memiliki traffic yang menggunakan header kustom sebelum 14 November 2022. Untuk mengetahui detailnya, lihat catatan rilis untuk 14 November 2022.

Variabel yang didukung dengan nilai header

Variabel berikut dapat muncul dalam 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 log permintaan Cloud CDN di Logging.
cdn_cache_status	Status cache saat ini. Nilainya dapat berupa hit, miss, revalidated, stale, uncacheable, atau disabled untuk objek apa pun yang ditayangkan oleh backend yang mengaktifkan Cloud CDN.
origin_request_header	Mencerminkan nilai header Origin dalam permintaan untuk kasus penggunaan Cross-Origin Resource Sharing (CORS).
client_rtt_msec	Estimasi waktu transmisi round-trip antara load balancer dan klien HTTP(S), dalam milidetik. Ini adalah parameter waktu pergi-pulang (SRTT) yang dihaluskan yang diukur oleh stack TCP load balancer, sesuai dengan RFC 2988. RTT yang dihaluskan adalah algoritma yang menangani variasi dan anomali yang dapat 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 sesuai langsung dengan kode ISO-3166-2.)
client_region_subdivision	Subdivisi, misalnya, provinsi atau negara bagian, dari negara yang terkait dengan alamat IP klien. 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 yang valid untuk variabel ini. Nama kota dapat berisi huruf, angka, spasi, dan karakter berikut US-ASCII: !#$%&'*+-.^_`|~.
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. Ini biasanya sama dengan alamat IP klien yang merupakan alamat kedua terakhir di header X-Forwarded-For, kecuali jika klien menggunakan proxy atau header X-Forwarded-For telah dimodifikasi.
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 ke klien. Hal ini dapat berguna saat beberapa load balancer berbagi backend yang sama. Ini sama dengan alamat IP terakhir di header X-Forwarded-For.
server_port	Nomor port tujuan yang dihubungkan klien.
tls_sni_hostname	Server Name Indication (seperti yang ditentukan dalam RFC 6066), jika diberikan oleh klien selama TLS atau QUIC handshake. Nama host dikonversi menjadi huruf kecil dan 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	Suite cipher yang dinegosiasikan selama TLS handshake. Nilainya adalah empat digit heksadesimal yang ditentukan oleh Registry TLS Cipher Suite IANA, 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	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
• 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. Meskipun header X-Forwarded-For asli berisi informasi lokasi yang valid, Google memperkirakan lokasi klien menggunakan informasi alamat IP sumber yang terdapat dalam paket yang diterima oleh load balancer.

Header yang ditambahkan oleh load balancer akan menimpa header yang ada yang memiliki nama yang sama. Nama header tidak peka huruf besar/kecil. Saat 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 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 buka ({), dan dua tanda kurung kurawal tutup (}}) sebagai satu tanda kurung tutup (}).

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 TLS handshake; jika tidak, false.
client_cert_chain_verified	true jika rantai sertifikat klien diverifikasi terhadap TrustStore yang dikonfigurasi; jika tidak, false.
client_cert_error	String standar yang mewakili kondisi error. Untuk mengetahui informasi selengkapnya tentang string error, lihat mode validasi klien mTLS.
client_cert_sha256_fingerprint	Sidik jari SHA-256 yang dienkode Base64 dari sertifikat klien.
client_cert_serial_number	Nomor seri sertifikat klien. Jika nomor seri lebih panjang dari 50 byte, client_cert_error ditetapkan ke client_cert_serial_number_exceeded_size_limit, 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, ID SPIFFE akan ditetapkan ke string kosong. Jika ID SPIFFE lebih panjang dari 2048 byte, client_cert_error akan ditetapkan ke client_cert_spiffe_id_exceeded_size_limit.
client_cert_uri_sans	Daftar ekstensi SAN dari jenis URI yang dipisahkan koma dan dienkode Base64. 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, client_cert_error akan ditetapkan ke client_cert_uri_sans_exceeded_size_limit, dan daftar yang dipisahkan koma akan ditetapkan ke string kosong.
client_cert_dnsname_sans	Daftar yang dipisahkan koma dan dienkode Base64 dari ekstensi SAN jenis DNSName. Ekstensi SAN diekstrak dari sertifikat klien. Jika client_cert_dnsname_sans lebih panjang dari 512 byte, client_cert_error akan ditetapkan ke client_cert_dnsname_sans_exceeded_size_limit, dan daftar yang dipisahkan koma akan ditetapkan 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 itu sertifikat klien tidak valid. Contoh, 2022-07-01T18:05:09+00:00.
client_cert_issuer_dn	Encoding DER yang dienkode ke Base64 dari kolom Penerbit lengkap 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 ditetapkan ke string kosong.
client_cert_subject_dn	Encoding DER yang dienkode ke Base64 dari kolom Subjek lengkap 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 dibuat dengan sertifikat yang lulus validasi. Encoding sertifikat mematuhi RFC 9440. Hal ini berarti sertifikat DER biner dienkode menggunakan Base64 dan dibatasi dengan titik dua di kedua sisi. 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 ditetapkan ke string kosong.
client_cert_chain	Daftar sertifikat yang dipisahkan koma, dalam urutan TLS standar, dari rantai sertifikat klien untuk koneksi mTLS yang dibuat saat sertifikat klien lulus validasi, tidak termasuk sertifikat akhir. 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 ditetapkan ke string kosong.

Mengonfigurasi header permintaan kustom

Konsol

Untuk menambahkan header permintaan kustom ke layanan backend yang ada:

1. Buka halaman ringkasan load balancing.
   Buka halaman Load balancing
2. Klik Backend.
3. Klik nama layanan backend.
4. Klik Edit .
5. Klik Advanced configurations (Session affinity, connection draining timeout, security policies).
6. Di bagian Header permintaan kustom, klik Tambahkan header.
7. Masukkan Nama header dan Nilai header untuk header permintaan kustom.
8. Masukkan header permintaan kustom tambahan.
9. Klik Simpan.

Untuk menghapus header permintaan kustom dari layanan backend:

1. Buka halaman ringkasan load balancing.
   Buka halaman Load balancing
2. Klik Backend.
3. Klik nama layanan backend.
4. Klik Edit .
5. Klik Advanced configurations (Session affinity, connection draining timeout, security policies).
6. Klik X di samping nama header permintaan kustom yang ingin Anda hapus.
7. Klik Simpan.

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 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 akan mengganti header 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"
]

Mengonfigurasi header respons kustom

Konsol

Untuk menambahkan header respons kustom ke layanan backend yang ada:

1. Buka halaman ringkasan load balancing.
   Buka halaman Load balancing
2. Klik Backend.
3. Klik nama layanan backend.
4. Klik Edit .
5. Klik Advanced configurations (Session affinity, connection draining timeout, security policies).
6. Di bagian Header respons kustom, klik Tambahkan header.
7. Masukkan Nama header dan Nilai header untuk header respons kustom.
8. Masukkan header respons kustom tambahan.
9. Klik Simpan.

Untuk menghapus header respons kustom dari layanan backend:

1. Buka halaman ringkasan load balancing.
   Buka halaman Load balancing
2. Klik Backend.
3. Klik nama layanan backend.
4. Klik Edit .
5. Klik Konfigurasi lanjutan (Afinitas sesi, waktu tunggu pengosongan koneksi, kebijakan keamanan).
6. Klik X di samping nama header respons kustom yang ingin Anda hapus.
7. Klik Simpan.

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]

Menetapkan header respons untuk Cloud Storage

Jika Anda perlu menetapkan header HTTP pada respons dari Cloud Storage—seperti header Cross-Origin Resource Policy, X-Frame-Options, atau X-XSS-Protection—Google Cloud menawarkan opsi untuk menggunakan header kustom untuk Cloud CDN dengan Cloud Storage. Anda dapat melakukannya dengan mengonfigurasi header kustom di tingkat bucket backend load balancer, seperti yang dijelaskan di halaman ini.

Header respons kustom yang dikonfigurasi di tingkat 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 menyisipkan nama header kustom yang sama dengan header kustom Load Balancer Aplikasi eksternal global atau 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:

• Ukuran total semua header permintaan kustom (nama dan nilai digabungkan, sebelum perluasan variabel) untuk setiap layanan backend tidak boleh melebihi 8 KB atau 16 header permintaan.
• Ukuran total semua header respons kustom (nama dan nilai digabungkan, sebelum perluasan variabel) untuk setiap layanan backend tidak boleh melebihi 8 KB atau 16 header respons.