Extensible Service Proxy V2 (ESPv2) adalah proxy berbasis Envoy yang memungkinkan Cloud Endpoints menyediakan fitur pengelolaan API. ESPv2 menggantikan Extensible Service Proxy (ESP) berbasis NGINX.
Dokumen ini menjelaskan cara memigrasikan deployment Endpoints API yang ada dari ESP ke ESPv2.
Sebelum memulai
Sebelum memulai migrasi, pertimbangkan kasus penggunaan yang tidak didukung dan memengaruhi perubahan API yang dijelaskan di bawah.
Kasus penggunaan yang tidak didukung ESPv2
Lingkungan fleksibel App Engine tidak didukung
Lingkungan fleksibel App Engine memiliki dukungan Endpoint bawaan yang diaktifkan dengan menetapkan
endpoints_api_service
dalam fileapp.yaml
aplikasi. Implementasi Endpoint bawaan ini hanya mendukung ESP; tidak dapat dimigrasikan ke ESPv2.Jika Anda ingin menggunakan ESPv2 dengan lingkungan fleksibel App Engine, nonaktifkan
endpoints_api_service
diapp.yaml
. Anda dapat men-deploy ESPv2 sebagai layanan Cloud Run terpisah yang digunakan untuk mengelola aplikasi di lingkungan fleksibel App Engine. Deployment ini berfungsi dengan cara yang sama seperti saat digunakan ESPv2 untuk mendukung lingkungan standar App Engine.Konfigurasi NGINX Kustom tidak didukung
ESPv2 adalah proxy berbasis Envoy. URL ini tidak dapat mendukung konfigurasi proxy NGINX kustom. Jika konfigurasi ESP menggunakan tanda
-n
atau--nginx_config
, implementasi Anda dapat bergantung pada konfigurasi NGINX kustom yang tidak dapat dimigrasikan dengan mudah ke ESPv2.
Perubahan yang dapat menyebabkan gangguan
- Format data header
X-Endpoint-API-UserInfo
diubah. Jika aplikasi Anda menggunakan header ini, header harus diubah untuk menggunakan format baru. Lihat Menangani JWT di layanan backend untuk detail selengkapnya. Jika kunci API diperlukan untuk permintaan, ESP akan mengirimkan header
X-Endpoint-API-Project-ID
dengan project ID konsumen ke aplikasi backend. ESPv2 menggunakan dua header yang berbeda,X-Endpoint-API-Consumer-Type
danX-Endpoint-API-Consumer-Number
, untuk mengirim detail yang diperlukan. Lihat dokumentasi referensi Infrastruktur Layanan untuk mengetahui detail selengkapnya tentangConsumer-Type
danConsumer-Number
yang dikirim dengan header ini.Format isi respons error HTTP diubah. Saat ESPv2 menolak permintaan HTTP, isi respons error akan dibuat dalam format baru. Jika implementasi Anda menggunakan kode klien untuk memproses isi respons JSON error HTTP, kode klien harus diperbarui. Lihat isi respons JSON HTTP Error untuk mengetahui detail selengkapnya.
Tanda startup baru tersedia dan beberapa tanda ESP sudah tidak digunakan lagi atau diganti di ESPv2. Lihat Perubahan tanda Startup antara ESP dan ESPv2.
Memigrasikan Endpoints API untuk menggunakan ESPv2
Langkah-langkah migrasi yang diperlukan untuk menggunakan ESPv2 dengan platform serverless (Cloud Run, Cloud Functions, App Engine) berbeda dengan langkah-langkah yang diperlukan untuk platform non-serverless (Google Kubernetes Engine, Compute Engine, dan Kubernetes).
Langkah-langkah migrasi yang diperlukan untuk setiap jenis platform dijelaskan di bawah:
Platform non-serverless: GKE, Compute Engine, Kubernetes
ESPv2 adalah pengganti langsung untuk ESP. Untuk sebagian besar konfigurasi, Anda hanya perlu mengupdate ke tag image docker.
Namun, Anda mungkin perlu menyesuaikan tanda startup jika mengonfigurasi ESP dengan:
- Lebih dari satu port melalui tanda
--http_port
,http2_port
, dan/atau--ssl_port
. SSL
,DNS
,Client IP
, atau flag lain yang jarang digunakan.
Tanda startup baru tersedia untuk ESPv2 dan beberapa tanda ESP sudah tidak digunakan lagi atau diganti. Lihat Perubahan tanda Startup antara ESP dan ESPv2 untuk detail selengkapnya.
GKE dan Kubernetes
Guna memigrasikan konfigurasi Endpoint untuk GKE dan Kubernetes, ubah tag image ESP dari :1
menjadi :2
di file yaml
deployment. Contoh:
- name: esp image: gcr.io/endpoints-release/endpoints-runtime:2 args: [ "--http_port=8081", "--backend=127.0.0.1:8080", "--service=SERVICE_NAME", "--rollout_strategy=managed", ]
Compute Engine
ESP dan ESPv2 di-deploy ke container docker menggunakan perintah docker run
. Guna memigrasikan Endpoint untuk Compute Engine keESPv2, perbarui tag image docker dari :1
menjadi :2
di perintah. 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
Platform serverless (Cloud Run, Cloud Functions, App Engine)
Untuk platform tanpa server, ESPv2 di-deploy sebagai layanan Cloud Run untuk mengelola aplikasi Anda yang berjalan di Cloud Run, Cloud Function, atau App Engine. Untuk memigrasikan Endpoint ke ESPv2, Anda harus mem-build konfigurasi layanan Endpoint yang ada ke image docker ESPv2 baru, lalu men-deploy image ke layanan ESPv2 Cloud Run.
Langkah-langkah deployment untuk ESP dan ESPv2 sama, kecuali untuk detail berikut:
Tag image harus diubah dari
:1
menjadi:2
di ESPv2 saat Anda men-deploy ESPv2 ke Cloud Run. Contoh:gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/endpoints-release/endpoints-runtime-serverless:2" \ --allow-unauthenticated \ --platform managed \ --project=ESP_PROJECT_ID
Skrip
gcloud_build_image
didownload dari lokasi yang berbeda.gcr.io/endpoints-release/endpoints-runtime-serverless:2
digunakan sebagai image dasar.Variabel lingkungan digunakan untuk menentukan flag startup. Nama variabel untuk ESP adalah
ESP_ARGS
. Nama untuk ESPv2 adalahESPv2_ARGS
. Lihat Opsi startup Extensible Service Proxy V2 untuk mengetahui informasi selengkapnya tentang setelanESPv2_ARGS
dan tanda startup yang tersedia.
Perubahan tanda startup antara ESP dan ESPv2
Seperti Extensible Service Proxy, Anda dapat menentukan flag konfigurasi saat men-deploy layanan ESPv2. Dengan perubahan dari ESP berbasis NGINX ke ESPv2 berbasis Envoy, beberapa flag sudah tidak digunakan lagi atau diganti dan flag baru telah ditambahkan. Bagian ini menggunakan tiga tabel untuk menjelaskan perubahan:
- Tabel 1 menjelaskan flag baru yang menggantikan flag yang tidak digunakan lagi.
- Tabel 2 menjelaskan flag baru.
- Tabel 3 menjelaskan flag yang tidak digunakan lagi.
Tanda yang Diganti
Tanda baru | Tanda yang diganti | Deskripsi | |
---|---|---|---|
--listener_port
|
--http_port , --http2_port , --ssl_port
|
Sebuah port pendengar Envoy tunggal mendukung http, http2 dan ssl di ESPv2. Tidak perlu menentukan port terpisah. | |
--ssl_server_cert_path
|
--ssl_port
|
Saat --ssl_server_cert_path digunakan, ESPv2 akan menggunakan sertifikat dari file server.key dan
server.crt . Dengan ESPv2, Anda dapat menentukan jalur sertifikat server selain /etc/nginx/ssl . Flag ini menggantikan --ssl_port di ESP, yang menggunakan sertifikat dari jalur file /etc/nginx/ssl/nginx.key dan /etc/nginx/ssl/nginx.crt .
|
|
--ssl_backend_client_cert_path
|
--tls_mutual_auth , --enable_grpc_backend_ssl , --grpc_backend_ssl_private_key_file , --grpc_backend_ssl_cert_chain_file
|
Saat --ssl_backend_client_cert_path digunakan, ESPv2 akan menggunakan sertifikat dari file client.key dan
client.crt . Dengan ESPv2, Anda dapat menentukan jalur sertifikat klien selain /etc/nginx/ssl . Flag ini menggantikan --tls_mutual_auth di ESP, yang menggunakan sertifikat dari jalur file /etc/nginx/ssl/backend.key dan /etc/nginx/ssl/backend.crt .
|
|
--ssl_backend_client_root_certs_file
|
--grpc_backend_ssl_root_certs_file
|
Dengan ESPv2, --ssl_backend_client_root_certs_file berfungsi untuk semua backend. Tanda ini menggantikan --grpc_backend_ssl_root_certs_file di ESP, yang hanya berfungsi untuk backend gRPC.
|
|
--ssl_minimum_protocol ,--ssl_maximum_protocol
|
--ssl_protocols
|
Saat menggunakan --ssl_protocols di ESP, Anda harus mencantumkan semua protokol ssl yang diinginkan. Pada ESPv2, Anda dapat menentukan protokol min dan max.
|
|
--envoy_use_remote_address ,--envoy_xff_num_trusted_hops
|
--xff_trusted_proxy_list ,--client_ip_header ,--client_ip_position
|
Envoy memerlukan use_remote_address dan xff_num_trusted_hops untuk mengonfigurasi ekstraksi IP klien.
|
|
--dns_resolver_addresses
|
--dns
|
Tanda pengganti memiliki perilaku yang sama, tetapi nilai default yang berbeda.
ESP menggunakan 8.8.8.8 sebagai DNS resolver. ESPv2 menggunakan DNS resolver yang dikonfigurasi di /etc/resolv.conf .
|
|
--service_account_key
|
--non_gcp , --service_account_key
|
Pada ESP, flag --service_account_key secara implisit memungkinkan deployment ke platform selain GCP.
Hal ini mencegah ESP memanggil Server Metadata Instance.
|
Di ESPv2, perilaku implisit ini dibagi menjadi tanda lain. Anda mungkin perlu menambahkan --non_gcp saat melakukan migrasi. Jika tidak, ESPv2 akan gagal dimulai di platform selain GCP.
|
Tanda Baru
Tanda baru | Deskripsi |
---|---|
--http_request_timeout_s
|
Menetapkan waktu tunggu untuk semua panggilan jarak jauh http/https, kecuali untuk panggilan backend dan panggilan Kontrol Layanan Google, dalam detik. |
--service_control_check_timeout_ms
|
Menetapkan waktu tunggu untuk panggilan Google Service Control Check, dalam milidetik. |
--service_control_report_timeout_ms
|
Menetapkan waktu tunggu untuk panggilan Google Service Control Report. |
--service_control_quota_timeout_ms
|
Menetapkan waktu tunggu untuk panggilan Google Service Control Quota. |
--service_control_check_retries
|
Menentukan nomor coba lagi untuk panggilan Google Service Control Check. |
--service_control_report_retries
|
Menentukan nomor coba lagi untuk panggilan Laporan Kontrol Layanan Google. |
--service_control_quota_retries
|
Menentukan jumlah coba lagi untuk panggilan Kuota Kontrol Layanan Google. |
--backend_dns_lookup_family
|
Konfigurasi khusus Envoy yang digunakan untuk menentukan kelompok pencarian DNS untuk semua backend. |
--disable_tracing
|
Flag keseluruhan yang digunakan untuk menonaktifkan semua trace. |
--tracing_project_id
|
Digunakan untuk menetapkan ID project yang memiliki data trace. |
--tracing_incoming_context
|
yang digunakan untuk menentukan konteks pelacakan yang masuk. |
--tracing_outgoing_context
|
Digunakan untuk menentukan konteks outgoingtrace. |
Tanda yang Tidak Digunakan Lagi
Tanda yang tidak digunakan lagi | Deskripsi |
---|---|
--enable_websocket
|
Websocket diaktifkan secara default di Envoy. |
--experimental_proxy_backend_host_header
|
Tidak didukung. |
--allow_invalid_headers
|
Tidak didukung. Ini adalah konfigurasi NGINX: ignore_invalid_headers . Jika permintaan HTTP memiliki nama header yang tidak valid, permintaan tersebut akan ditolak oleh ESPv2.
Nama header yang valid terdiri dari huruf, angka, tanda hubung, dan mungkin garis bawah dalam bahasa Inggris. Di ESPv2, flag
--underscores_in_headers menentukan apakah garis bawah diizinkan dalam header.
|
--client_max_body_size
|
Konfigurasi NGINX, tidak didukung. |
--client_body_buffer_size
|
Konfigurasi NGINX, tidak didukung. |
--large_client_header_buffers
|
Konfigurasi NGINX, tidak didukung. |
--keepalive_timeout
|
Konfigurasi NGINX, tidak didukung. |
--client_body_timeout
|
Konfigurasi NGINX, tidak didukung. |
--rewrite
|
Tidak didukung. |
--experimental_enable_multiple_api_configs
|
Tidak didukung. |
--enable_backend_routing
|
Tidak diperlukan. Pemilihan rute backend otomatis diaktifkan untuk platform tanpa server. |
--rollout_fetch_throttle_window_in_s
|
Tidak diperlukan. |
--nginx_config
|
Tidak didukung. |
Lihat Opsi startup Extensible Service Proxy V2 untuk mengetahui detail selengkapnya terkait tanda startup ESPv2. Contoh umum tambahan dan teks bantuan untuk flag dapat ditemukan di repositori GitHub.
Lokasi JWT default
Secara default, JWT diteruskan di header Authorization
(diawali dengan "Bearer "), header X-Goog-Iap-Jwt-Assertion
, atau parameter kueri access_token
. Lokasi ini didukung oleh ESP dan ESPv2. Anda juga dapat meneruskan JWT di header Authorization
(tanpa awalan) saat menggunakan ESP. Namun, lokasi ini tidak didukung di ESPv2.
Jika ingin terus meneruskan JWT menggunakan header Authorization
(tanpa awalan) setelah bermigrasi ke ESPv2, Anda dapat:
- Tetapkan x-google-jwt-locations di file openAPI (untuk pengguna backend HTTP):
x-google-jwt-locations: - header: "Authorization"
- Tetapkan Authentication.providers.jwt_locations di file yaml gRPC Anda (untuk pengguna backend gRPC):
jwt_locations:
- header: Authorization
Menangani JWT di layanan backend
Saat menggunakan JWT untuk melakukan autentikasi, ESPv2 dan ESP
akan mengirimkan hasil autentikasi di header X-Endpoint-API-UserInfo
ke
API backend. Sebaiknya gunakan header ini, bukan header Authorization
asli, karena header Authorization
asli dapat dimodifikasi di platform serverless.
Header X-Endpoint-API-UserInfo
berisi objek JSON yang dienkode Base64Url. Namun, formatnya telah diubah dari ESP menjadi
ESPv2.
Untuk ESPv2, header X-Endpoint-API-UserInfo
berisi payload JWT asli, tanpa modifikasi apa pun.
Pada ESP, header X-Endpoint-API-UserInfo
berisi payload JWT dan beberapa kolom spesifik yang ditambahkan oleh ESP. ESP menambahkan kolom id
, issuer
, email
, dan audiences
ke objek JSON.
Kode ini juga menambahkan kolom claims
untuk menyertakan payload JWT asli.
# ESPv1 X-Endpoint-API-UserInfo header value { "id": "extracted from 'sub' field", "issuer": "extracted from 'iss' field", "email": "extracted from 'email' field", # The following "audiences" is extracted from 'aud' field. # The 'aud' field may have multiple audiences delimited by coma. e.g. "aud: aud1,aud2". # but the following "audiences" is always a JSON array. "audiences": ["aud1", "aud2"], "claims": { Original JWT payload } }
Contoh berikut menggambarkan perbedaannya. Semuanya telah didekode dalam base64url.
# This is an example of the original JWT payload: { "iss": "https://accounts.google.com", "email": "abcdefg123456@gmail.com", "sub": "1234567890123456789", "aud": "xyz1.example.com,xyz2.example.com", "foo": "foo.foo.foo.foo", "bar": "bar.bar.bar.bar", "azp": "98765432109876543210", "exp": "1642809446", "iat": "1642805846" } # This is an example of the `X-Endpoint-API-UserInfo` header from ESPv2 # extracted from above JWT payload. { "iss": "https://accounts.google.com", "email": "abcdefg123456@gmail.com", "sub": "1234567890123456789", "aud": "xyz1.example.com,xyz2.example.com", "foo": "foo.foo.foo.foo", "bar": "bar.bar.bar.bar", "azp": "98765432109876543210", "exp": "1642809446", "iat": "1642805846" } # This is an example of the `X-Endpoint-API-UserInfo` header from ESP # extracted from above JWT payload. { "id":"1234567890123456789", "issuer": "https://accounts.google.com", "email": "abcdefg123456@gmail.com", "audiences": [ "xyz1.example.com" "xyz2.example.com" ], "claims": { "iss": "https://accounts.google.com", "email": "abcdefg123456@gmail.com", "sub": "1234567890123456789", "aud": "xyz1.example.com,xyz2.example.com", "foo": "foo.foo.foo.foo", "bar": "bar.bar.bar.bar", "azp": "98765432109876543210", "exp": "1642809446", "iat": "1642805846" } }
Lihat Menggunakan metode kustom untuk mengautentikasi pengguna dan Autentikasi antarlayanan untuk mengetahui informasi selengkapnya tentang cara menggunakan JWT dengan autentikasi.
Terjadi error pada format isi respons JSON
Jika permintaan HTTP ditolak oleh ESP atau ESPv2, isi respons akan berisi kode status dan pesan error dalam format JSON. Format isi respons telah berubah di ESPv2, seperti yang ditunjukkan pada contoh di bawah:
Isi respons error dari ESP
{ "code": 5, "message": "Method does not exist.", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "stackEntries": [], "detail": "service_control" } ] }
Isi respons error dari ESPv2
{ "code": 400, "message": "Method does not exist.", }
Ada dua perbedaan utama:
- Di ESPv2, kolom
code
berisi kode status http, bukan kode status RPC yang ditemukan di ESP. - Isi respons error di ESPv2 tidak berisi kolom
details
.
Langkah selanjutnya
Pelajari: