Halaman ini diterjemahkan oleh Cloud Translation API.

Menjalankan ESP 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-deploynya ke platform produksi.
Pastikan setelan keamanan dikonfigurasi dan berfungsi dengan benar, serta metrik dan log muncul di halaman Endpoints > Services seperti yang diharapkan.

Prasyarat

Sebagai titik awal, halaman ini mengasumsikan bahwa:

Anda telah menginstal Docker, jika men-deploy penampung ESP secara lokal atau ke VM. Lihat Menginstal Docker untuk mengetahui informasi selengkapnya.
Anda telah men-deploy API secara lokal atau di host yang dapat dijangkau oleh host tempat Anda menjalankan ESP.
Anda telah mengonfigurasi Cloud Endpoints dan men-deploy konfigurasi untuk membuat layanan terkelola bagi 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 Membuat akun layanan.

Opsional: Menggunakan API contoh

Bagian ini akan memandu Anda mengonfigurasi dan men-deploy contoh getting-started untuk Endpoints versi Python 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 Contoh untuk mengetahui lokasi GitHub contoh getting-started dalam bahasa pilihan Anda. Ikuti petunjuk dalam file README.md contoh untuk dijalankan secara lokal, lalu ikuti petunjuk di bagian ini untuk mengonfigurasi Endpoint dan men-deploy konfigurasi Endpoint.

Mendapatkan software yang diperlukan

Jika Anda belum menyiapkan lingkungan pengembangan Python, lihat Menyiapkan lingkungan pengembangan Python untuk mendapatkan panduan. Pastikan Anda telah menginstal hal berikut:

Mendapatkan kode sampel

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 bagian Membuat akun layanan.
Simpan file openapi.yaml.

Men-deploy konfigurasi Endpoint

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

Update gcloud CLI:
```
gcloud components update
```
Pastikan 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.
Tetapkan project default ke project ID Anda:
```
gcloud config set project YOUR-PROJECT-ID
```
Ganti YOUR-PROJECT-ID dengan project ID project Google Cloud yang Anda tentukan dalam file openapi.yaml.

Deploy konfigurasi Anda:

gcloud endpoints services deploy openapi.yaml

Pengelolaan Layanan menggunakan teks yang Anda tentukan di kolom host dalam file openapi.yaml untuk membuat layanan Endpoints 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 menampilkan informasi ke terminal. Anda dapat mengabaikan peringatan tentang jalur dalam file openapi.yaml yang tidak memerlukan kunci API dengan aman. Setelah 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 merespons pesan yang Anda kirim, dan merespons dengan hal berikut:

{
"message": "hello world"
}

Membuat akun layanan

Untuk menyediakan pengelolaan API, 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, Compute Engine, atau lingkungan fleksibel App Engine, ESP dan ESPv2 akan mendapatkan token akses untuk Anda melalui layanan metadata Google Cloud.

Saat men-deploy ESP atau ESPv2 ke lingkungan non-Google Cloud, seperti desktop lokal, cluster Kubernetes lokal, atau penyedia cloud lainnya, Anda harus memberikan 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 Buka.
Klik + Create Service Account.
Di kolom Service account name, masukkan nama untuk 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 Buat. 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 kode berikut untuk 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 di project yang sama dengan project 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 berada dalam project Google Cloud tempat API berada. Jika Anda menjalankan gcloud auth list, akun yang Anda pilih 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 dalam 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 agar akun layanan yang terpasang dapat mengakses resource ini.

Konfigurasi Layanan Endpoint

ESP dan ESPv2 memanggil Kontrol Layanan yang menggunakan konfigurasi layanan endpoint. Konfigurasi layanan endpoint adalah resource IAM dan ESP serta ESPv2 memerlukan peran Service Controller untuk mengaksesnya.

Peran IAM ada di konfigurasi layanan endpoint, bukan di project. Project dapat memiliki beberapa konfigurasi layanan endpoint.

Gunakan perintah gcloud berikut untuk menambahkan peran ke akun layanan yang terlampir 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 terlampir.

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 adalah sama. Di ESPv2, project pelacakan dapat ditentukan oleh flag --tracing_project_id, dan ditetapkan secara default ke project deployment.

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

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

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 project ID pelacakan
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com adalah akun layanan yang terpasang. Untuk mengetahui informasi selengkapnya, lihat Apa yang dimaksud dengan peran dan izin?

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

Menjalankan ESP dalam penampung

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

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

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 dan salin ke $HOME/Downloads/ jika file tersebut didownload ke direktori lain. Dengan cara ini, nama jalur lengkap akan cocok dengan nilai untuk --service_account_key dalam perintah docker run berikut.
Pada 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 \
  --backend=localhost:8080 \
  --service_account_key=/esp/service-account-creds.json

Mac OS

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

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 \
  --backend=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 \
  --backend=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 penampung dalam mode terpisah, sehingga berjalan di latar belakang.
`--name="esp"`	Opsi Docker ini memberikan nama yang mudah diakses untuk penampung. Misalnya, untuk melihat log dari penampung, Anda dapat menjalankan `docker logs esp`
`--net="host"`	Opsi Docker ini menunjukkan bahwa penampung Docker menggunakan konfigurasi jaringan yang sama dengan mesin host, sehingga memungkinkannya melakukan panggilan ke localhost di mesin host. Opsi ini tidak berfungsi untuk menjalankan ESP secara lokal di macOS.
`--publish=8082:8082`	Untuk macOS saat 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` dalam penampung. Pemetaan ini digunakan oleh opsi ESP `--service_account_key`.

Menjalankan ESP dalam penampung di cluster Kubernetes

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

Agar API Anda dikelola oleh Endpoints, deploy penampung ESP ke pod Kubernetes yang sama dengan penampung 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 permintaan klien ke port proxy.

Ganti nama file JSON yang berisi kunci pribadi untuk akun layanan menjadi service-account-creds.json dan salin ke $HOME/Downloads/ jika file tersebut 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

Di file konfigurasi Kubernetes, tambahkan kode berikut, dengan mengganti YOUR_APP_NAME dengan nama API 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",
          "--backend=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 telah 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 mengirimkan permintaan ke API contoh. Jika tidak menggunakan API contoh, sebaiknya jalankan pengujian serupa.

Anda telah mengonfigurasi penampung ESP untuk menerima permintaan di port 8082. Jika Anda mengirim permintaan langsung ke server di http://localhost:8080, permintaan 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 Kredensial API.

Buka halaman Kredensial
Klik Create credentials, lalu pilih API key.
Salin kunci, lalu tempelkan ke dalam 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 akan 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 API dan instance API.

Langkah selanjutnya

Pelajari cara menambahkan dukungan SSL ke ESP