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 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 file app.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 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 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 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 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 adalah ESPv2_ARGS. Lihat Opsi startup Extensible Service Proxy V2 untuk mengetahui informasi selengkapnya tentang setelan ESPv2_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

Catatan: * Jika Anda menentukan lokasi JWT kustom, Endpoint akan mengabaikan semua lokasi default. * Fitur lokasi JWT kustom hanya didukung oleh ESPv2.

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": "[e-mail]",
  "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": "[e-mail]",
  "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": "[e-mail]",
  "audiences": [
    "xyz1.example.com"
    "xyz2.example.com"
  ],
  "claims": {
    "iss": "https://accounts.google.com",
    "email": "[e-mail]",
    "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:

• Opsi startup Extensible Service Proxy V2
• Ekstensi OpenAPI
• Repo ESPv2 di GitHub