Menyiapkan Cloud Endpoints OpenAPI untuk penayangan Knative dengan ESPv2
Halaman ini menunjukkan cara menyiapkan Cloud Endpoints untuk penayangan Knative. Endpoint menggunakan Extensible Service Proxy V2 (ESPv2) sebagai API gateway. Untuk menyediakan pengelolaan API untuk penayangan Knative, Anda men-deploy penampung ESPv2 bawaan ke penayangan Knative yang berjalan di cluster GKE.
Dengan penyiapan ini, ESPv2 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.
Untuk ringkasan Endpoint, lihat Tentang Endpoint dan Arsitektur endpoint.
Daftar Tugas
Gunakan daftar tugas berikut saat Anda mengerjakan tutorial ini. Semua tugas diperlukan untuk menyelesaikan tutorial ini.
Buat project Google Cloud, dan jika Anda belum men-deploy layanan Knative sendiri, deploy layanan contoh. Lihat Sebelum memulai.
Buat cluster GKE dengan penayangan Knative diaktifkan.
Deploy contoh layanan penayangan Knative.
Buat dokumen OpenAPI yang menjelaskan Endpoints API Anda, dan konfigurasikan rute ke layanan penayangan Knative Anda. Lihat Mengonfigurasi Endpoint.
Deploy dokumen OpenAPI untuk membuat layanan terkelola. Lihat Men-deploy konfigurasi Endpoint.
Build image Docker ESPv2 baru dengan konfigurasi layanan Endpoints Anda. Lihat Mem-build image ESPv2 baru.
Deploy image penayangan Knative ESPv2 baru. Lihat Men-deploy image Cloud Run ESPv2.
Buat pemetaan domain ke layanan penayangan Knative ESPv2.
Uji konfigurasi Anda dengan Mengirim permintaan ke API.
Melacak aktivitas ke layanan Anda. Lihat Melacak aktivitas API.
Biaya
Dalam dokumen ini, Anda akan menggunakan komponen Google Cloud yang dapat ditagih berikut:
Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda,
gunakan kalkulator harga.
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
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- Catat project ID karena diperlukan nanti. Di bagian lain halaman ini, project ID ini disebut sebagai ESP_PROJECT_ID.
- Download dan instal Google Cloud SDK.
- Instal cURL jika Anda ingin mengirim permintaan ke layanan contoh yang di-deploy.
Menyiapkan command line gcloud
Untuk menyiapkan gcloud CLI untuk penayangan Knative untuk Anthos:
Pastikan Google Cloud SDK diberi otorisasi untuk mengakses data dan layanan Anda.
Log in.
gcloud auth login
Di tab browser baru yang terbuka, pilih akun yang memiliki peran Editor atau Pemilik di project Google Cloud yang Anda buat untuk men-deploy ESPv2 ke layanan Knative.
Mengupdate komponen
gcloud
yang diinstal:gcloud components update
Tetapkan platform ke
gke
dan tetapkan setelan project default untukgcloud
ke project yang baru saja Anda buat:gcloud config set run/platform gke
gcloud config set project ESP_PROJECT_ID
Ganti ESP_PROJECT_ID dengan project ID project yang Anda buat.
Tetapkan zona yang diinginkan untuk cluster baru. Anda dapat menggunakan zona mana pun yang mendukung GKE, misalnya:
gcloud config set compute/zone ZONE
Ganti ZONE dengan zona Anda. Misalnya, gunakan
us-central1-a
. Anda dapat menggunakan zona apa pun yang didukung oleh GKE.Aktifkan API berikut untuk project, yang diperlukan untuk membuat cluster, mem-build, dan memublikasikan penampung ke Artifact Registry:
gcloud services enable container.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com
Membuat cluster GKE dengan penayangan Knative diaktifkan
Untuk membuat cluster dan mengaktifkannya untuk penayangan Knative di Google Cloud:
Buat cluster baru menggunakan perintah:
gcloud container clusters create CLUSTER_NAME \ --addons=HttpLoadBalancing,CloudRun \ --machine-type=n1-standard-4 \ --num-nodes=3 \ --enable-stackdriver-kubernetes
Ganti CLUSTER_NAME dengan nama yang Anda inginkan untuk cluster Anda.
Meskipun petunjuk ini tidak mengaktifkan penskalaan otomatis cluster untuk mengubah ukuran cluster sesuai permintaan, penayangan Knative di Google Cloud akan otomatis menskalakan instance dalam cluster.
Tunggu hingga pembuatan cluster selesai. Selama proses pembuatan, Anda akan melihat pesan yang mirip dengan berikut ini:
Creating cluster CLUSTER_NAME...done. Created [https://container.googleapis.com/v1/projects/ESP_PROJECT_ID/zones/ZONE/clusters/CLUSTER_NAME].
Output juga menampilkan versi cluster di kolom
NODE_VERSION
output. Misalnya1.15.11-gke.1
atau1.14.10-gke.27
. Catat versi cluster untuk digunakan nanti dalam dokumen ini.Tetapkan default
gcloud
untuk menggunakan cluster dan lokasi cluster baru, agar Anda tidak perlu menentukannya saat menggunakan gcloud CLI:gcloud config set run/cluster CLUSTER_NAME
gcloud config set run/cluster_location ZONE
Gunakan perintah berikut untuk melihat detail tentang cluster baru:
gcloud container clusters describe CLUSTER_NAME
Gunakan perintah berikut untuk mengambil kredensial cluster Anda:
gcloud container clusters get-credentials CLUSTER_NAME
Men-deploy contoh penayangan container Knative
Untuk men-deploy contoh penayangan Knative "hello" ke cluster yang baru saja Anda buat:
Klik Create service.
Pilih Penayangan Knative sebagai platform pengembangan Anda.
Di menu dropdown cluster yang tersedia, pilih cluster yang baru saja Anda buat.
Gunakan nama hello sebagai Nama layanan. Anda dapat menggunakan beberapa nama lain, tetapi jika melakukannya, pastikan Anda menggunakan nama tersebut nanti. Petunjuk ini mengasumsikan bahwa Anda menggunakan hello.
Pilih Internal di bagian Konektivitas sehingga layanan tidak dapat diakses secara eksternal.
Klik Berikutnya untuk melanjutkan ke halaman kedua formulir pembuatan layanan.
Tentukan
gcr.io/cloudrun/hello
sebagai Container image URL.Klik Create untuk men-deploy image ke layanan Knative dan tunggu hingga deployment selesai.
Setelah selesai, layar Revisi akan muncul. Perhatikan bahwa URL layanan yang di-deploy adalah:
http://hello.default.svc.cluster.local
Saat Anda membuat layanan Internal, GKE akan membuat nama DNS yang hanya dapat di-resolve untuk permintaan yang berasal dari dalam cluster itu sendiri, bukan untuk permintaan eksternal. Anda tidak dapat mengakses link ini secara eksternal dari cluster. Lihat layanan Cloud Run untuk mengetahui informasi selengkapnya.
Untuk memverifikasi bahwa layanan Anda berfungsi dengan benar menggunakan cURL, siapkan tunnel dari desktop ke cluster. Untuk melihat petunjuk ini, klik ikon di sebelah kanan URL pada layar Revisi:
Panel akan terbuka dan menampilkan dua perintah yang Anda gunakan untuk mengakses layanan internal. Anda harus menjalankan perintah ini di dua jendela terminal terpisah karena perintah pertama menyiapkan penerusan port yang digunakan oleh perintah kedua.
Saat menjalankan perintah cURL, Anda akan melihat output dari layanan dalam bentuk:
<!doctype html> <html lang=en> <head> <meta charset=utf-8> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Congratulations | Cloud Run</title> ...
Mengonfigurasi Endpoint
Anda harus memiliki dokumen OpenAPI berdasarkan Spesifikasi OpenAPI v2.0 yang menjelaskan platform layanan backend Anda dan persyaratan autentikasi apa pun. Anda juga perlu menambahkan kolom khusus Google yang berisi URL untuk setiap layanan sehingga ESPv2 memiliki informasi yang diperlukan untuk memanggil layanan. Jika Anda baru menggunakan OpenAPI, lihat Ringkasan OpenAPI untuk mengetahui informasi selengkapnya.
Tentang menetapkan kolom host spesifikasi OpenAPI
Di kolom host
spesifikasi OpenAPI, Anda menentukan nama layanan Endpoint yang digunakan untuk mengakses layanan penayangan Knative. Nama layanan Endpoint berupa nama domain:
API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
Karena nama layanan Endpoints sesuai dengan nama domain, nama tersebut harus mengikuti aturan berikut:
- Hanya boleh berisi huruf kecil, angka, titik, atau tanda pisah.
- Tidak boleh diawali dengan tanda hubung.
- Tidak boleh berisi garis bawah.
Contoh:
hello-api.endpoints.ESP_PROJECT_ID.cloud.goog
Membuat spesifikasi OpenAPI
Buat file teks bernama
openapi-run-anthos.yaml
.Layanan backend penayangan Knative Anda ditentukan di bagian atas file
openapi-run-anthos.yaml
, dalam definisix-google-backend
. Contoh:swagger: '2.0' info: title: Cloud Endpoints + Cloud Run description: Sample API on Cloud Endpoints with a Cloud Run backend version: 1.0.0 host: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog x-google-endpoints: - name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog target: "INGRESS-IP" schemes: - https produces: - application/json x-google-backend: address: http://hello.default.svc.cluster.local disable_auth: true paths: /hello: get: summary: Greet a user operationId: hello responses: '200': description: A successful response schema: type: string
Indentasi penting untuk format YAML. Misalnya, kolom
host
harus berada di tingkat yang sama denganinfo
.Di kolom
host
, tentukan nama domain Endpoints API yang digunakan untuk mengakses layanan penayangan Knative Anda, dalam bentuk:API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
Contoh:
hello-api.endpoints.ESP_PROJECT_ID.cloud.goog
Ekstensi
x-google-endpoints
mendaftarkan entri DNS untuk layanan Endpoints Anda di domaincloud.goog
, dalam bentuk:x-google-endpoints: - name: "API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog" target: "IP_ADDRESS"
IP_ADDRESS adalah IP layanan
istio-ingress
untuk cluster Anda. Untuk menentukan alamat IP ini:Buka halaman Google Kubernetes Engine di Konsol Google Cloud:
Klik Services & Ingress di panel navigasi kiri untuk menampilkan daftar layanan.
Jika versi cluster Anda adalah
1.15.3-gke.19
atau yang lebih baru,1.14.3-gke.12
atau yang lebih baru, atau1.13.10-gke.8
atau yang lebih baru, scroll ke bawah ke layananistio-ingress
. Untuk semua versi cluster lainnya, scroll ke bawah ke layananistio-ingressgateway
.Salin alamat IP eksternal yang ditampilkan di samping Load Balancer, tanpa setelan port, jika ada. Misalnya, jika IP-nya adalah
XX.XXX.XX.XXX:15020
, hapus:15020
. Abaikan alamat IP lain yang tercantum.
Di kolom
address
di bagianx-google-backend
, tentukan nama DNS internal layanan "hello" yang ditayangkan Knative backend, dan nonaktifkan autentikasi ke layanan ini. Hal ini diperlukan karena panggilan dari ESPv2 ke layanan penayangan Knative dilakukan sebagai panggilan internal dari dalam cluster sehingga autentikasi tidak diperlukan.Perhatikan nilai properti
title
dalam fileopenapi-run-anthos.yaml
:title: Cloud Endpoints + Cloud Run
Nilai properti
title
menjadi nama layanan Endpoints setelah Anda men-deploy konfigurasi.Simpan dokumen OpenAPI Anda.
Untuk mengetahui informasi tentang kolom dalam dokumen OpenAPI yang diperlukan Endpoints, lihat Mengonfigurasi Endpoints.
Men-deploy konfigurasi Endpoint
Untuk men-deploy konfigurasi Endpoints, Anda menggunakan perintah gcloud endpoints services deploy. Perintah ini menggunakan Pengelolaan Layanan untuk membuat layanan terkelola.
Untuk men-deploy konfigurasi Endpoint:
Pastikan Anda berada di direktori yang berisi dokumen OpenAPI.
Upload konfigurasi dan buat layanan terkelola.
gcloud endpoints services deploy openapi-run-anthos.yaml \ --project ESP_PROJECT_ID
Tindakan ini akan membuat layanan Endpoints baru dengan nama yang Anda tentukan di kolom
host
fileopenapi-run-anthos.yaml
. Layanan Endpoints dikonfigurasi sesuai dengan dokumen OpenAPI Anda.Saat membuat dan mengonfigurasi layanan Endpoints, Pengelolaan Layanan akan menampilkan informasi ke terminal. Setelah deployment selesai, pesan seperti berikut akan ditampilkan:
Service Configuration [CONFIG_ID] uploaded for service [API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog]
CONFIG_ID adalah ID konfigurasi layanan Endpoints unik yang dibuat oleh deployment. Contoh:
Service Configuration [2019-02-01r0] uploaded for service [hello-api.endpoints.ESP_PROJECT_ID.cloud.goog]
ID konfigurasi layanan terdiri dari stempel tanggal yang diikuti dengan nomor revisi. Jika Anda men-deploy
openapi-run-anthos.yaml
lagi pada hari yang sama, nomor revisi akan bertambah di ID konfigurasi layanan. Anda dapat melihat konfigurasi layanan dan histori deployment di halaman Endpoints > Services di Konsol Google Cloud.Jika Anda menerima pesan error, lihat Memecahkan masalah deployment konfigurasi Endpoints.
Memeriksa layanan yang diperlukan
Setidaknya, Endpoint dan ESP mewajibkan layanan Google berikut diaktifkan:Nama | Judul |
---|---|
servicemanagement.googleapis.com |
Service Management API |
servicecontrol.googleapis.com |
Service Control API |
Dalam sebagian besar kasus, perintah gcloud endpoints services deploy
mengaktifkan
layanan yang diperlukan 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 men-deploy konfigurasi Endpoints ke project Google Cloud yang ada, tempat layanan ini dinonaktifkan 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
Aktifkan juga layanan Endpoints Anda:
gcloud services enable ENDPOINTS_SERVICE_NAME
Untuk menentukan ENDPOINTS_SERVICE_NAME, Anda dapat:
Setelah men-deploy konfigurasi Endpoints, buka halaman Endpoints di Konsol Cloud. Daftar kemungkinan ENDPOINTS_SERVICE_NAME ditampilkan di kolom Nama layanan.
Untuk OpenAPI, ENDPOINTS_SERVICE_NAME adalah yang Anda tentukan di kolom
host
pada spesifikasi OpenAPI. Untuk gRPC, ENDPOINTS_SERVICE_NAME adalah yang Anda tentukan di kolomname
pada konfigurasi Endpoint gRPC.
Untuk informasi selengkapnya tentang perintah gcloud
, lihat
layanan gcloud
.
Mem-build image penayangan Knative ESPv2 baru
Build konfigurasi layanan Endpoints ke dalam image docker ESPv2 baru. Setelah membuat image ini, Anda dapat men-deploy-nya ke cluster.
Untuk mem-build konfigurasi layanan ke dalam image docker ESPv2 baru:
Download skrip ini ke komputer lokal tempat gcloud CLI diinstal, lalu jalankan sebagai:
chmod +x gcloud_build_image
./gcloud_build_image -s API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog \ -c CONFIG_ID -p ESP_PROJECT_ID
Skrip menggunakan perintah
gcloud
untuk mendownload konfigurasi layanan, mem-build konfigurasi layanan menjadi image ESPv2 baru, dan mengupload image baru ke registry container project Anda. Skrip secara otomatis menggunakan rilis ESPv2 terbaru, yang ditunjukkan dengan ESP_VERSION dalam nama image output. Gambar output diupload ke:gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID
Men-deploy image penayangan Knative ESPv2
Deploy image layanan penayangan Knative ESPv2 ke cluster Anda:
Deploy layanan penayangan Knative ESPv2 dengan image baru:
gcloud run deploy ESP_V2_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ --platform gke \ --project=ESP_PROJECT_ID
Untuk ESP_PROJECT_ID, tentukan nama yang ingin Anda gunakan untuk layanan ESPv2. Dalam contoh ini, tetapkan ESP_V2_SERVICE_NAME ke
espv2
.Jika ingin mengonfigurasi Endpoints untuk menggunakan opsi startup ESPv2 tambahan, seperti mengaktifkan CORS, Anda dapat meneruskan argumen dalam variabel lingkungan
ESPv2_ARGS
:gcloud run deploy ESP_V2_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ --platform gke \ --project ESP_PROJECT_ID
Untuk informasi selengkapnya dan contoh tentang cara menetapkan variabel lingkungan ESPv2_ARGS, termasuk daftar opsi yang tersedia dan informasi tentang cara menentukan beberapa opsi, lihat Flag Extensible Service Proxy V2.
Layanan ESPv2 di-deploy sebagai layanan eksternal, yang berarti Anda dapat mengaksesnya menggunakan perintah cURL dalam bentuk:
curl -H "Host: espv2.default.example.com" http://IP_ADDRESS
dengan IP_ADDRESS adalah alamat IP layanan istio-ingress
untuk cluster Anda.
Untuk melihat perintah cURL ini, klik ikon IMAGE di sebelah kanan URL ESPv2 di layar Revisions dari layanan penayangan Knative ESPv2 yang di-deploy.
Sekarang Anda dapat melakukan panggilan API ke layanan Endpoints melalui layanan ESPv2. Misalnya, untuk membuat permintaan ke layanan Endpoints dengan jalur /hello
, Anda dapat membuat permintaan dalam bentuk:
curl -H "Host: espv2.default.example.com" http://IP_ADDRESS/hello
Namun, menentukan header host
pada setiap permintaan ke layanan Endpoints Anda tidak mudah digunakan. Di bagian berikutnya, Anda akan menyiapkan peta domain untuk mempermudah panggilan ke layanan Endpoint melalui ESPv2.
Membuat pemetaan domain ke layanan penayangan Knative ESPv2
Agar dapat menghilangkan header host
saat Anda membuat permintaan, tambahkan pemetaan domain untuk layanan ESPv2:
Pilih Kelola Domain Kustom.
Pilih Tambahkan Pemetaan.
Dari dropdown, pilih Tambahkan pemetaan domain layanan.
Di kolom Pilih layanan yang akan dipetakan pada pop-up Tambahkan pemetaan, pilih layanan ESPv2 Anda.
Di kolom Enter domain name, tentukan nama domain yang ingin digunakan untuk mengakses layanan penayangan Knative melalui Endpoints. Misalnya, tentukan:
API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
Dengan API_NAME adalah nama Endpoints API Anda. Untuk contoh ini, Anda dapat menggunakan "hello-api":
hello-api.endpoints.ESP_PROJECT_ID.cloud.goog
Klik Lanjutkan. Ringkasan pemetaan akan muncul.
Pilih Selesai untuk menyimpan pemetaan.
Mengirim permintaan ke API
Gunakan cURL untuk mengirim permintaan HTTP ke API Anda:
curl -X GET "http://hello-api.endpoints.ESP_PROJECT_ID.cloud.goog/hello"
Jika Anda tidak mendapatkan respons yang berhasil, lihat Memecahkan Masalah Error Respons.
Mengonfigurasi Endpoints API untuk menggunakan HTTPS
Dukungan TLS otomatis dinonaktifkan secara default untuk penayangan Knative di Google Cloud. Oleh karena itu, dalam contoh ini, saat mengakses Endpoints API melalui ESPv2, Anda melakukan panggilan menggunakan HTTP.
Anda dapat mengonfigurasi ESPv2 untuk mendukung permintaan menggunakan HTTPS. Perhatikan bahwa Anda mengonfigurasi dukungan HTTPS di ESPv2, layanan eksternal, bukan di "hello", layanan backend internal.
Untuk mendukung HTTPS dengan ESPv2, Anda harus:
Memiliki domain. Jika belum memiliki domain, Anda bisa mendapatkannya dari Cloud Domains atau dari vendor domain lain.
Buat pemetaan domain untuk layanan ESPv2 Anda dan perbarui data DNS Anda dengan mengikuti petunjuk di halaman pemetaan domain.
Jika Anda mendapatkan domain dari Cloud Domains, gunakan Cloud DNS, atau server DNS pilihan Anda. Menggunakan domain dari Cloud Domains adalah opsi termudah.
Dalam spesifikasi OpenAPI Endpoints:
Tetapkan kolom
host
untuk merujuk ke domain Anda, bukan ke*.cloud.goog
.Hapus tag
x-google-endpoints
dan dua properti turunannya.
Untuk petunjuk dan tutorial lengkap, lihat Mengaktifkan HTTPS dan sertifikat TLS otomatis.
Melacak aktivitas API
Lihat grafik aktivitas untuk API Anda di halaman Endpoints > Service di Konsol Google Cloud.
Melihat grafik aktivitas Endpoint
Mungkin perlu waktu beberapa saat agar permintaan ditampilkan dalam grafik.
Lihat log permintaan untuk API Anda di halaman Logs Explorer. Melihat log permintaan Endpoints
Membuat portal developer untuk API
Anda dapat menggunakan Cloud Endpoints Portal untuk membuat portal developer, situs yang dapat Anda gunakan untuk berinteraksi dengan API contoh. Untuk mempelajari lebih lanjut, lihat Ringkasan Cloud Endpoints Portal.
Pembersihan
Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan pada halaman ini, ikuti langkah-langkah berikut.
Lihat Menghapus API dan instance API untuk mengetahui informasi tentang cara menghentikan layanan yang digunakan oleh tutorial ini.