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 menyebabkan error yang dijelaskan di bawah.

Kasus penggunaan ESPv2 yang tidak didukung

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 di lingkungan fleksibel App Engine. Deployment ini berfungsi dengan cara yang sama seperti ESPv2 yang digunakan untuk mendukung lingkungan standar App Engine.
Konfigurasi NGINX Kustom tidak didukung

ESPv2 adalah proxy berbasis Envoy. Layanan ini tidak dapat mendukung konfigurasi proxy NGINX kustom. Jika konfigurasi ESP Anda menggunakan flag -n atau --nginx_config, penerapan Anda mungkin bergantung pada konfigurasi NGINX kustom yang tidak dapat dengan mudah dimigrasikan ke ESPv2.

Perubahan yang dapat menyebabkan gangguan

Format data header X-Endpoint-API-UserInfo diubah. Jika aplikasi Anda menggunakan header ini, aplikasi harus diubah untuk menggunakan format baru. Lihat Menangani JWT di layanan backend untuk mengetahui 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 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 menghasilkan 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 tidak digunakan lagi 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-tanpa server: GKE, Compute Engine, Kubernetes

ESPv2 adalah pengganti drop-in untuk ESP. Untuk sebagian besar konfigurasi, Anda hanya perlu mengupdate ke 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 tidak digunakan lagi atau diganti. Lihat Perubahan tanda pengaktifan 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 penampung docker menggunakan perintah docker run. Untuk memigrasikan Endpoints untuk Compute Engine ke ESPv2, perbarui tag image docker dari :1 menjadi :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 Functions, atau App Engine. Untuk memigrasikan Endpoints ke ESPv2, Anda harus mem-build 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 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. Image ini 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 menetapkan ESPv2_ARGS dan flag startup yang tersedia.

Perubahan tanda pengaktifan antara ESP dan ESPv2

Seperti halnya 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 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.

Flag yang Diganti

Flag baru	Flag yang diganti	Deskripsi
`--listener_port`	`--http_port`, `--http2_port`, `--ssl_port`	Satu port pemroses 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 minimum dan maksimum.
`--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. Tindakan ini mencegah ESP memanggil Server Metadata Instance.	Di ESPv2, perilaku implisit ini dibagi menjadi flag lain. Anda mungkin perlu menambahkan `--non_gcp` saat melakukan migrasi. Jika tidak, ESPv2 akan gagal dimulai di platform selain GCP.

Flag 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 Laporan Kontrol Layanan Google.
`--service_control_quota_timeout_ms`	Menetapkan waktu tunggu untuk panggilan Kuota Google Service Control.
`--service_control_check_retries`	Menentukan nomor percobaan ulang untuk panggilan Pemeriksaan Kontrol Layanan Google.
`--service_control_report_retries`	Menentukan nomor percobaan ulang untuk panggilan Laporan Kontrol Layanan Google.
`--service_control_quota_retries`	Menentukan jumlah percobaan ulang untuk panggilan Kuota Google Service Control.
`--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 menetapkan ID project yang memiliki data rekaman aktivitas.
`--tracing_incoming_context`	digunakan untuk menentukan konteks rekaman aktivitas yang 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. 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 dalam bahasa Inggris, angka, tanda hubung, dan mungkin garis bawah. Di ESPv2, flag `--underscores_in_headers` menentukan apakah tanda 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 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 flag 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 Anda (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 diubah di platform serverless.

Header X-Endpoint-API-UserInfo berisi objek JSON Base64Url encoded. 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 tertentu yang ditambahkan oleh ESP. ESP menambahkan kolom id, issuer, email, dan audiences ke objek JSON. Tindakan 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 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 selanjutnya

Pelajari: