Menjalankan Extensible Service Proxy secara lokal atau di platform lain

OpenAPI | gRPC

Halaman ini menjelaskan cara mengonfigurasi dan menjalankan instance Extensible Service Proxy (ESP) di komputer lokal, di penyedia cloud lain, seperti Amazon Web Services (AWS), atau di cluster Kubernetes yang tidak ada di Google Cloud.

Anda dapat menjalankan ESP di komputer Linux atau macOS atau virtual machine (VM). Microsoft Windows tidak didukung. Anda dapat men-deploy aplikasi dan ESP di host yang sama atau di host yang berbeda. Dengan menghosting instance ESP lokal, Anda dapat:

Coba ESP sebelum men-deploy-nya ke platform produksi.
Pastikan setelan keamanan dikonfigurasi dan berfungsi dengan benar, serta metrik dan log muncul di halaman Endpoint > Services seperti yang diharapkan.

Prasyarat

Sebagai titik awal, halaman ini mengasumsikan bahwa:

Anda telah menginstal Docker, jika men-deploy container ESP secara lokal atau ke VM. Baca bagian Menginstal Docker untuk mengetahui informasi selengkapnya.
Anda telah men-deploy API secara lokal atau di host yang dapat dijangkau ke host tempat Anda menjalankan ESP.
Anda telah mengonfigurasi Cloud Endpoints dan men-deploy konfigurasi guna membuat layanan terkelola untuk API Anda.

Jika memerlukan API untuk pengujian dengan ESP, Anda dapat mengonfigurasi dan men-deploy kode contoh di bagian Opsional: Menggunakan API contoh. Jika Anda telah mengonfigurasi dan men-deploy API, lanjutkan ke bagian Membuat akun layanan.

Opsional: Menggunakan API contoh

Bagian ini akan memandu Anda dalam mengonfigurasi dan men-deploy contoh versi Python getting-started untuk Endpoint secara lokal. Lakukan langkah-langkah di bagian ini hanya jika Anda tidak memiliki API untuk pengujian dengan ESP.

Contoh getting-started Cloud Endpoints tersedia dalam bahasa lain. Lihat halaman Samples untuk mengetahui lokasi GitHub contoh getting-started dalam bahasa pilihan Anda. Ikuti petunjuk dalam contoh file README.md untuk berjalan secara lokal, lalu ikuti petunjuk di bagian ini untuk mengonfigurasi Endpoint dan men-deploy konfigurasi Endpoint.

Dapatkan software yang diperlukan

Jika Anda belum menyiapkan lingkungan pengembangan Python, lihat bagian Menyiapkan lingkungan pengembangan Python untuk mendapatkan panduannya. Pastikan Anda telah menginstal aplikasi berikut:

Mendapatkan kode contoh

Clone repositori aplikasi contoh ke komputer lokal Anda:

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

Ubah ke direktori yang berisi kode contoh:

cd python-docs-samples/endpoints/getting-started

Mengonfigurasi Endpoint

Di direktori kode contoh, buka file konfigurasi openapi.yaml.

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

Di kolom host, ganti YOUR-PROJECT-ID dengan project ID Google Cloud Anda sendiri.

Penting: Project ini harus sama dengan project yang Anda pilih di Membuat akun layanan.
Simpan file openapi.yaml.

Men-deploy konfigurasi Endpoint

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

Update gcloud CLI:
```
gcloud components update
```
Pastikan bahwa gcloud CLI (gcloud) diberi otorisasi untuk mengakses data dan layanan Anda di Google Cloud:
```
gcloud auth login
```
Di tab browser baru yang terbuka, pilih akun.
Setel project default ke project ID Anda:
```
gcloud config set project YOUR-PROJECT-ID
```
Ganti YOUR-PROJECT-ID dengan project ID untuk project Google Cloud yang Anda tentukan di file openapi.yaml.

Deploy konfigurasi Anda:

gcloud endpoints services deploy openapi.yaml

Pengelolaan Layanan menggunakan teks yang Anda tentukan dalam kolom host di file openapi.yaml untuk membuat layanan Endpoint baru dengan nama echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog (jika tidak ada), lalu mengonfigurasi layanan sesuai dengan file konfigurasi OpenAPI Anda.

Saat membuat dan mengonfigurasi layanan, Pengelolaan Layanan akan menghasilkan informasi ke terminal. Anda dapat mengabaikan peringatan tentang jalur dalam file openapi.yaml yang tidak memerlukan kunci API dengan aman. Jika berhasil diselesaikan, baris yang mirip dengan berikut ini akan menampilkan ID konfigurasi layanan dan nama layanan dalam tanda kurung siku:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

Pada contoh sebelumnya, 2017-02-13r0 adalah ID konfigurasi layanan, dan echo-api.endpoints.example-project-12345.cloud.goog adalah nama layanan.

Memulai server lokal

Buat virtualenv, aktifkan, lalu instal dependensi aplikasi.

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

Mulai server:
```
python main.py
```

Buka jendela terminal lain dan gunakan curl untuk mengirim permintaan:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8080/echo

API akan menggemakan kembali pesan yang Anda kirimkan, dan merespons dengan hal berikut:

{
"message": "hello world"
}

Membuat akun layanan

Untuk menyediakan pengelolaan bagi API Anda, ESP dan ESPv2 memerlukan layanan di Infrastruktur Layanan. Untuk memanggil layanan ini, ESP dan ESPv2 harus menggunakan token akses. Saat Anda men-deploy ESP atau ESPv2 ke lingkungan Google Cloud, seperti GKE atau Compute Engine, ESP dan ESPv2 akan mendapatkan token akses untuk Anda melalui layanan metadata Google Cloud.

Saat Anda men-deploy ESP atau ESPv2 ke lingkungan non-Google Cloud, seperti desktop lokal, cluster Kubernetes lokal, atau penyedia cloud lainnya, Anda harus menyediakan file JSON akun layanan yang berisi kunci pribadi. ESP dan ESPv2 menggunakan akun layanan untuk membuat token akses guna memanggil layanan yang diperlukan untuk mengelola API Anda.

Anda dapat menggunakan konsol Google Cloud atau Google Cloud CLI untuk membuat akun layanan dan file kunci pribadi:

Konsol

Di konsol Google Cloud, buka halaman Service Accounts .
Buka halaman Service Accounts
Klik Select a project.
Pilih project tempat API Anda dibuat, lalu klik Open.
Klik + Buat Akun Layanan.
Di kolom Nama akun layanan, masukkan nama akun layanan Anda.
Klik Create.
Klik Lanjutkan.
Klik Done.
Klik alamat email akun layanan yang baru dibuat.
Klik Kunci.
Klik Tambahkan kunci, lalu klik Buat kunci baru.
Klik Create. File kunci JSON akan didownload ke komputer Anda.

Pastikan Anda menyimpan file kunci dengan aman karena file tersebut dapat digunakan untuk melakukan autentikasi sebagai akun layanan Anda. Anda dapat memindahkan dan mengganti nama file ini sesuai keinginan Anda.
Klik Close.

`gcloud`

Masukkan informasi berikut guna menampilkan project ID untuk project Google Cloud Anda:
```
gcloud projects list
```
Ganti PROJECT_ID dalam perintah berikut untuk menetapkan project default ke project tempat API Anda berada:
```
gcloud config set project PROJECT_ID
```
Penting: Anda harus membuat akun layanan dalam project yang sama tempat API Anda berada.
Pastikan Google Cloud CLI (gcloud) diberi otorisasi untuk mengakses data dan layanan Anda di Google Cloud:
```
gcloud auth login
```
Jika Anda memiliki lebih dari satu akun, pastikan untuk memilih akun yang ada di project Google Cloud tempat API berada. Jika Anda menjalankan gcloud auth list, akun yang dipilih akan ditampilkan sebagai akun aktif untuk project.
Untuk membuat akun layanan, jalankan perintah berikut dan ganti SERVICE_ACCOUNT_NAME dan My Service Account dengan nama dan nama tampilan yang ingin Anda gunakan:
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
   --display-name "My Service Account"
```
Perintah ini menetapkan alamat email untuk akun layanan dalam format berikut:

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Alamat email ini diperlukan pada perintah berikutnya.

Buat file kunci akun layanan:

gcloud iam service-accounts keys create ~/service-account-creds.json \
   --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Tambahkan peran IAM yang diperlukan:

Bagian ini menjelaskan resource IAM yang digunakan oleh ESP dan ESPv2, serta peran IAM yang diperlukan untuk akun layanan yang disertakan untuk mengakses resource ini.

Konfigurasi Layanan Endpoint

ESP dan ESPv2 memanggil Service Control yang menggunakan konfigurasi layanan endpoint. Konfigurasi layanan endpoint adalah resource IAM, dan ESP dan ESPv2 memerlukan peran Pengontrol Layanan untuk mengaksesnya.

Peran IAM ada pada konfigurasi layanan endpoint, bukan pada project. Sebuah project mungkin memiliki beberapa konfigurasi layanan endpoint.

Gunakan perintah gcloud berikut untuk menambahkan peran ke akun layanan yang terpasang untuk konfigurasi layanan endpoint.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

Dengan
* SERVICE_NAME adalah nama layanan endpoint
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com adalah akun layanan yang disertakan.

Cloud Trace

ESP dan ESPv2 memanggil layanan Cloud Trace untuk mengekspor Trace ke project. Project ini disebut project pelacakan. Di ESP, project pelacakan dan project yang memiliki konfigurasi layanan endpoint sama. Di ESPv2, project pelacakan dapat ditentukan oleh flag --tracing_project_id, dan ditetapkan secara default ke project deployment.

ESP dan ESPv2 memerlukan peran Agen Cloud Trace untuk mengaktifkan Cloud Trace.

Gunakan perintah gcloud berikut untuk menambahkan peran ke akun layanan yang terpasang:

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

Dengan
* TRACING_PROJECT_ID adalah ID project pelacakan
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com adalah akun layanan yang disertakan. Untuk mengetahui informasi selengkapnya, lihat Apa yang dimaksud dengan peran dan izin?

Lihat gcloud iam service-accounts untuk mengetahui informasi selengkapnya tentang perintah ini.

Menjalankan ESP dalam container

Bagian ini menjelaskan cara men-deploy penampung ESP. Prosedur yang Anda gunakan bergantung pada tempat Anda men-deploy penampung ESP:

Menjalankan ESP di container Docker secara lokal atau di platform lain
Menjalankan ESP dalam container di cluster Kubernetes

Pada contoh berikut, opsi ESP --http_port hanya berfungsi jika layanan gRPC memiliki transcoding HTTP/JSON yang telah dikonfigurasi. Untuk mengetahui informasi selengkapnya, lihat Melakukan transcoding HTTP/JSON ke gRPC.

Menjalankan ESP di container Docker secara lokal atau di platform lain

Ganti nama file JSON yang berisi kunci pribadi untuk akun layanan menjadi service-account-creds.json, lalu salin ke $HOME/Downloads/ jika didownload ke direktori lain. Dengan cara ini, nama jalur lengkap cocok dengan nilai untuk --service_account_key dalam perintah docker run berikut.
Dalam perintah docker run berikut, ganti YOUR_SERVICE_NAME dengan nama layanan Anda.

Linux

sudo docker run \
    --detach \
    --name="esp" \
    --net="host" \
    --volume=$HOME/Downloads:/esp \
    --publish=8082 \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --http2_port=8083 \
    --backend=grpc://localhost:8080 \
    --service_account_key=/esp/service-account-creds.json

OS mac

Opsi Docker --net="host" tidak berfungsi di macOS. Sebagai gantinya, Anda harus melakukan pemetaan port eksplisit dari host ke container yang menggantikan --net="host" dengan --publish 8082:8082. Anda juga harus mengganti localhost dengan nama DNS khusus macOS docker.for.mac.localhost. Lihat Kasus penggunaan dan solusi dalam dokumentasi Docker untuk mengetahui informasi lebih lanjut.

sudo docker run \
  --detach \
  --name="esp" \
  --publish=8082:8082 \
  --volume=$HOME/Downloads:/esp \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --http2_port=8083 \
  --backend=grpc://docker.for.mac.localhost:8080 \
  --service_account_key=/esp/service-account-creds.json

Platform lain

sudo docker run \
  --detach \
  --name="esp" \
  --net="host" \
  --volume=$HOME/Downloads:/esp \
  --publish=8082 \
  gcr.io/endpoints-release/endpoints-runtime:1 \
  --service=YOUR_SERVICE_NAME \
  --rollout_strategy=managed \
  --http_port=8082 \
  --http2_port=8083 \
  --backend=grpc://IP_Address:PORT \
  --service_account_key=/esp/service-account-creds.json

Tabel berikut menjelaskan opsi Docker yang digunakan dalam perintah sebelumnya. Untuk mengetahui informasi tentang opsi ESP yang digunakan dalam contoh, lihat Opsi startup ESP.

Opsi	Deskripsi
`--detach`	Opsi Docker ini memulai container dalam mode terpisah, sehingga berjalan di latar belakang.
`--name="esp"`	Opsi Docker ini menyediakan nama yang mudah diakses untuk container. Misalnya, untuk melihat log dari container, Anda dapat menjalankan `docker logs esp`
`--net="host"`	Opsi Docker ini menunjukkan bahwa container Docker menggunakan konfigurasi jaringan yang sama dengan mesin host, sehingga dapat melakukan panggilan ke localhost pada mesin host. Opsi ini tidak berfungsi untuk menjalankan ESP secara lokal di macOS.
`--publish=8082:8082`	Untuk macOS, jika Anda ingin menjalankan ESP secara lokal, gunakan opsi Docker ini, bukan `--net="host"`, untuk melakukan pemetaan port eksplisit dari host ke container.
`--volume=` `$HOME/Downloads:/esp`	Opsi Docker ini memetakan direktori `$HOME/Downloads` lokal Anda ke direktori `/esp` di container. Pemetaan ini digunakan oleh opsi ESP `--service_account_key`.

Menjalankan ESP dalam container di cluster Kubernetes

Bagian ini menjelaskan cara men-deploy ESP ke cluster Kubernetes yang tidak ada di Google Cloud.

Agar API Anda dikelola oleh Endpoint, deploy container ESP ke pod Kubernetes yang sama dengan container API Anda. Kumpulan pod yang menjalankan ESP dan API Anda dikelompokkan dalam layanan Kubernetes menggunakan pemilih label, seperti app: my-api. Layanan Kubernetes menentukan kebijakan akses untuk melakukan load balancing terhadap permintaan klien ke port proxy.

Ganti nama file JSON yang berisi kunci pribadi untuk akun layanan menjadi service-account-creds.json, lalu salin ke $HOME/Downloads/ jika didownload ke direktori lain. Dengan cara ini, nama jalur lengkap akan cocok dengan perintah di langkah berikutnya.
Jalankan perintah berikut untuk membuat secret Kubernetes dan memasang secret sebagai volume Kubernetes.
```
kubectl create secret generic service-account-creds \
  --from-file=$HOME/Downloads/service-account-creds.json
```
Jika berhasil, pesan berikut akan ditampilkan: secret "service-account-creds" created

Dalam file konfigurasi Kubernetes Anda, tambahkan kode berikut, dengan mengganti YOUR_APP_NAME dengan nama API Anda dan YOUR_SERVICE_NAME dengan nama layanan Anda.

spec:
replicas: 1
template:
  metadata:
    labels:
      app: "YOUR_APP_NAME"
  spec:
    volumes:
      - name: service-account-creds
        secret:
          secretName: service-account-creds
          containers:
      - name: esp
        image: gcr.io/endpoints-release/endpoints-runtime:1
        args: [
          "--http_port=8082",
          "--http2_port=8083",
          "--backend=grpc://127.0.0.1:8081",
          "--service=YOUR_SERVICE_NAME",
          "--rollout_strategy=managed",
          "--service_account_key=/etc/nginx/creds/service-account-creds.json"
        ]
        ports:
          - containerPort: 8080
        volumeMounts:
          - mountPath: /etc/nginx/creds
            name: service-account-creds
            readOnly: true

Untuk mengetahui informasi tentang opsi ESP yang digunakan dalam contoh, lihat Opsi startup ESP.

Men-deploy ESP ke Kubernetes. Ganti YOUR_CONFIGURATION_FILE dengan nama file konfigurasi Kubernetes Anda.
```
kubectl apply -f YOUR_CONFIGURATION_FILE
```

Mengirim permintaan

Untuk mengonfirmasi bahwa file akun layanan sudah benar dan port dipetakan dengan benar, kirim beberapa permintaan ke API Anda dan pastikan permintaan tersebut melalui ESP. Anda dapat melihat log ESP dengan menjalankan:

sudo docker logs esp

Contoh berikut mengirim permintaan ke API contoh. Jika Anda tidak menggunakan API contoh, sebaiknya jalankan pengujian serupa.

Anda telah mengonfigurasi penampung ESP untuk menerima permintaan pada port 8082. Jika Anda mengirim permintaan langsung ke server di http://localhost:8080, permintaan tersebut akan mengabaikan ESP. Contoh:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8080/echo

Respons:

  {
    "message": "hello world"
  }

Saat Anda mengirim permintaan ke http://localhost:8082 yang melewati ESP, dan Anda tidak mengirim kunci API, ESP akan menolak permintaan tersebut. Contoh:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8082/echo

Respons:

  {
   "code": 16,
   "message": "Method doesn't allow unregistered callers (callers without
    established identity). Please use API Key or other form of API consumer
    identity to call this API.",
   "details": [
    {
     "@type": "type.googleapis.com/google.rpc.DebugInfo",
     "stackEntries": [],
     "detail": "service_control"
    }
   ]
  }

Untuk menguji API dengan kunci API:

Buat kunci API di halaman API credentials.

Buka halaman Kredensial
Klik Create credentials, lalu pilih API key.
Salin kunci, lalu tempelkan ke pernyataan variabel lingkungan berikut:
```
export KEY=AIza...
```

Kirim permintaan dengan kunci:

curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  http://localhost:8082/echo?key=$KEY

Anda melihat respons yang berhasil:

{
  "message": "hello world"
}

Pembersihan

Matikan dan hapus container Docker esp menggunakan alat docker:

    sudo docker stop esp
    sudo docker rm esp

Jika Anda ingin membersihkan konfigurasi layanan yang di-deploy, lihat Menghapus instance API dan API.

Langkah selanjutnya

Pelajari cara menambahkan dukungan SSL ke ESP