Memulai API Gateway dan Cloud Run untuk gRPC

Halaman ini menunjukkan cara menyiapkan API Gateway untuk mengelola dan mengamankan layanan backend Cloud Run dengan gRPC.

Daftar Tugas

Gunakan daftar tugas berikut saat Anda mengerjakan tutorial ini. Semua tugas diperlukan untuk men-deploy gateway API untuk layanan backend Cloud Run Anda dengan gRPC.

1. Membuat atau memilih project Google Cloud.
2. Jika Anda belum men-deploy Cloud Run sendiri, deploy contoh layanan gRPC backend. Lihat langkah 7 di Sebelum memulai.
3. Aktifkan layanan API Gateway yang diperlukan.
4. Buat dokumen konfigurasi gRPC API yang menjelaskan API Anda, dan konfigurasikan rute ke Cloud Run Anda. Lihat Mengonfigurasi konfigurasi API dengan gRPC.
5. Deploy API gateway menggunakan konfigurasi API Anda. Lihat Men-deploy API gateway.
6. Uji deployment API Anda dengan mengirim permintaan. Lihat Mengirim permintaan ke API.
7. Melacak aktivitas ke layanan Anda. Lihat Melacak aktivitas API.
8. Hindari tagihan pada akun Google Cloud Anda. Lihat Pembersihan.

Sebelum memulai

1. Di konsol Google Cloud, buka halaman Dasbor, lalu pilih atau buat project Google Cloud.

   Buka Dasbor

   Catatan: Jika Anda tidak berencana untuk menyimpan resource yang dibuat dalam tutorial ini, buat project baru, bukan memilih project yang ada. Setelah menyelesaikan langkah-langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

2. Pastikan penagihan diaktifkan untuk project Anda.

   Mengaktifkan penagihan

3. Catat project ID karena diperlukan nanti. Di bagian lain halaman ini, project ID ini disebut sebagai PROJECT_ID.

4. Catat nomor project karena diperlukan nanti. Di bagian lain halaman ini, nomor project ini disebut sebagai PROJECT_NUMBER.

5. Download dan instal Google Cloud CLI.

   Mendownload gcloud CLI

6. Ikuti langkah-langkah di panduan memulai gRPC Python untuk menginstal gRPC dan alat gRPC.

7. Deploy contoh layanan backend gRPC Cloud Run python-grpc-bookstore-server untuk digunakan dengan tutorial ini. Layanan gRPC menggunakan image container berikut:

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

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

   Catat URL layanan, serta region dan project ID tempat layanan Anda di-deploy.

Mengaktifkan layanan yang diperlukan

API Gateway mengharuskan Anda mengaktifkan layanan Google berikut:

Nama	Judul
apigateway.googleapis.com	API Gateway API
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	Service Control API

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 apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

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

Membuat konfigurasi API dengan gRPC

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

1. Buat file deskripsi 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 Toko Buku.
   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 yang berbeda untuk file input .proto, ubah --proto_path sehingga compiler menelusuri direktori tempat Anda menyimpan bookstore.proto.

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

   # 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: "*.apigateway.PROJECT_ID.cloud.goog"
   title: API Gateway + 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://python-grpc-bookstore-server-HASH-uc.a.run.app

   Indentasi penting untuk format yaml. Misalnya, kolom name harus berada di tingkat yang sama dengan type.
3. Di kolom name, layanan bernama *.apigateway.PROJECT_ID.cloud.goog dengan PROJECT_ID adalah nama project ID Google Cloud Anda.

4. Di kolom address di bagian backend.rules, ganti grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app dengan URL sebenarnya dari layanan Cloud Run gRPC backend python-grpc-bookstore-server, dengan HASH adalah kode hash unik yang dihasilkan saat Anda membuat layanan.

   Catatan: Untuk menggunakan gRPC dengan TLS di Cloud Run, kolom address harus memiliki skema grpcs://, bukan https://.

   Contoh ini mengasumsikan bahwa Anda menggunakan layanan backend Bookstore gRPC yang dibuat di Sebelum memulai. Jika perlu, ganti nilai ini dengan URL layanan Cloud Run Anda.

5. Simpan dokumen konfigurasi gRPC API Anda.
6. Buat konfigurasi API:

   gcloud api-gateway api-configs create CONFIG_ID \
   --api=API_ID --project=PROJECT_ID \
   --grpc-files=api_descriptor.pb,api_config.yaml

   dengan:
   • CONFIG_ID menentukan nama konfigurasi API Anda.
   • API_ID menentukan nama API Anda.
   • PROJECT_ID menentukan nama project Google Cloud Anda.
   Misalnya:

   gcloud api-gateway api-configs create grpc-config \
   --api=grpc-test --project=my-test-project \
   --grpc-files=api_descriptor.pb,api_config.yaml

Men-deploy gateway API

Untuk men-deploy konfigurasi gRPC API ke gateway, jalankan perintah berikut:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

dengan:

• GATEWAY_ID menentukan nama gateway.
• API_ID menentukan nama API Gateway API yang terkait dengan gateway ini.
• CONFIG_ID menentukan nama konfigurasi API yang di-deploy ke gateway.

• GCP_REGION adalah region Google Cloud untuk gateway yang di-deploy.

  Catatan: Nilai yang diizinkan adalah:

  • asia-northeast1
  • australia-southeast1
  • europe-west1
  • europe-west2
  • us-east1
  • us-east4
  • us-central1
  • us-west2
  • us-west3
  • us-west4

• PROJECT_ID menentukan nama project Google Cloud Anda.

Contoh:

gcloud api-gateway gateways create bookstore-grpc \
  --api=grpc-test --api-config=grpc-config \
  --location=us-central1 --project=my-project

Setelah berhasil diselesaikan, Anda dapat menggunakan perintah berikut untuk melihat detail tentang gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Perhatikan nilai properti defaultHostname dalam output perintah ini. Ini adalah bagian nama host dari URL gateway yang Anda gunakan untuk menguji deployment di langkah berikutnya.

Contoh:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Mengirim permintaan ke API

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

1. Clone repositori git tempat kode klien gRPC dihosting:

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

2. Ubah direktori kerja Anda:

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

3. Instal dependensi:

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

4. Kirim permintaan ke API contoh:

   python3 bookstore_client.py --host=DEFAULT_HOSTNAME --port 443 --use_tls true

   Tentukan properti defaultHostname gateway Anda di DEFAULT_HOSTNAME, tanpa ID protokol. Contoh:

   python3 bookstore_client.py --host=my-gateway-a12bcd345e67f89g0h.uc.gateway.dev --port 443 --use_tls true

Melacak aktivitas API

1. Lihat grafik aktivitas untuk API Anda di halaman API Gateway di konsol Google Cloud. Klik API Anda untuk melihat grafik aktivitasnya di halaman Ringkasan. Mungkin perlu waktu beberapa saat hingga permintaan ditampilkan dalam grafik.

2. Lihat log permintaan untuk API Anda di halaman Logs Explorer. Link ke halaman Logs Explorer dapat ditemukan di halaman API Gateway di konsol Google Cloud.

   Buka API Gateway

   Setelah berada di halaman API Gateway:

   1. Pilih API yang akan dilihat.
   2. Klik tab Detail.
   3. Klik link di bagian Logs.

Anda baru saja men-deploy dan menguji API di API Gateway dengan gRPC.

Pembersihan

Agar tidak menimbulkan tagihan pada akun Google Cloud Anda untuk resource yang digunakan dalam panduan memulai ini, Anda dapat:

• Menghapus gateway
• Menghapus API Anda

Atau, Anda juga dapat menghapus project Google Cloud yang digunakan untuk tutorial ini.