Menyiapkan Cloud Endpoints gRPC untuk Cloud Run dengan ESPv2

OpenAPI | gRPC

Halaman ini menunjukkan cara menyiapkan Cloud Endpoints untuk Cloud Run dengan backend gRPC. Endpoint menggunakan Extensible Service Proxy V2 (ESPv2) sebagai gateway API. Guna menyediakan pengelolaan API untuk Cloud Run, Anda men-deploy container ESPv2 yang telah dibangun sebelumnya ke Cloud Run. Selanjutnya, Anda dapat membantu mengamankan layanan dengan menggunakan Cloud Run IAM sehingga ESPv2 dapat memanggilnya.

Dengan penyiapan ini, ESPv2 akan mencegat semua permintaan ke layanan Anda dan melakukan pemeriksaan yang diperlukan (seperti autentikasi) sebelum memanggil layanan. Saat layanan merespons, ESPv2 akan mengumpulkan dan melaporkan telemetri, seperti yang ditunjukkan pada gambar di bawah. Anda dapat melihat metrik untuk layanan Anda di halaman Endpoint > Layanan di Konsol Google Cloud.

Arsitektur endpoint

Untuk ringkasan Cloud Endpoints, lihat Tentang Endpoint dan Arsitektur endpoint.

Bermigrasi ke ESPv2

Rilis Cloud Endpoints sebelumnya tidak mendukung gRPC di Cloud Run dengan ESP. Untuk menggunakan fitur ini, migrasikan ke Extensible Service Proxy V2.

{i>Task List <i}(Daftar Tugas)

Gunakan daftar tugas berikut saat Anda mengerjakan tutorial. Semua tugas diperlukan untuk menyelesaikan tutorial ini.

Buat project Google Cloud, dan jika Anda belum men-deploy Cloud Run sendiri, deploy contoh layanan gRPC backend. Lihat Sebelum memulai.
Cadangkan nama host Cloud Run untuk layanan ESPv2. Lihat Mereservasi nama host Cloud Run.
Buat dokumen konfigurasi gRPC API yang mendeskripsikan API Anda, dan konfigurasikan rute ke Cloud Run Anda. Lihat Mengonfigurasi Endpoint.
Deploy dokumen konfigurasi gRPC API untuk membuat layanan terkelola. Lihat Men-deploy konfigurasi Endpoint.
Build image Docker ESPv2 baru dengan konfigurasi layanan Endpoint Anda. Lihat Membuat image ESPv2 baru.
Men-deploy container ESPv2 ke Cloud Run. Kemudian, beri ESPv2 izin Identity and Access Management (IAM) untuk memanggil layanan Anda. Lihat Men-deploy container ESPv2.
Panggil layanan. Lihat Mengirim permintaan ke API.
Lacak aktivitas ke layanan Anda. Lihat Aktivitas Tracking API.
Hindari menimbulkan tagihan ke akun Google Cloud Anda. Lihat Pembersihan.

Biaya

Dalam dokumen ini, Anda menggunakan komponen Google Cloud yang dapat ditagih berikut:

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga. Pengguna baru Google Cloud mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Setelah menyelesaikan tugas yang dijelaskan dalam dokumen ini, Anda dapat menghindari penagihan berkelanjutan dengan menghapus resource yang Anda buat. Untuk mengetahui informasi selengkapnya, lihat Pembersihan.

Sebelum memulai

Untuk melakukan penyiapan:

Di konsol Google Cloud, buka halaman Manage resources dan buat project.
Buka halaman Kelola resource
Pastikan penagihan diaktifkan untuk project Anda.
Pelajari cara mengaktifkan penagihan
Catat ID project karena akan diperlukan nanti. Di bagian selanjutnya dari halaman ini, project ID ini disebut sebagai ESP_PROJECT_ID.
Catat nomor project karena akan diperlukan nanti. Di bagian selanjutnya halaman ini, nomor project ini disebut sebagai ESP_PROJECT_NUMBER.
Mendownload dan menginstal Google Cloud CLI.
Mendownload gcloud CLI
Ikuti langkah-langkah dalam panduan memulai Python gRPC untuk menginstal alat gRPC dan gRPC.
Deploy layanan backend contoh python-grpc-bookstore-server gRPC Cloud Run untuk digunakan dengan tutorial ini. Layanan gRPC menggunakan image container berikut:

gcr.io/endpointsv2/python-grpc-bookstore-server:2

Ikuti langkah-langkah di bagian Panduan Memulai: Men-deploy Container Contoh Bawaan untuk men-deploy layanan. Pastikan untuk mengganti image container yang ditentukan dalam panduan memulai tersebut dengan gcr.io/endpointsv2/python-grpc-bookstore-server:2

Catat region dan project ID tempat layanan Anda di-deploy. Di bagian lain halaman ini, project ID ini disebut sebagai BACKEND_PROJECT_ID. Nama layanan Cloud Run yang di-deploy disebut sebagai BACKEND_SERVICE_NAME. Nama host Cloud Run-nya disebut sebagai BACKEND_HOST_NAME.

Mencadangkan nama host Cloud Run

Anda harus mencadangkan nama host Cloud Run untuk layanan ESPv2 agar dapat configure dokumen OpenAPI atau konfigurasi layanan gRPC. Untuk mencadangkan nama host, Anda akan men-deploy container contoh ke Cloud Run. Kemudian, Anda akan deploy container ESPv2 ke layanan Cloud Run yang sama.

Pastikan gcloud CLI diberi otorisasi untuk mengakses data dan layanan Anda.
1. Log in.
```
gcloud auth login
```
2. Pada tab browser baru yang terbuka, pilih akun yang memiliki peran Editor atau Owner di project Google Cloud yang Anda buat untuk men-deploy ESPv2 ke Cloud Run.

Tetapkan wilayah.

gcloud config set run/region us-central1

Deploy image contoh gcr.io/cloudrun/hello ke Cloud Run. Ganti CLOUD_RUN_SERVICE_NAME dengan nama yang ingin Anda gunakan untuk layanan.

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/cloudrun/hello" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESP_PROJECT_ID

Setelah berhasil, perintah akan menampilkan pesan yang mirip dengan berikut ini:

Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

Misalnya, jika Anda menetapkan CLOUD_RUN_SERVICE_NAME ke gateway:

Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

Dalam contoh ini, https://gateway-12345-uc.a.run.app adalah CLOUD_RUN_SERVICE_URL dan gateway-12345-uc.a.run.app adalah CLOUD_RUN_HOSTNAME.

Catat CLOUD_RUN_SERVICE_NAME dan CLOUD_RUN_HOSTNAME. Kemudian, Anda men-deploy ESPv2 ke layanan Cloud Run CLOUD_RUN_SERVICE_NAME. Anda menentukan CLOUD_RUN_HOSTNAME di kolom host pada dokumen OpenAPI.

Mengonfigurasi Endpoint

Contoh bookstore-grpc berisi file yang perlu Anda salin secara lokal dan konfigurasi.

Buat file deskriptor protobuf mandiri dari file .proto layanan Anda:
1. Simpan salinan bookstore.proto dari repositori contoh ke direktori kerja Anda saat ini. File ini menentukan API layanan Bookstore.
2. Buat direktori berikut di direktori kerja Anda: mkdir generated_pb2
3. Buat file deskripsi, api_descriptor.pb, menggunakan compiler buffering protokol protoc. Jalankan perintah berikut di direktori tempat Anda menyimpan bookstore.proto:
```
python3 -m grpc_tools.protoc \
    --include_imports \
    --include_source_info \
    --proto_path=. \
    --descriptor_set_out=api_descriptor.pb \
    --python_out=generated_pb2 \
    --grpc_python_out=generated_pb2 \
    bookstore.proto
```
  Dalam perintah sebelumnya, --proto_path ditetapkan ke direktori kerja saat ini. Di lingkungan build gRPC, jika Anda menggunakan direktori berbeda untuk file input .proto, ubah --proto_path agar compiler menelusuri direktori tempat Anda menyimpan bookstore.proto.

Buat file teks bernama api_config.yaml di direktori kerja Anda saat ini (direktori yang sama yang berisi bookstore.proto). Untuk memudahkan, halaman ini merujuk ke dokumen konfigurasi gRPC API dengan nama file tersebut, tetapi Anda dapat menamainya dengan nama lain jika ingin. Tambahkan konten berikut ke file tersebut:

# The configuration schema is defined by the service.proto file.
# https://github.com/googleapis/googleapis/blob/master/google/api/service.proto

type: google.api.Service
config_version: 3
name: CLOUD_RUN_HOSTNAME
title: Cloud Endpoints + Cloud Run gRPC
apis:
  - name: endpoints.examples.bookstore.Bookstore
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true
backend:
  rules:
    - selector: "*"
      address: grpcs://BACKEND_HOST_NAME

Indentasi penting untuk format yaml. Misalnya, kolom name harus berada pada level yang sama dengan type.

Di kolom name, tentukan CLOUD_RUN_HOSTNAME, bagian nama host URL yang dicadangkan di atas di bagian Pemesanan nama host Cloud Run. Jangan sertakan ID protokol, seperti https:// atau grpcs://.
Di kolom address pada bagian backend.rules, ganti BACKEND_HOST_NAME dengan layanan Cloud Run gRPC Bookstore aktual yang dibuat di Sebelum Anda memulai.

Catatan: Untuk menggunakan gRPC dengan TLS di Cloud Run, kolom address harus memiliki skema grpcs://, bukan https://.
Perhatikan nilai properti title dalam file api_config.yaml:
```
title: Cloud Endpoints + Cloud Run gRPC
```
Nilai properti title akan menjadi nama layanan Endpoint setelah Anda men-deploy konfigurasi.
Simpan dokumen konfigurasi gRPC API Anda.

Lihat Mengonfigurasi Endpoint untuk informasi selengkapnya.

Men-deploy konfigurasi Endpoint

Untuk men-deploy konfigurasi Endpoint, gunakan perintah gcloud endpoints services deploy. Perintah ini menggunakan Pengelolaan Layanan untuk membuat layanan terkelola.

Pastikan Anda berada di direktori tempat file api_descriptor.pb dan api_config.yaml berada.
Pastikan project default yang digunakan alat command line gcloud saat ini adalah project Google Cloud tempat Anda ingin men-deploy konfigurasi Endpoint. Validasi project ID yang ditampilkan dari perintah berikut untuk memastikan bahwa layanan tidak dibuat dalam project yang salah.
```
gcloud config list project
```
Jika Anda perlu mengubah project default, jalankan perintah berikut:
```
gcloud config set project YOUR_PROJECT_ID
```
Deploy file proto descriptor dan file konfigurasi menggunakan Google Cloud CLI:
```
gcloud endpoints services deploy api_descriptor.pb api_config.yaml
```
Saat membuat dan mengonfigurasi layanan, Pengelolaan Layanan menghasilkan informasi ke terminal. Setelah deployment selesai, pesan yang mirip dengan yang berikut ini akan ditampilkan:
```
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
CONFIG_ID adalah ID konfigurasi layanan Endpoint unik yang dibuat oleh deployment. Contoh:
```
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
Pada contoh sebelumnya, 2017-02-13r0 adalah ID konfigurasi layanan dan bookstore.endpoints.example-project.cloud.goog adalah nama layanan. ID konfigurasi layanan terdiri dari stempel tanggal yang diikuti dengan nomor revisi. Jika Anda men-deploy konfigurasi Endpoint lagi pada hari yang sama, nomor revisinya akan bertambah di ID konfigurasi layanan.

Memeriksa layanan yang diperlukan

Setidaknya, Endpoint dan ESP mengharuskan layanan Google berikut diaktifkan:

Nama	Judul
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API
`endpoints.googleapis.com`	Google Cloud Endpoints

Dalam sebagian besar kasus, perintah gcloud endpoints services deploy akan mengaktifkan layanan wajib ini. Namun, perintah gcloud berhasil diselesaikan tetapi tidak mengaktifkan layanan yang diperlukan dalam situasi berikut:

Jika Anda menggunakan aplikasi pihak ketiga seperti Terraform, dan Anda tidak menyertakan layanan ini.
Anda telah men-deploy konfigurasi Endpoint ke project Google Cloud yang ada, yang menonaktifkan layanan ini secara eksplisit.

Gunakan perintah berikut untuk mengonfirmasi bahwa layanan yang diperlukan telah diaktifkan:

gcloud services list

Jika Anda tidak melihat layanan yang diperlukan tercantum, aktifkan layanan tersebut:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

Aktifkan juga layanan Endpoint Anda:

gcloud services enable ENDPOINTS_SERVICE_NAME

Untuk menentukan ENDPOINTS_SERVICE_NAME, Anda dapat:

Setelah men-deploy konfigurasi Endpoint, buka halaman Endpoint di Cloud Console. Daftar kemungkinan ENDPOINTS_SERVICE_NAME ditampilkan di bawah kolom Service name.
Untuk OpenAPI, ENDPOINTS_SERVICE_NAME adalah yang Anda tentukan dalam kolom host pada spesifikasi OpenAPI. Untuk gRPC, ENDPOINTS_SERVICE_NAME adalah yang Anda tentukan di kolom name pada konfigurasi Endpoint gRPC Anda.

Untuk mengetahui informasi selengkapnya tentang perintah gcloud, lihat layanan gcloud.

Jika Anda mendapatkan pesan error, lihat Memecahkan masalah deployment konfigurasi Endpoint.

Lihat Men-deploy konfigurasi Endpoint untuk mengetahui informasi tambahan.

Membuat gambar ESPv2 baru

Build konfigurasi layanan Endpoint ke image Docker ESPv2 baru. Anda nanti akan men-deploy image ini ke layanan Cloud Run yang dicadangkan.

Catatan:

Langkah ini wajib dilakukan.

Konfigurasi layanan harus di-build ke dalam image docker baru karena Cloud Run adalah layanan scale-to-zero. Artinya, jika tidak ada traffic, semua instance akan dihapus. Saat traffic meningkat, instance baru akan dibuat sesuai permintaan. Jenis pembuatan instance layanan ini juga disebut cold start. Lihat dokumentasi Konkurensi Cloud Run untuk informasi selengkapnya.

Jika image docker tidak memiliki konfigurasi layanan bawaan, Cloud Run harus melakukan dua panggilan API ke Google ServiceManagement saat cold start. Panggilan ini mengurangi kuota Google ServiceManagement API Anda.

Dengan mem-build konfigurasi layanan ke image docker ESPv2, Anda menghapus dua panggilan API dan agar tidak memengaruhi jumlah kuota untuk layanan Google ServiceManagement. Langkah ini juga akan mempercepat pembuatan instance layanan baru dan mengurangi latensi untuk permintaan yang menunggu instance baru.

Anda harus menjalankan ulang seluruh langkah ini dan men-deploy ulang container baru:

Setiap kali Anda mengubah dan men-deploy ulang konfigurasi layanan Endpoint. Jika tidak, perubahan pada konfigurasi layanan tidak akan diterapkan ke ESPv2.
Saat ESPv2 versi baru dirilis. Jika tidak, versi lama ESPv2 akan tetap di-deploy.

Untuk mem-build konfigurasi layanan ke dalam image docker ESPv2 baru:

Download skrip ini ke mesin lokal tempat gcloud CLI diinstal.

Catatan:
Skrip ini membutuhkan bash. Jika tidak menggunakan macOS/Linux, Anda dapat menjalankannya di Cloud Shell, Compute Engine, atau Windows Subsystem for Linux.

Jalankan skrip dengan perintah berikut:

chmod +x gcloud_build_image

./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESP_PROJECT_ID

Untuk CLOUD_RUN_HOSTNAME, tentukan nama host URL yang Anda cadangkan di atas di Pemesanan nama host Cloud Run. Jangan sertakan ID protokol, https://.

Contoh:

chmod +x gcloud_build_image

./gcloud_build_image -s gateway-12345-uc.a.run.app \
    -c 2019-02-01r0 -p your-project-id

Skrip ini menggunakan perintah gcloud untuk mendownload konfigurasi layanan, mem-build konfigurasi layanan ke image ESPv2 yang baru, dan mengupload image baru ke container registry project Anda. Skrip secara otomatis menggunakan rilis terbaru ESPv2, yang dilambangkan dengan ESP_VERSION dalam nama image output. Gambar output diupload ke:
```
gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID
```
Contoh:
```
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
```
Catatan:
Teruskan flag -z ke skrip untuk menghasilkan image di lokasi registry yang berbeda.

Misalnya, untuk mengirim image ESPv2 yang dihasilkan ke pusat data Euopean Union, teruskan -z eu ke skrip.

Men-deploy container ESPv2

Deploy layanan ESPv2 Cloud Run dengan image baru yang Anda build di atas. Ganti CLOUD_RUN_SERVICE_NAME dengan nama layanan Cloud Run yang sama seperti yang Anda gunakan saat pertama kali mencadangkan nama host di atas di bagian Memesan nama host Cloud Run:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESP_PROJECT_ID
```
Catatan:
Jika layanan gRPC Anda menggunakan protokol streaming, tambahkan flag --use-http2 ke perintah gcloud run deploy. Saat ini, flag ini hanya didukung di gcloud beta run. Tambahkan tanda ini saat men-deploy layanan Cloud Run backend ESPv2 dan gRPC.
Jika Anda ingin mengonfigurasi Endpoint untuk menggunakan opsi startup ESPv2 tambahan, seperti mengaktifkan CORS, Anda dapat meneruskan argumen dalam variabel lingkungan ESPv2_ARGS:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --allow-unauthenticated \
  --platform managed \
  --project ESP_PROJECT_ID
```
Untuk mengetahui informasi dan contoh selengkapnya tentang cara menetapkan variabel lingkungan ESPv2_ARGS, termasuk daftar opsi yang tersedia dan informasi tentang cara menentukan beberapa opsi, lihat tanda Extensible Service Proxy V2.
Beri ESPv2 izin untuk memanggil layanan Cloud Run Anda. Jalankan perintah berikut untuk setiap layanan. Dalam perintah berikut:
Catatan:
Langkah ini tidak diperlukan jika layanan ESPv2 Cloud Run di-deploy tanpa menggunakan flag --service-account dan layanan backend BACKEND_SERVICE_NAME di-deploy di project ESP_PROJECT_NUMBER.
- Ganti BACKEND_SERVICE_NAME dengan nama layanan Cloud Run yang dipanggil. Jika Anda menggunakan layanan yang dibuat dengan men-deploy `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, maka gunakan python-grpc-bookstore-server sebagai nilai ini.
- Ganti ESP_PROJECT_NUMBER dengan nomor project yang Anda buat untuk ESPv2. Salah satu cara untuk menemukannya adalah dengan membuka halaman IAM di Konsol Google Cloud dan menemukan Akun layanan komputasi default, yang merupakan akun layanan yang digunakan di flag `member`.
```
gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
  --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role "roles/run.invoker" \
  --platform managed \
  --project BACKEND_PROJECT_ID
```

Untuk mengetahui informasi selengkapnya, baca bagian Mengelola akses menggunakan IAM.

Mengirim permintaan ke API

Untuk mengirim permintaan ke API contoh, Anda dapat menggunakan klien gRPC contoh yang ditulis dalam Python.

Clone repo git tempat kode klien gRPC dihosting:

git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

Ubah direktori kerja Anda:

cd python-docs-samples/endpoints/bookstore-grpc/

Instal dependensi:

pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt

Kirim permintaan ke API contoh:
```
python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true
```
Tentukan nama host layanan ESPv2 Cloud Run Anda di CLOUD_RUN_HOSTNAME, tanpa ID protokol. Contoh:
```
python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true
```
- Lihat grafik aktivitas untuk API Anda di halaman Endpoint > Layanan.
  
  Buka halaman Layanan Endpoint
  
  Mungkin perlu waktu beberapa saat agar permintaan terlihat dalam grafik.
- Lihat log permintaan untuk API Anda di halaman Logs Explorer.
  
  Buka halaman Logs Explorer

Jika tidak mendapatkan respons yang berhasil, lihat Memecahkan masalah error respons.

Anda baru saja men-deploy dan menguji API di Endpoint.

Melacak aktivitas API

Lihat grafik aktivitas untuk API Anda di halaman Endpoint > Layanan di Google Cloud Console.

Melihat grafik aktivitas Endpoint

Mungkin perlu waktu beberapa saat agar permintaan terlihat dalam grafik.
Lihat log permintaan untuk API Anda di halaman Logs Explorer.

Melihat log permintaan Endpoint

Membuat portal developer untuk API

Anda dapat menggunakan Portal Cloud Endpoints untuk membuat portal developer, yaitu situs yang dapat digunakan untuk berinteraksi dengan contoh API. Untuk mempelajari lebih lanjut, lihat Ringkasan Portal Cloud Endpoints.

Pembersihan

Agar akun Google Cloud Anda tidak dikenakan biaya untuk resource yang digunakan pada halaman ini, ikuti langkah-langkah berikut.

Lihat Menghapus instance API dan API untuk mengetahui informasi tentang cara menghentikan layanan yang digunakan oleh tutorial ini.