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 flag konfigurasi saat men-deploy layanan ESPv2.

Menyetel flag konfigurasi

Metode untuk menyetel tanda 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 flag konfigurasi ESPv2.

GKE dan Kubernetes

Anda dapat menentukan flag konfigurasi untuk GKE dan Kubernetes di kolom args pada file manifes deployment Anda. 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

Guna menentukan opsi startup untuk Cloud Run untuk model 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 for OpenAPI, atau Cloud Run for gRPC untuk mengetahui informasi selengkapnya tentang perintah gcloud run deploy.

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

Contoh berikut menggunakan ++ sebagai pembatas:

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 di skrip gcloud_build_image.

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

  • Download skrip gcloud_build_image.
  • Edit gcloud_build_image seperti yang ditunjukkan di bawah ini:
    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 mem-build image.

Tanda konfigurasi ESPv2

Tanda konfigurasi ESPv2 dapat dikelompokkan ke dalam kategori berikut:

Contoh umum 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. Atribut ini tidak dapat ditetapkan saat di-deploy di Cloud Run untuk platform serverless.

``

Tanda Deskripsi
--service Menetapkan nama layanan Endpoint.
--version Menetapkan ID konfigurasi layanan dari layanan Endpoint.
--rollout_strategy Menentukan strategi peluncuran konfigurasi layanan, [fixed|managed]. Defaultnya adalah diperbaiki.
--listener_port Mengidentifikasi port untuk menerima koneksi downstream. Solusi 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 defaultnya adalah >http.

Logging

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

Tanda Deskripsi
--log_request_headers

Catat 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 Endpoint akan berisi:

request_headers: foo=foo_value;bar=bar_value

--log_response_headers

Catat 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 Endpoint akan berisi:

response_headers: baz=baz_value;bing=bing_value

--log_jwt_payloads

Catat 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 dalam payload JWT, log Endpoint 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 mengetahui tata bahasa format yang mendetail, lihat referensi string format.

Tracing

Gunakan tanda ini untuk mengonfigurasi data pelacakan ESPv2 yang dikirim ke Stackdriver. Tanda ini hanya berlaku saat pelacakan diaktifkan.

Tanda Deskripsi
--disable_tracing

Nonaktifkan perekaman aktivitas. Secara default, perekaman aktivitas diaktifkan.

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

--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 Server Metadata Instance Google Cloud saat memulai. Jika ESPv2 di-deploy di luar Google Cloud (menggunakan flag --non_gcp), pelacakan akan otomatis dinonaktifkan, kecuali jika flag ini ditetapkan secara eksplisit.

--tracing_sample_rate

Menetapkan frekuensi sampling trace 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 yang akan diperiksa konteks pelacakannya, dengan nilai flag yang dipisahkan koma tanpa spasi. Perhatikan bahwa urutan itu penting: konteks pelacakan akan diambil dari header pertama yang cocok.

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

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

Lihat Melacak API Anda untuk detail selengkapnya.

--tracing_outgoing_context

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

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

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

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

Lihat Melacak API Anda untuk detail selengkapnya.

Health Check

Gunakan tanda ini guna mengonfigurasi health check untuk ESPv2. Flag pertama dapat digunakan untuk menyiapkan pengendali health guna merespons panggilan health check. Tanda lainnya dapat digunakan untuk mengaktifkan health check untuk backend gRPC.

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

Proses Debug

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

Tanda Deskripsi
--status_port, --admin_port Aktifkan admin Envoy ESPv2 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.

Deployment Non-Google Cloud

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

Tanda Deskripsi
--service_account_key

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

--dns_resolver_addresses Alamat DNS resolver. Setiap alamat harus memiliki format IP_ADDR atau IP_ADDR:PORT dan dipisahkan dengan titik koma (;). Untuk IP_ADDR, port DNS default 52 akan digunakan. Contoh: --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 kelompok pencarian DNS untuk semua backend. Opsinya adalah auto, v4only, v6only, v4preferred, dan all. Setelan defaultnya adalah v4preferred. Perhatikan bahwa auto adalah nilai lama. Menyetel tanda ke auto akan menghasilkan perilaku yang setara dengan v6preferred.
--non_gcp Secara default, proxy mencoba terhubung ke Server Metadata Google Cloud 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 detail selengkapnya.

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

Tanda 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

Tanda 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 dalam ekstensi x-google-backend.

backend.rule.address konfigurasi layanan per operasi biasanya ditentukan untuk perutean tanpa server. Secara default, backend.rule.address akan lebih diprioritaskan daripada flag --backend untuk setiap operasi individual.

Aktifkan flag ini jika Anda ingin flag --backend lebih 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 flag --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 guna mengonfigurasi ekstraksi IP klien untuk ESPv2.

Tanda Deskripsi
--envoy_use_remote_address

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

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

Dukungan CORS

Lihat Dukungan CORS untuk 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 permintaan sederhana dan preflight HTTP OPTIONS.
  • Menyimpan hasil permintaan OPTIONS preflight ke cache 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 menetapkan Access-Control-Allow-Origin ke origin 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 menetapkan Access-Control-Allow-Origin.
Contoh:
--cors_preset=cors_with_regex
--cors_allow_origin_regex=^https?://.+\.example\.com$

Ekspresi reguler dalam contoh sebelumnya memungkinkan origin dengan http atau https dan subdomain example.com apa pun.

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

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

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

Setelah menetapkan --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 dengan 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 yang dapat ditampilkan sebagai bagian dari respons sebagai string dengan setiap header 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, masing-masing dengan nilai pecahan opsional dan akhiran satuan, seperti "300 m", "1,5 jam", atau "2j45m". Satuan waktu yang valid adalah "m" untuk menit, "h" untuk jam. Nilai defaultnya adalah "480 jam" jika tidak disetel.
Contoh:
--cors_preset=basic
--cors_max_age=24h

Dukungan TLS

Gunakan tanda ini untuk mengonfigurasi ESPv2 agar menggunakan koneksi TLS.

Tanda Deskripsi
--ssl_server_cert_path Jalur sertifikat server proxy. Jika dikonfigurasi, ESPv2 hanya menerima koneksi aman HTTP/1.x dan HTTP/2 pada pemroses_port. Memerlukan file sertifikat dan kunci "server.crt" dan "server.key" dalam jalur ini.
--ssl_server_cipher_suites Suite cipher yang akan digunakan untuk koneksi downstream, ditetapkan 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 root certificate yang digunakan ESPv2 untuk memverifikasi sertifikat server backend. Jika tidak ditentukan, ESPv2 akan menggunakan "/etc/ssl/certs/ca-certificates.crt" secara default.
--ssl_backend_client_cipher_suites Paket cipher yang akan digunakan untuk backend HTTPS, ditetapkan sebagai daftar yang dipisahkan koma. Lihat Konfigurasi cipher suite.
--ssl_minimum_protocol Versi protokol TLS minimum untuk koneksi sisi klien. Lihat ini
--ssl_maximum_protocol Versi protokol TLS maksimum untuk koneksi sisi klien. Lihat 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 di awal, lalu simpan di "/tmp/ssl/endpoints/server.crt" dan "/tmp/ssl/endpoints/server.key". Hal ini berguna jika hanya sertifikat penandatanganan mandiri acak yang diperlukan untuk menayangkan permintaan HTTPS. Sertifikat yang dibuat akan memiliki Nama Umum "localhost" dan berlaku selama 10 tahun.

Waktu Tunggu dan Percobaan Ulang

Gunakan tanda ini untuk mengonfigurasi waktu tunggu panggilan HTTP jarak jauh dan mencoba lagi untuk ESPv2.

Tanda Deskripsi
--http_request_timeout_s

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

--service_control_network_fail_open

Jika terjadi kegagalan jaringan saat terhubung ke kontrol layanan Google, permintaan akan diizinkan jika tanda ini aktif. Setelan defaultnya adalah on.

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

Kondisi saat ESPv2 melakukan percobaan ulang pada 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 flag ini ke kosong.

Buka link berikut untuk mengetahui kondisi yang diterima:

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

Transcoding gRPC

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

Tanda Deskripsi
--transcoding_always_print_primitive_fields

Menentukan apakah akan mencetak kolom primitif untuk transcoding grpc-json atau tidak. Secara default, kolom primitif dengan nilai default akan dihilangkan dalam output JSON. Misalnya, kolom int32 yang ditetapkan ke 0 akan dihilangkan. Menyetel tanda ini ke true akan mengganti perilaku default dan mencetak kolom primitif cetak, apa pun nilainya. Nilai defaultnya adalah false.

--transcoding_always_print_enums_as_ints

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

--transcoding_stream_newline_delimited

Jika true (benar), gunakan pemisah baris baru untuk memisahkan pesan streaming respons. Jika salah, semua pesan streaming respons akan di-transcoding menjadi array JSON.

--transcoding_case_insensitive_enum_parsing

Biasanya, nilai enum proto harus ditulis dalam huruf besar saat digunakan di JSON. Tetapkan tanda ini ke benar (true) jika permintaan JSON Anda menggunakan nilai enum bukan huruf besar.

--transcoding_preserve_proto_field_names

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

--transcoding_ignore_query_parameters

Daftar parameter kueri yang dipisahkan koma yang akan diabaikan untuk pemetaan metode transcoding dalam transcoding grpc-json. Secara default, filter transcodingr tidak akan melakukan transcoding 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 metode ini jika Anda tidak dapat mengontrol parameter kueri dan tidak mengenalnya 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 ke dalam ruang " " dalam transcoding grpc-json. Ini untuk mendukung HTML 2.0. Jika tidak diinginkan, setel tanda ini ke benar (true) untuk menonaktifkan fitur ini.

Perubahan Permintaan dan Respons

Gunakan tanda ini untuk mengonfigurasi ESPv2 agar dapat mengubah sebagian permintaan dan respons.

Tanda Deskripsi
--add_request_header

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

Kode ini mendukung variabel kustom Envoy.

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

--append_request_header

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

Kode ini mendukung variabel kustom Envoy.

Argumen ini dapat diulang beberapa kali untuk menentukan beberapa header. Contoh:
--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 akan diganti dengan yang baru.

Kode ini mendukung variabel kustom Envoy.

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

--append_response_header

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

Kode ini mendukung variabel kustom Envoy.

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

Opsi Keamanan

Gunakan tanda ini untuk lebih mempersempit permintaan yang diizinkan ESPv2.

Tanda Deskripsi
--underscores_in_headers

Izinkan 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 dapat dipertukarkan.

--envoy_connection_buffer_limit_bytes

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

--disable_normalize_path

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

Tabel berikut menyediakan 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 dipengaruhi oleh perilaku tersebut.

Catatan: Setelah RFC 3986, opsi ini tidak membatalkan escape karakter garis miring yang dienkode persen. Lihat flag --disallow_escaped_slashes_in_path untuk mengaktifkan perilaku yang tidak mematuhi kebijakan ini.

Catatan: Normalisasi kasus dari RFC 3986 tidak didukung, meskipun opsi ini diaktifkan.

Untuk detail selengkapnya, lihat Memahami Template Jalur.

--disable_merge_slashes_in_path

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

Tabel berikut menyediakan 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 dipengaruhi oleh perilaku tersebut.

Untuk detail selengkapnya, lihat Memahami Template Jalur.

--disallow_escaped_slashes_in_path

Melarang permintaan dengan karakter garis miring berenkode persen yang di-escape:

  • %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 berenkode persen yang di-escape akan otomatis dibatalkan konversinya melalui pengalihan.
  • Untuk backend gRPC, jalur permintaan dengan garis miring berenkode persen yang di-escape akan ditolak (gRPC tidak mendukung pengalihan).

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

Untuk detail selengkapnya, lihat Memahami Template Jalur.

Autentikasi JWT

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

Tanda Deskripsi
--jwks_fetch_num_retries

Tentukan jumlah percobaan ulang dalam kebijakan percobaan ulang pengambilan JWKS jarak jauh. Defaultnya adalah 0, bukan mencoba ulang.

--jwks_fetch_retry_back_off_base_interval_ms

Tentukan JWKS mengambil percobaan ulang back-off interval dasar eksponensial, dalam milidetik. Defaultnya adalah 200 md, jika tidak disetel.

--jwks_fetch_retry_back_off_max_interval_ms

Tentukan JWKS mengambil percobaan ulang back-off eksponensial dalam interval maksimum, dalam milidetik. Defaultnya adalah 32 dtk, jika tidak disetel.

--jwks_cache_duration_in_s

Tentukan durasi cache kunci publik JWT dalam detik. Setelan default-nya adalah 5 menit, jika tidak disetel.

--jwks_async_fetch_fast_listener

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

--jwt_cache_size

Menentukan 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 cache yang digunakan kurang lebih (ukuran token + 64 byte) per token. Jika tidak ditentukan, jumlah defaultnya adalah 100000.

--disable_jwt_audience_service_name_check

Biasanya, kolom aud JWT dibandingkan dengan audiens yang ditentukan dalam 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 digunakan untuk memeriksa kolom JWT aud. Jika tanda ini digunakan, kolom aud JWT tidak akan dicentang.

Langkah selanjutnya

Pelajari: