Opsi startup Extensible Service Proxy V2

Extensible Service Proxy V2 (ESPv2) adalah proxy berbasis Envoy yang memungkinkan Cloud Endpoints menyediakan fitur pengelolaan API. Untuk mengonfigurasi ESPv2, Anda dapat menentukan tanda konfigurasi saat men-deploy layanan ESPv2.

Menetapkan tanda konfigurasi

Metode untuk menyetel flag konfigurasi ESPv2 bervariasi berdasarkan platform deployment, seperti yang diuraikan di bagian berikut.

VM Compute Engine

Flag konfigurasi ESPv2 untuk Compute Engine ditentukan dalam perintah docker run. Contoh:

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

Dalam contoh ini, --service, --rollout_strategy, dan --backend adalah tanda konfigurasi ESPv2.

GKE dan Kubernetes

Anda dapat menentukan tanda konfigurasi untuk GKE dan Kubernetes di kolom args pada file manifes deployment. Contoh:

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

Dalam contoh ini, --listener_port, --backend, --service, dan --rollout_strategy adalah flag konfigurasi ESPv2.

Cloud Run untuk platform serverless

Untuk menentukan opsi startup Cloud Run untuk serverless, gunakan variabel lingkungan ESPv2_ARGS. Variabel dapat ditetapkan dalam perintah gcloud run deploy menggunakan opsi --set-env-vars.

Contoh:

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

Dalam contoh ini, --enable_debug adalah tanda konfigurasi ESPv2.

Lihat Cloud Functions untuk OpenAPI, Cloud Run untuk OpenAPI, atau Cloud Run untuk gRPC untuk mengetahui informasi selengkapnya tentang perintah gcloud run deploy.

Untuk menetapkan beberapa argumen dalam variabel lingkungan ESPv2_ARGS, tentukan pembatas kustom dan gunakan pembatas tersebut untuk memisahkan beberapa argumen. Jangan gunakan koma sebagai pembatas. Tempatkan pembatas kustom di awal variabel lingkungan ESPv2_ARGS, yang diapit oleh tanda sisipan.

Contoh berikut menggunakan ++ sebagai pemisah: 

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

Jika tanda yang Anda tetapkan berisi koma, Anda harus menetapkan variabel lingkungan ESPv2_ARGS dalam skrip gcloud_build_image.

Misalnya, untuk menambahkan tanda --cors_allow_methods=PUT,POST,GET:

  • Download skrip gcloud_build_image.
  • Edit gcloud_build_image seperti yang ditunjukkan di bawah: 
    cat <<EOF > Dockerfile
  FROM BASE_IMAGE

  ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
  COPY service.json \ENDPOINTS_SERVICE_PATH

  ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials

  ENTRYPOINT ["/env_start_proxy.py"]
  EOF
  • Jalankan skrip gcloud_build_image untuk membangun image.

Flag konfigurasi ESPv2

Flag konfigurasi ESPv2 dapat dikelompokkan ke dalam kategori berikut:

Contoh generik tambahan dan teks bantuan untuk tanda ESPv2 dapat ditemukan di repositori GitHub.

Konfigurasi Non-Serverless

Flag ini diperlukan untuk menjalankan ESPv2 di platform non-serverless, seperti GKE, Compute Engine, dan Kubernetes. Tidak dapat ditetapkan saat di-deploy di Cloud Run untuk platform serverless.

``

Flag Deskripsi
--service Menetapkan nama layanan Endpoints.
--version Menetapkan ID konfigurasi layanan dari layanan Endpoints.
--rollout_strategy Menentukan strategi peluncuran konfigurasi layanan, [fixed|managed]. Default-nya adalah fixed.
--listener_port Mengidentifikasi port untuk menerima koneksi hilir. Layanan ini mendukung koneksi HTTP/1.x, HTTP/2, dan gRPC. Defaultnya adalah 8080.
--backend Menentukan alamat server aplikasi backend lokal. Skema yang valid adalah http, https, grpc, dan grpcs jika disertakan. Skema default adalah >http.

Logging

Gunakan flag ini untuk mengonfigurasi ESPv2 agar menulis informasi tambahan ke log Stackdriver.

Flag Deskripsi
--log_request_headers

Mencatat nilai header permintaan yang ditentukan, dipisahkan dengan koma tanpa spasi. Misalnya, tetapkan tanda ini sebagai:

--log_request_headers=foo,bar

Jika nilai untuk header "foo" dan "bar" tersedia dalam permintaan, log Endpoints akan berisi:

request_headers: foo=foo_value;bar=bar_value

--log_response_headers

Mencatat nilai header respons yang ditentukan, dipisahkan dengan koma tanpa spasi. Misalnya, tetapkan tanda ini sebagai:

--log_response_headers=baz,bing

Jika nilai untuk header "baz" dan "bing" tersedia dalam respons, log Endpoints akan berisi:

response_headers: baz=baz_value;bing=bing_value

--log_jwt_payloads

Mencatat nilai kolom primitif payload JWT yang ditentukan, dipisahkan dengan koma tanpa spasi. Misalnya, tetapkan tanda ini sebagai:

--log_jwt_payload=sub,project_id,foo.foo_name

Jika nilai tersedia di payload JWT, log Endpoints akan berisi:

jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value

Nilai dalam payload JWT harus berupa kolom primitif (string, bilangan bulat). Objek dan array JSON tidak dicatat.
--access_log

Jika ditentukan, jalur ke file lokal tempat entri log akses akan ditulis.
--access_log_format

Format string untuk menentukan format log akses. Jika tidak disetel, >string format default akan digunakan. Untuk tata bahasa format yang mendetail, lihat referensi string format.

Pelacakan

Gunakan flag ini untuk mengonfigurasi data pelacakan ESPv2 yang dikirim ke Stackdriver. Flag ini hanya berlaku jika pelacakan diaktifkan.

Flag Deskripsi
--disable_tracing

Nonaktifkan perekaman aktivitas. Secara default, pelacakan diaktifkan.

Jika diaktifkan, ESPv2 akan mengambil sampel sejumlah kecil permintaan ke API Anda setiap detik untuk mendapatkan rekaman aktivitas yang dikirim ke Stackdriver Trace. Secara default, 1 dari 1.000 permintaan diambil sampelnya. Gunakan flag --tracing_sample_rate untuk mengubah frekuensi pengambilan sampel.

--tracing_project_id

ID project Google untuk pelacakan Stackdriver.

Tracing adalah layanan berbayar. Project yang ditentukan akan ditagih untuk pelacakan.

Secara default, project ID layanan ESPv2 yang di-deploy akan ditagih.

Project ID ditentukan dengan memanggil Google Cloud Server Metadata Instance saat startup. Jika ESPv2 di-deploy di luar Google Cloud (menggunakan flag --non_gcp), maka pelacakan akan otomatis dinonaktifkan kecuali jika flag ini ditetapkan secara eksplisit.

--tracing_sample_rate

Tetapkan rasio pengambilan sampel rekaman aktivitas ke nilai dari 0,0 hingga 1,0. Nilai ini menentukan fraksi permintaan yang diambil sampelnya.

Nilai defaultnya adalah 0,001, yang setara dengan 1 dari 1.000 permintaan.

--tracing_incoming_context

Flag ini menentukan header HTTP mana yang akan diperiksa untuk konteks rekaman aktivitas, dengan nilai flag yang dipisahkan oleh koma tanpa spasi. Perhatikan bahwa urutan itu penting: konteks rekaman aktivitas akan diambil dari header pertama yang cocok.

Nilai yang mungkin mencakup traceparent, x-cloud-trace-context, dan grpc-trace-bin.

Jika tidak ada, header traceparent dan x-cloud-trace-context akan diperiksa (secara berurutan).

Lihat Melakukan Penelusuran API Anda untuk mengetahui detail selengkapnya.
--tracing_outgoing_context

Menetapkan header konteks rekaman aktivitas dalam permintaan yang dikirim ke layanan backend.

Flag ini menentukan header HTTP mana yang akan ditetapkan, dengan nilai flag yang dipisahkan oleh koma tanpa spasi.

Nilai yang mungkin mencakup traceparent, x-cloud-trace-context, dan grpc-trace-bin.

Jika tidak ada, header traceparent dan x-cloud-trace-context akan dikirim.

Lihat Melakukan Penelusuran API Anda untuk mengetahui detail selengkapnya.

Health Check

Gunakan flag ini untuk mengonfigurasi health check untuk ESPv2. Flag pertama dapat digunakan untuk menyiapkan handler kesehatan guna merespons panggilan pemeriksaan kesehatan. Flag lainnya dapat digunakan untuk mengaktifkan pemeriksaan kondisi untuk backend gRPC.

/tbody>
Flag Deskripsi
-z, --healthz Tentukan endpoint pemeriksaan kesehatan. Misalnya, -z healthz membuat ESPv2 menampilkan kode 200 untuk jalur /healthz.
--health_check_grpc_backend Aktifkan ESPv2 untuk memeriksa layanan Health gRPC secara berkala untuk backend yang ditentukan oleh tanda --backend. Backend harus menggunakan protokol gRPC dan menerapkan Protokol Health Check gRPC. Endpoint health check yang diaktifkan oleh tanda --healthz akan mencerminkan hasil health check backend.
--health_check_grpc_backend_service Tentukan nama layanan saat memanggil Protokol Health Check gRPC backend. Nilai tanda ini hanya diterapkan saat tanda --health_check_grpc_backend digunakan. Opsional, jika tidak disetel, defaultnya adalah kosong. Nama layanan kosong digunakan untuk mengkueri status kesehatan keseluruhan server gRPC.
--health_check_grpc_backend_interval Tentukan interval pemeriksaan dan waktu tunggu permintaan saat memanggil layanan Health gRPC backend. Nilai tanda ini hanya diterapkan saat tanda --health_check_grpc_backend digunakan. Defaultnya adalah 1 detik. Format yang diterima adalah urutan bilangan desimal, masing-masing dengan pecahan opsional dan akhiran satuan, seperti "5s", "100ms", atau "2m". Unit waktu yang valid adalah "m" untuk menit, "s" untuk detik, dan "ms" untuk milidetik.

Proses Debug

Gunakan flag ini untuk mengonfigurasi proses debug untuk ESPv2. Flag ini dapat digunakan untuk menyiapkan port admin Envoy guna mengambil konfigurasi dan statistik atau menjalankan Envoy dalam mode debug untuk menulis informasi tingkat debug ke log.

Flag Deskripsi
--status_port, --admin_port Aktifkan admin ESPv2 Envoy di port ini. Lihat referensi antarmuka administrasi Envoy untuk mengetahui detail selengkapnya. Port admin dinonaktifkan secara default.
--enable_debug Aktifkan log tingkat debug dan tambahkan header debug.

Non-Google Cloud Deployment

Jika ESPv2 di-deploy di lingkungan non Google Cloud , flag berikut mungkin diperlukan.

Flag Deskripsi
--service_account_key

Menentukan file JSON kunci akun layanan untuk mengakses layanan Google. Jika opsi ini tidak ada, proxy akan menghubungi server metadata Google Cloud untuk mengambil token akses.

--dns_resolver_addresses Alamat resolver DNS. Setiap alamat harus dalam format IP_ADDR atau IP_ADDR:PORT dan dipisahkan dengan titik koma (;). Untuk IP_ADDR, port DNS default 52 akan digunakan. Misalnya: --dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000) Jika tidak disetel, ESPv2 akan menggunakan resolver default yang dikonfigurasi di /etc/resolv.conf
--backend_dns_lookup_family Tentukan keluarga pencarian DNS untuk semua backend. Opsinya adalah auto, v4only, v6only, v4preferred, dan all. Defaultnya adalah v4preferred. Perhatikan bahwa auto adalah nilai lama. Menetapkan flag ke auto akan menghasilkan perilaku yang setara dengan v6preferred.
--non_gcp Secara default, proxy mencoba terhubung ke Google Cloud Server Metadata untuk mendapatkan lokasi VM dalam beberapa permintaan pertama. Untuk melewati langkah ini, tetapkan tanda ini ke true.

Pengujian Lokal

ESPv2 dapat di-deploy secara lokal di workstation Anda untuk pengujian. Lihat Menjalankan ESP secara lokal atau di platform lain untuk mengetahui detail selengkapnya.

Gunakan tanda ini bersama dengan Tanda deployment Non-Google Cloud untuk deployment dan pengujian lokal yang lebih mudah dalam continuous integration.

Flag Deskripsi
--service_json_path

Tentukan jalur bagi ESPv2 untuk memuat konfigurasi layanan endpoint. Dengan tanda ini, ESPv2 akan menggunakan strategi peluncuran "tetap" dan tanda berikut akan diabaikan:

  • --service
  • --version
  • --rollout_strategy

Flag ini akan mencegah ESPv2 menggunakan kuota Service Management API.

--enable_backend_address_override

Alamat backend dapat ditentukan menggunakan tanda --backend atau kolom backend.rule.address dalam konfigurasi layanan. Untuk pengguna OpenAPI, perhatikan bahwa kolom backend.rule.address ditetapkan oleh kolom address di ekstensi x-google-backend.

Konfigurasi layanan per operasi backend.rule.address biasanya ditentukan untuk perutean serverless. Secara default, backend.rule.address akan diprioritaskan daripada flag --backend untuk setiap operasi.

Aktifkan tanda ini jika Anda ingin tanda --backend diprioritaskan. Hal ini berguna jika Anda melakukan pengembangan di workstation lokal. Kemudian, Anda dapat menggunakan konfigurasi layanan produksi yang sama, tetapi mengganti alamat backend melalui tanda --backend untuk pengujian lokal.

Catatan: Hanya alamat yang akan diganti. Semua komponen backend.rule lainnya akan tetap berlaku (batas waktu, autentikasi backend, terjemahan jalur, dll.).

Ekstraksi IP Klien

Gunakan tanda ini untuk mengonfigurasi ekstraksi IP klien untuk ESPv2.

Flag Deskripsi
--envoy_use_remote_address

Konfigurasi HttpConnectionManager Envoy, lihat referensi Envoy untuk mengetahui informasi mendetail. Defaultnya adalah nonaktif.

--envoy_xff_num_trusted_hops Konfigurasi HttpConnectionManager Envoy, lihat referensi Envoy untuk mengetahui informasi mendetail. Nilai defaultnya adalah 2.

Dukungan CORS

Lihat Mendukung CORS untuk mengetahui deskripsi opsi dukungan CORS yang tersedia. Bagian ini menjelaskan penggunaan flag startup ESPv2 untuk mendukung CORS.

Untuk mengaktifkan dukungan CORS di ESPv2, sertakan opsi --cors_preset dan tetapkan salah satu flag berikut:

  • --cors_preset=basic
  • --cors_preset=cors_with_regex

Jika Anda menyertakan --cors_preset=basic atau --cors_preset=cors_with_regex, ESPv2:

  • Mengasumsikan semua jalur lokasi memiliki kebijakan CORS yang sama.
  • Merespons permintaan sederhana dan permintaan preflight HTTP OPTIONS.
  • Meng-cache hasil permintaan pra-penerbangan OPTIONS hingga 20 hari (1728000 detik).

  • Menetapkan header respons ke nilai berikut:

    Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization
Access-Control-Expose-Headers: Content-Length,Content-Range
Access-Control-Max-Age: 1728000

Untuk mengganti nilai default Access-Control-Allow-Origin, tentukan salah satu opsi berikut:

Opsi Deskripsi
--cors_allow_origin Gunakan dengan --cors_preset=basic untuk menyetel Access-Control-Allow-Origin ke asal tertentu.
Contoh:
--cors_preset=basic
--cors_allow_origin=http://example.com
--cors_allow_origin_regex Gunakan dengan --cors_preset=cors_with_regex. Memungkinkan Anda menggunakan ekspresi reguler untuk menyetel Access-Control-Allow-Origin.
Contoh:
--cors_preset=cors_with_regex
--cors_allow_origin_regex=^https?://.+\.example\.com$

Ekspresi reguler dalam contoh sebelumnya mengizinkan asal dengan http atau https dan subdomain apa pun dari example.com.

Saat menyetel opsi ini dalam file konfigurasi Kubernetes, Anda perlu menambahkan karakter garis miring terbalik tambahan untuk meng-escape kedua instance \. dalam string, misalnya:

"--cors_preset","cors_with_regex",
"--cors_allow_origin_regex","^https?://.+\\.example\\.com$"

Saat Anda menyetel opsi ini dalam skrip gcloud_build_image untuk Cloud Run, coba hindari penggunaan karakter yang di-escape dan garis miring terbalik, karena mungkin tidak diteruskan dengan benar dari skrip bash ke proxy saat startup. Gunakan class karakter, bukan urutan meta. Contoh: Original: \d Recommended: [0-9]

Setelah menyetel --cors_preset=basic atau --cors_preset=cors_with_regex untuk mengaktifkan CORS, Anda dapat mengganti nilai default header respons lainnya dengan menentukan satu atau beberapa opsi berikut:

Opsi Deskripsi
--cors_allow_methods Menetapkan Access-Control-Allow-Methods ke metode HTTP yang ditentukan. Tentukan metode HTTP sebagai string dengan setiap metode HTTP dipisahkan oleh koma.
Contoh:
--cors_preset=basic
--cors_allow_methods=GET,POST,PUT,OPTIONS
--cors_allow_headers Menetapkan Access-Control-Allow-Headers ke header HTTP yang ditentukan. Tentukan header HTTP sebagai string dengan setiap header HTTP dipisahkan dengan koma.
Contoh:
--cors_preset=basic
--cors_allow_headers=Origin,Content-Type,Accept
--cors_allow_credentials Menyertakan header Access-Control-Allow-Credentials dengan nilai true dalam respons. Secara default, header Access-Control-Allow-Credentials tidak disertakan dalam respons.
Contoh:
--cors_preset=basic
--cors_allow_credentials
--cors_expose_headers Menetapkan Access-Control-Expose-Headers ke header yang ditentukan. Tentukan header mana yang dapat diekspos sebagai bagian dari respons sebagai string dengan setiap header yang dipisahkan oleh koma.
Contoh:
--cors_preset=basic
--cors_expose_headers=Content-Length
--cors_max_age Menetapkan Access-Control-Max-Age ke durasi waktu yang ditentukan. Format yang dapat diterima adalah urutan angka desimal, yang masing-masing memiliki nilai pecahan opsional dan akhiran satuan, seperti "300m", "1,5h", atau "2h45m". Satuan waktu yang valid adalah "m" untuk menit, "h" untuk jam. Nilai defaultnya adalah "480h" jika tidak ditetapkan.
Contoh:
--cors_preset=basic
--cors_max_age=24h

Dukungan TLS

Gunakan tanda ini untuk mengonfigurasi ESPv2 agar menggunakan koneksi TLS.

Flag Deskripsi
--ssl_server_cert_path Jalur sertifikat server proxy. Jika dikonfigurasi, ESPv2 hanya menerima koneksi aman HTTP/1.x dan HTTP/2 di listener_port. Memerlukan file sertifikat dan kunci "server.crt" dan "server.key" dalam jalur ini.
--ssl_server_cipher_suites Cipher suite yang akan digunakan untuk koneksi hilir, yang ditentukan sebagai daftar yang dipisahkan koma. Lihat Konfigurasi cipher suite.
--ssl_backend_client_cert_path Jalur sertifikat klien proxy. Jika dikonfigurasi, ESPv2 akan mengaktifkan autentikasi bersama TLS untuk backend HTTPS. Memerlukan file sertifikat dan kunci "client.crt" dan "client.key" dalam jalur ini.
--ssl_backend_client_root_certs_file Jalur file sertifikat root yang digunakan ESPv2 untuk memverifikasi sertifikat server backend. Jika tidak ditentukan, ESPv2 menggunakan "/etc/ssl/certs/ca-certificates.crt" secara default.
--ssl_backend_client_cipher_suites Cipher suite yang akan digunakan untuk backend HTTPS, ditentukan sebagai daftar yang dipisahkan koma. Lihat Konfigurasi cipher suite.
--ssl_minimum_protocol Versi protokol TLS minimum untuk koneksi sisi klien. Lihat artikel ini
--ssl_maximum_protocol Versi protokol TLS maksimum untuk koneksi sisi klien. Lihat artikel ini
--enable_strict_transport_security Aktifkan HSTS (HTTP Strict Transport Security). Header respons "Strict-Transport-Security" dengan nilai "max-age=31536000; includeSubdomains;" ditambahkan untuk semua respons.
--generate_self_signed_cert Buat sertifikat dan kunci yang ditandatangani sendiri saat memulai, lalu simpan di "/tmp/ssl/endpoints/server.crt" dan "/tmp/ssl/endpoints/server.key". Hal ini berguna jika hanya sertifikat penandatanganan sendiri acak yang diperlukan untuk melayani permintaan HTTPS. Sertifikat yang dibuat akan memiliki Nama Umum "localhost" dan berlaku selama 10 tahun.

Waktu Tunggu dan Coba Lagi

Gunakan flag ini untuk mengonfigurasi waktu tunggu dan percobaan ulang panggilan HTTP jarak jauh untuk ESPv2.

Flag Deskripsi
--http_request_timeout_s

Tetapkan waktu tunggu dalam hitungan detik untuk permintaan yang dibuat ke layanan eksternal, kecuali Backend dan Kontrol Layanan Google. Hal ini mencakup Google ServiceManagement, server Metadata, dan server Google IAM. Harus > 0 dan defaultnya adalah 30 detik jika tidak ditetapkan.

--service_control_network_fail_policy

Jika terjadi kegagalan jaringan saat terhubung ke kontrol layanan Google, permintaan akan diizinkan jika tanda ini terbuka. Defaultnya adalah open.

--service_control_check_timeout_ms Menetapkan waktu tunggu dalam milidetik untuk permintaan Check kontrol layanan. Harus > 0 dan defaultnya adalah 1000 jika tidak ditetapkan.
--service_control_report_timeout_ms Tetapkan waktu tunggu dalam milidetik untuk permintaan Laporan kontrol layanan. Harus > 0 dan defaultnya adalah 1000 jika tidak ditetapkan.
--service_control_quota_timeout_ms Menetapkan waktu tunggu dalam milidetik untuk permintaan Kuota kontrol layanan. Harus > 0 dan defaultnya adalah 1000 jika tidak ditetapkan.
--service_control_check_retries Menetapkan waktu percobaan ulang untuk permintaan Check kontrol layanan. Harus >= 0 dan defaultnya adalah 3 jika tidak ditetapkan
--service_control_report_retries Menetapkan waktu percobaan ulang untuk permintaan Report kontrol layanan. Harus >= 0 dan defaultnya adalah 5 jika tidak ditetapkan
--service_control_quota_retries Menetapkan waktu percobaan ulang untuk permintaan Kuota kontrol layanan. Harus >= 0 dan defaultnya adalah 1 jika tidak ditetapkan
--backend_retry_ons

Kondisi saat ESPv2 mencoba lagi di backend. Satu atau beberapa kondisi retryOn dapat ditentukan menggunakan daftar yang dipisahkan koma. Defaultnya adalah reset,connect-failure,refused-stream. Nonaktifkan percobaan ulang dengan menyetel tanda ini ke kosong.

Lihat link berikut untuk mengetahui kondisi yang diterima:

--backend_retry_num Jumlah upaya percobaan ulang yang diizinkan. Harus >= 0 dan defaultnya adalah 1.

Transcoding gRPC

Gunakan tanda ini untuk mengonfigurasi ESPv2 untuk transcoding HTTP/JSON ke gRPC.

Flag Deskripsi
--transcoding_always_print_primitive_fields

Menentukan apakah akan mencetak kolom primitif untuk transkode grpc-json. Secara default, kolom primitif dengan nilai default akan dihilangkan dalam output JSON. Misalnya, kolom int32 yang disetel ke 0 akan dihilangkan. Menetapkan tanda ini ke true akan menggantikan perilaku default dan mencetak kolom primitif terlepas dari nilainya. Nilai defaultnya adalah false.

--transcoding_always_print_enums_as_ints

Menentukan apakah akan mencetak enum sebagai int untuk transkode grpc-json. Secara default, nilai tersebut dirender sebagai string. Nilai defaultnya adalah false.

--transcoding_stream_newline_delimited

Jika benar, gunakan pembatas baris baru untuk memisahkan pesan streaming respons. Jika salah (false), semua pesan streaming respons ditranskode ke dalam array JSON.

--transcoding_case_insensitive_enum_parsing

Biasanya, nilai enum proto harus dalam huruf besar saat digunakan dalam JSON. Setel tanda ini ke benar (true) jika permintaan JSON Anda menggunakan nilai enum non-huruf besar.

--transcoding_preserve_proto_field_names

Menentukan apakah akan mempertahankan nama kolom proto untuk transkode grpc-json. Secara default, protobuf akan membuat nama kolom JSON menggunakan opsi json_name, atau lower camel case, dalam urutan tersebut. Menyetel tanda ini akan mempertahankan nama kolom asli. Nilai defaultnya adalah false.

--transcoding_ignore_query_parameters

Daftar parameter kueri yang dipisahkan koma untuk diabaikan untuk pemetaan metode transkode dalam transkode grpc-json. Secara default, filter transkoder tidak akan mentranskode permintaan dengan parameter kueri yang tidak diketahui/tidak valid.

--transcoding_ignore_unknown_query_parameters

Menentukan apakah akan mengabaikan parameter kueri yang tidak dapat dipetakan ke kolom protobuf yang sesuai dalam transcoding grpc-json. Gunakan ini jika Anda tidak dapat mengontrol parameter kueri dan tidak mengetahuinya sebelumnya. Jika tidak, gunakan --transcoding_ignore_query_parameters. Nilai defaultnya adalah false.

--transcoding_query_parameters_disable_unescape_plus

Secara default, tanda plus "+" dalam parameter kueri tidak di-escape menjadi spasi " " dalam transkode grpc-json. Hal ini untuk mendukung HTML 2.0. Jika tidak diinginkan, setel tanda ini ke benar (true) untuk menonaktifkan fitur ini.

Modifikasi Permintaan dan Respons

Gunakan flag ini untuk mengonfigurasi ESPv2 agar memodifikasi permintaan dan respons sebagian.

Flag Deskripsi
--add_request_header

Tambahkan header HTTP ke permintaan sebelum mengirimkannya ke backend upstream. Jika header sudah ada dalam permintaan, nilainya akan diganti dengan nilai yang baru.

Fitur ini mendukung variabel kustom Envoy.

Argumen ini dapat diulang beberapa kali untuk menentukan beberapa header. Misalnya:
--add_request_header=key1=value1
--add_request_header=key2=value2.

--append_request_header

Tambahkan header HTTP ke permintaan sebelum mengirimkannya ke backend upstream. Jika header sudah ada dalam permintaan, nilai baru akan ditambahkan.

Fitur ini mendukung variabel kustom Envoy.

Argumen ini dapat diulang beberapa kali untuk menentukan beberapa header. Misalnya:
--append_request_header=key1=value1
--append_request_header=key2=value2.

--add_response_header

Tambahkan header HTTP ke respons sebelum mengirimkannya ke klien downstream. Jika header sudah ada dalam respons, header tersebut akan diganti dengan header baru.

Fitur ini mendukung variabel kustom Envoy.

Argumen ini dapat diulang beberapa kali untuk menentukan beberapa header. Misalnya:
--add_response_header=key1=value1
--add_response_header=key2=value2.

--append_response_header

Tambahkan header HTTP ke respons sebelum mengirimkannya ke klien downstream. Jika header sudah ada dalam respons, header baru akan ditambahkan.

Fitur ini mendukung variabel kustom Envoy.

Argumen ini dapat diulang beberapa kali untuk menentukan beberapa header. Misalnya:
--append_response_header=key1=value1
--append_response_header=key2=value2.

Opsi Keamanan

Gunakan flag ini untuk lebih menyaring permintaan yang diizinkan ESPv2.

Flag Deskripsi
--underscores_in_headers

Mengizinkan nama header yang berisi garis bawah untuk diteruskan. Nilai defaultnya adalah false.

Karakter garis bawah diizinkan dalam nama header oleh RFC-7230. Namun, perilaku ini diterapkan sebagai langkah keamanan karena beberapa sistem memperlakukan _ dan - sebagai sesuatu yang dapat dipertukarkan.

--envoy_connection_buffer_limit_bytes

Mengonfigurasi jumlah maksimum data yang di-buffer untuk setiap isi permintaan/respons, dalam byte. Jika tidak disetel, default akan ditentukan oleh Envoy. Lihat Konfigurasi pemroses Envoy.

--disable_normalize_path

Menonaktifkan normalisasi header HTTP path sesuai dengan RFC 3986. Sebaiknya tetap aktifkan opsi ini jika backend Anda melakukan normalisasi jalur secara default.

Tabel berikut memberikan contoh permintaan path yang akan diterima backend dari ESPv2 berdasarkan konfigurasi flag ini. 

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello/../world  | Rejected              | /world             |
        | /%4A             | /%4A                  | /J                 |
        | /%4a             | /%4a                  | /J                 |
        -----------------------------------------------------------------

Secara default, ESPv2 akan menormalisasi jalur. Nonaktifkan fitur ini hanya jika traffic Anda terpengaruh oleh perilaku tersebut.

Catatan: Mengikuti RFC 3986, opsi ini tidak meng-unescape karakter garis miring yang dienkode persen. Lihat tanda --disallow_escaped_slashes_in_path untuk mengaktifkan perilaku yang tidak mematuhi kebijakan ini.

Catatan: Normalisasi huruf besar/kecil dari RFC 3986 tidak didukung, meskipun opsi ini diaktifkan.

Untuk mengetahui detail selengkapnya, lihat Memahami Pembuatan Template Jalur.

--disable_merge_slashes_in_path

Menonaktifkan penggabungan garis miring yang berdekatan di header HTTP path. Sebaiknya tetap aktifkan opsi ini jika backend Anda melakukan penggabungan secara default.

Tabel berikut memberikan contoh permintaan path yang akan diterima backend dari ESPv2 berdasarkan konfigurasi flag ini. 

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello//world    | Rejected              | /hello/world       |
        | /hello///        | Rejected              | /hello             |
        -----------------------------------------------------------------

Secara default, ESPv2 akan menggabungkan garis miring. Nonaktifkan fitur ini hanya jika traffic Anda terpengaruh oleh perilaku tersebut.

Untuk mengetahui detail selengkapnya, lihat Memahami Pembuatan Template Jalur.

--disallow_escaped_slashes_in_path

Tidak mengizinkan permintaan dengan karakter garis miring yang di-escape dan dienkode persen:

  • %2F atau %2f diperlakukan sebagai /
  • %5C atau %5c diperlakukan sebagai \

Jika diaktifkan, perilaku ini bergantung pada protokol yang digunakan:

  • Untuk backend OpenAPI, jalur permintaan dengan garis miring yang di-escape dan dienkode persen akan otomatis di-unescape melalui pengalihan.
  • Untuk backend gRPC, jalur permintaan dengan garis miring yang di-escape dan dienkode persen akan ditolak (gRPC tidak mendukung pengalihan).

Opsi ini tidak sesuai dengan RFC 3986, jadi opsi ini dinonaktifkan secara default. Jika backend Anda tidak mematuhi RFC 3986 dan meng-escape garis miring, Anda harus mengaktifkan opsi ini di ESPv2. Tindakan ini akan mencegah serangan kebingungan jalur yang mengakibatkan persyaratan keamanan tidak diterapkan.

Untuk mengetahui detail selengkapnya, lihat Memahami Pembuatan Template Jalur.

Autentikasi JWT

Gunakan tanda ini untuk mengonfigurasi ESPv2 agar mengambil Jwks jarak jauh dengan percobaan ulang.

Flag Deskripsi
--jwks_fetch_num_retries

Tentukan jumlah percobaan ulang dalam kebijakan percobaan ulang pengambilan JWKS jarak jauh. Defaultnya adalah 0, tidak ada percobaan ulang.

--jwks_fetch_retry_back_off_base_interval_ms

Tentukan interval backoff eksponensial percobaan ulang pengambilan JWKS, dalam milidetik. Nilai defaultnya adalah 200 md, jika tidak ditetapkan.

--jwks_fetch_retry_back_off_max_interval_ms

Tentukan interval maksimum backoff eksponensial percobaan ulang pengambilan JWKS, dalam milidetik. Nilai defaultnya adalah 32 detik, jika tidak ditetapkan.

--jwks_cache_duration_in_s

Tentukan durasi cache kunci publik JWT dalam detik. Defaultnya adalah 5 menit, jika tidak disetel.

--jwks_async_fetch_fast_listener

Hanya berlaku jika tanda --disable_jwks_async_fetch tidak ditetapkan. Flag ini menentukan apakah ESPv2 akan menunggu pengambilan jwks awal selesai sebelum mengikat port pemroses. Jika salah, perintah akan menunggu. Defaultnya adalah "false".

--jwt_cache_size

Tentukan jumlah token JWT unik sebagai ukuran cache JWT maksimum. Cache hanya menyimpan token terverifikasi. Jika 0, cache JWT dinonaktifkan. Flag ini membatasi penggunaan memori untuk cache JWT. Memori yang digunakan cache kira-kira (ukuran token + 64 byte) per token. Jika tidak ditentukan, nilai defaultnya adalah 100000.

--disable_jwt_audience_service_name_check

Biasanya, kolom aud JWT diperiksa berdasarkan audiens yang ditentukan di kolom x-google-audiences OpenAPI. Flag ini mengubah perilaku saat kolom x-google-audiences tidak ditentukan. Jika kolom x-google-audiences tidak ditentukan, dan tanda ini tidak digunakan, nama layanan akan digunakan untuk memeriksa kolom aud JWT. Jika tanda ini digunakan, kolom aud JWT tidak akan diperiksa.

Langkah berikutnya

Pelajari: