Halaman ini diterjemahkan oleh Cloud Translation API.

Bermigrasi ke Extensible Service Proxy V2

OpenAPI | gRPC

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 perubahan API yang merusak yang dijelaskan di bawah.

Kasus penggunaan yang tidak didukung ESPv2

Lingkungan fleksibel App Engine tidak didukung

Lingkungan fleksibel App Engine memiliki dukungan Endpoints bawaan yang diaktifkan dengan menetapkan endpoints_api_service dalam file app.yaml aplikasi. Implementasi Endpoints bawaan ini hanya mendukung ESP; tidak dapat dimigrasikan ke ESPv2.

Jika Anda ingin menggunakan ESPv2 dengan lingkungan fleksibel App Engine, nonaktifkan endpoints_api_service di app.yaml. Anda dapat men-deploy ESPv2 sebagai layanan Cloud Run terpisah yang digunakan untuk mengelola aplikasi Anda di lingkungan fleksibel App Engine. Deployment berfungsi dengan cara yang sama seperti ESPv2 digunakan untuk mendukung lingkungan standar App Engine.
Konfigurasi NGINX Kustom tidak didukung

ESPv2 adalah proxy berbasis Envoy. Tidak dapat mendukung konfigurasi proxy NGINX kustom. Jika konfigurasi ESP Anda menggunakan flag -n atau --nginx_config, penerapan Anda mungkin mengandalkan 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 tersebut harus diubah untuk menggunakan format baru. Lihat Menangani JWT di layanan backend untuk mengetahui detail selengkapnya.
Jika kunci API diperlukan untuk permintaan, ESP akan mengirim header X-Endpoint-API-Project-ID dengan project ID konsumen ke aplikasi backend. ESPv2 menggunakan dua header yang berbeda,X-Endpoint-API-Consumer-Type dan X-Endpoint-API-Consumer-Number, untuk mengirim detail yang diperlukan. Lihat dokumentasi referensi Infrastruktur Layanan untuk mengetahui detail selengkapnya tentang Consumer-Type dan Consumer-Number yang dikirim dengan header ini.
Format isi respons error HTTP diubah. Saat menolak permintaan HTTP, ESPv2 akan membuat isi respons error dalam format baru. Jika penerapan Anda menggunakan kode klien untuk memproses isi respons JSON error HTTP, kode klien harus diperbarui. Lihat Isi respons JSON Error HTTP untuk mengetahui detail selengkapnya.
Flag startup baru tersedia dan beberapa flag ESP telah dihentikan atau diganti di ESPv2. Lihat Perubahan flag startup antara ESP dan ESPv2.

Memigrasikan Endpoints API untuk menggunakan ESPv2

Langkah-langkah migrasi yang diperlukan untuk menggunakan ESPv2 dengan platform serverless (Cloud Run, fungsi Cloud Run, 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 memperbarui tag image Docker.

Namun, Anda mungkin perlu menyesuaikan flag startup jika mengonfigurasi ESP dengan:

Lebih dari satu port melalui flag --http_port, http2_port, dan/atau --ssl_port.
SSL, DNS, Client IP, atau flag lain yang jarang digunakan.

Flag startup baru tersedia untuk ESPv2 dan beberapa flag ESP telah dihentikan atau diganti. Lihat Perubahan flag startup antara ESP dan ESPv2 untuk mengetahui detail selengkapnya.

GKE dan Kubernetes

Untuk memigrasikan konfigurasi Endpoints untuk GKE dan Kubernetes, ubah tag image ESP dari :1 menjadi :2 dalam 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. Untuk memigrasikan Endpoints for Compute Engine ke ESPv2, perbarui tag image Docker dari :1 ke :2 dalam 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 serverless, ESPv2 di-deploy sebagai layanan Cloud Run untuk mengelola aplikasi Anda yang berjalan di Cloud Run, Cloud Function, atau App Engine. Untuk memigrasikan Endpoints ke ESPv2, Anda harus membuat konfigurasi layanan Endpoints yang ada ke dalam image Docker ESPv2 baru, lalu men-deploy image ke layanan Cloud Run ESPv2.

Langkah-langkah deployment untuk ESP dan ESPv2 identik, 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. Menggunakan gcr.io/endpoints-release/endpoints-runtime-serverless:2 sebagai image dasar.
Variabel lingkungan digunakan untuk menentukan flag startup. Nama variabel untuk ESP adalah ESP_ARGS. Nama untuk ESPv2 adalah ESPv2_ARGS. Lihat Opsi startup Extensible Service Proxy V2 untuk mengetahui informasi selengkapnya tentang cara menyetel ESPv2_ARGS dan flag startup yang tersedia.

Perubahan flag 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 telah dihentikan 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 tanda baru.
Tabel 3 menjelaskan tanda yang tidak digunakan lagi.

Flag yang Diganti

Flag baru	Flag yang diganti	Deskripsi
`--listener_port`	`--http_port`, `--http2_port`, `--ssl_port`	Satu port listener Envoy mendukung http, http2, dan ssl di ESPv2. Anda tidak perlu menentukan port terpisah.
`--ssl_server_cert_path`	`--ssl_port`	Saat `--ssl_server_cert_path` digunakan, ESPv2 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 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. Flag 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. Di ESPv2, Anda dapat menentukan protokol min dan maks.
`--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`	Flag penggantian memiliki perilaku yang sama, tetapi nilai default yang berbeda. ESP menggunakan 8.8.8.8 sebagai resolver DNS. ESPv2 menggunakan resolver DNS yang dikonfigurasi di `/etc/resolv.conf`.
`--service_account_key`	`--non_gcp`, `--service_account_key`	Di ESP, tanda `--service_account_key` secara implisit mengizinkan deployment ke platform selain GCP. Opsi 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 tidak akan dapat dimulai di platform selain GCP.

Bendera Baru

Flag 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 hitungan detik.
`--service_control_check_timeout_ms`	Menetapkan waktu tunggu untuk panggilan Pemeriksaan Kontrol Layanan Google, 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 Kuota Kontrol Layanan Google.
`--service_control_check_retries`	Menentukan jumlah percobaan ulang untuk panggilan Google Service Control Check.
`--service_control_report_retries`	Menentukan jumlah percobaan ulang untuk panggilan Google Service Control Report.
`--service_control_quota_retries`	Menentukan jumlah percobaan ulang untuk panggilan Google Service Control Quota.
`--backend_dns_lookup_family`	Konfigurasi khusus Envoy yang digunakan untuk menentukan keluarga pencarian DNS untuk semua backend.
`--disable_tracing`	Flag keseluruhan yang digunakan untuk menonaktifkan semua rekaman aktivitas.
`--tracing_project_id`	Digunakan untuk menyetel ID project yang memiliki data rekaman aktivitas.
`--tracing_incoming_context`	digunakan untuk menentukan konteks rekaman aktivitas masuk.
`--tracing_outgoing_context`	Digunakan untuk menentukan konteks outgoingtrace.

Flag yang Tidak Digunakan Lagi

Flag 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. Berikut 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 kemungkinan garis bawah. Di ESPv2, tanda `--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. Perutean backend diaktifkan secara otomatis untuk platform serverless.
`--rollout_fetch_throttle_window_in_s`	Tidak diperlukan.
`--nginx_config`	Tidak didukung.

Lihat Opsi startup Extensible Service Proxy V2 untuk mengetahui detail selengkapnya tentang tanda startup ESPv2. Contoh generik tambahan dan teks bantuan untuk tanda dapat ditemukan di repositori GitHub.

Lokasi JWT default

Secara default, JWT diteruskan di header Authorization (dengan awalan "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 Anda ingin terus meneruskan JWT menggunakan header Authorization (tanpa awalan) setelah bermigrasi ke ESPv2, Anda dapat:

Tetapkan x-google-jwt-locations dalam file openAPI Anda (untuk pengguna backend HTTP):

x-google-jwt-locations:
- header: "Authorization"

Tetapkan Authentication.providers.jwt_locations dalam 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 mengirimkan hasil autentikasi di header X-Endpoint-API-UserInfo ke backend API. Sebaiknya gunakan header ini, bukan header Authorization asli, karena header Authorization asli dapat diubah di platform serverless.

Header X-Endpoint-API-UserInfo berisi objek JSON berenkode Base64Url. Namun, formatnya telah diubah dari ESP menjadi ESPv2.

Untuk ESPv2, header X-Endpoint-API-UserInfo berisi payload JWT asli, tanpa modifikasi apa pun.

Di 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. Selain itu, kolom claims juga ditambahkan 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 mengilustrasikan perbedaannya, semuanya telah didekode base64url.

# This is an example of the original JWT payload:
{
  &quotiss&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotsub&quot: &quot1234567890123456789&quot,
  &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
  &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
  &quotbar&quot: &quotbar.bar.bar.bar&quot,
  &quotazp&quot: &quot98765432109876543210&quot,
  &quotexp&quot: &quot1642809446&quot,
  &quotiat&quot: &quot1642805846&quot
}

# This is an example of the `X-Endpoint-API-UserInfo` header from ESPv2
# extracted from above JWT payload.
{
  &quotiss&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotsub&quot: &quot1234567890123456789&quot,
  &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
  &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
  &quotbar&quot: &quotbar.bar.bar.bar&quot,
  &quotazp&quot: &quot98765432109876543210&quot,
  &quotexp&quot: &quot1642809446&quot,
  &quotiat&quot: &quot1642805846&quot
}

# This is an example of the `X-Endpoint-API-UserInfo` header from ESP
# extracted from above JWT payload.
{
  &quotid&quot:&quot1234567890123456789&quot,
  &quotissuer&quot: &quothttps://accounts.google.com&quot,
  &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
  &quotaudiences&quot: [
    &quotxyz1.example.com&quot
    &quotxyz2.example.com&quot
  ],
  &quotclaims&quot: {
    &quotiss&quot: &quothttps://accounts.google.com&quot,
    &quotemail&quot: &quotabcdefg123456@gmail.com&quot,
    &quotsub&quot: &quot1234567890123456789&quot,
    &quotaud&quot: &quotxyz1.example.com,xyz2.example.com&quot,
    &quotfoo&quot: &quotfoo.foo.foo.foo&quot,
    &quotbar&quot: &quotbar.bar.bar.bar&quot,
    &quotazp&quot: &quot98765432109876543210&quot,
    &quotexp&quot: &quot1642809446&quot,
    &quotiat&quot: &quot1642805846&quot
  }
}

Lihat Menggunakan metode kustom untuk mengautentikasi pengguna dan Autentikasi antar-layanan untuk mengetahui informasi selengkapnya tentang penggunaan JWT dengan autentikasi.

Format isi respons JSON error

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

Pelajari: