Menjalankan ESP secara lokal atau di platform lain

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 berada di Google Cloud.

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

  • Mencoba ESP sebelum men-deploy-nya ke platform produksi.
  • Memverifikasi bahwa 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 container 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 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, lewati ke Membuat akun layanan.

Opsional: Menggunakan API contoh

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

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 contoh

  1. Clone repositori aplikasi contoh ke komputer lokal Anda:

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

  2. Ubah ke direktori yang berisi kode contoh:

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

Mengonfigurasi Endpoints

  1. 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"

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

  3. Simpan file openapi.yaml.

Men-deploy konfigurasi Endpoints

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

  1. Update gcloud CLI:

    gcloud components update

  2. Pastikan gcloud CLI (gcloud) diizinkan untuk mengakses data dan layanan Anda di Google Cloud:

    gcloud auth login

    Di tab browser baru yang terbuka, pilih akun.

  3. Tetapkan project default ke project ID Anda:

    gcloud config set project YOUR-PROJECT-ID

    Ganti YOUR-PROJECT-ID dengan project ID Google Cloud project yang Anda tentukan dalam file openapi.yaml.

  4. 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. 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]

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

Memulai server lokal

  1. Buat virtualenv, aktifkan, lalu instal dependensi aplikasi.

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

  2. Mulai server:

    python main.py

  3. 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 mengulang pesan yang Anda kirimkan, dan merespons dengan hal berikut:

    {
"message": "hello world"
}

Membuat akun layanan

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

Saat Anda men-deploy ESP atau ESPv2 ke non-Google Cloud lingkungan, seperti desktop lokal, cluster Kubernetes lokal, atau penyedia cloud lain, 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 Google Cloud konsol atau Google Cloud CLI untuk membuat akun layanan dan file kunci pribadi:

Konsol

  1. Di Google Cloud konsol, buka halaman Akun Layanan .

    Buka halaman Service Accounts

  2. Klik Select a project.
  3. Pilih project tempat API Anda dibuat, lalu klik Open.
  4. Klik + Create Service Account.
  5. Di kolom Service account name, masukkan nama akun layanan Anda.
  6. Klik Create.
  7. Klik Continue.
  8. Klik Done.
  9. Klik alamat email akun layanan yang baru dibuat.
  10. Klik Keys.
  11. Klik Tambahkan kunci, lalu klik Buat kunci baru.

  12. Klik Buat. File kunci JSON akan didownload ke komputer Anda.

    Pastikan Anda menyimpannya 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.

  13. Klik Close.

gcloud

  1. Masukkan perintah berikut untuk menampilkan project ID project Anda Google Cloud :

    gcloud projects list

  2. Ganti PROJECT_ID dalam perintah berikut untuk menetapkan default project ke project tempat API Anda berada:

    gcloud config set project PROJECT_ID

  3. Pastikan Google Cloud CLI (gcloud) diizinkan 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 di Google Cloud project tempat API berada. Jika Anda menjalankan gcloud auth list, akun yang Anda pilih akan ditampilkan sebagai akun aktif untuk project tersebut.

  4. 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.

  5. 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 terlampir 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 Pengontrol Layanan untuk mengaksesnya.

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

Gunakan perintah gcloud berikut untuk menambahkan peran ke akun layanan 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 Cloud Trace layanan 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 secara default adalah project deployment.

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

Gunakan perintah gcloud berikut untuk menambahkan peran ke akun layanan 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 terlampir. Untuk mengetahui informasi selengkapnya, lihat Apa yang dimaksud dengan peran dan izin?

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

Menjalankan ESP dalam container

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

Menjalankan ESP dalam container Docker secara lokal atau di platform lain

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

  2. 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 \
  --backend=localhost:8080 \
  --service_account_key=/esp/service-account-creds.json

mac OS

Opsi Docker --net="host" tidak berfungsi di macOS. Sebagai gantinya, Anda harus melakukan pemetaan port eksplisit dari host ke container dengan 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 container dalam mode terpisah, sehingga berjalan di latar belakang.
--name="esp" Opsi Docker ini memberikan 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 memungkinkan container 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 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 berada di Google Cloud.

Agar API Anda dikelola oleh Endpoints, 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 menyeimbangkan beban permintaan klien ke port proxy.

  1. Ganti nama file JSON yang berisi kunci pribadi untuk akun layanan menjadi service-account-creds.json dan salin ke $HOME/Downloads/ jika didownload ke direktori lain. Dengan cara ini, jalur lengkap akan cocok dengan perintah di langkah berikutnya.

  2. 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

  3. Di file konfigurasi Kubernetes, tambahkan hal berikut, ganti 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",
          "--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.

  4. 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 mengirimkan permintaan ke API contoh. Jika Anda tidak menggunakan API contoh, sebaiknya jalankan pengujian serupa.

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

  1. Buat kunci API di halaman API credentials.

    Buka halaman Kredensial

  2. Klik Create credentials, lalu pilih API key.

  3. Salin kunci, lalu tempelkan ke pernyataan variabel lingkungan berikut:

    export KEY=AIza...

  4. 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

Nonaktifkan 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 berikutnya