Men-deploy backend API

Halaman ini menjelaskan cara men-deploy kode backend API dan Extensible Service Proxy (ESP) ke Google Kubernetes Engine, Compute Engine, dan lingkungan fleksibel App Engine.

Meskipun langkah deployment bervariasi bergantung pada platform yang menghosting API Anda, selalu ada langkah untuk memberi ESP nama layanan dan opsi yang mengonfigurasi ESP agar menggunakan konfigurasi layanan Cloud Endpoints yang terakhir di-deploy. Dengan informasi ini, ESP dapat memperoleh konfigurasi Endpoint API, yang memungkinkan ESP melakukan proxy permintaan dan respons sehingga Endpoint dapat mengelola API Anda.

Prasyarat

Sebagai permulaan, halaman ini mengasumsikan bahwa Anda telah:

Mempersiapkan deployment

App Engine

Dengan penambahan langkah konfigurasi kecil (dijelaskan dalam langkah-langkah berikut), men-deploy API agar dikelola oleh Endpoint sama dengan men-deploy aplikasi apa pun ke lingkungan fleksibel App Engine. Ikuti dokumentasi App Engine untuk:

Anda men-deploy API ke App Engine menggunakan perintah gcloud app deploy. Perintah ini secara otomatis membuat image container menggunakan layanan Container Builder, lalu men-deploy image tersebut ke lingkungan fleksibel App Engine Anda.

Sebelum melakukan deployment:

Compute Engine

Agar Endpoint dapat mengelola API, Anda harus menginstal dan mengonfigurasi ESP, serta kode server backend untuk API Anda. Anda harus menginstal Docker di instance VM Compute Engine agar dapat menjalankan image Docker ESP yang tersedia gratis di Container Registry.

Sebelum melakukan deployment:

Berikut adalah uraian secara umum langkah-langkah yang harus Anda lakukan sebelum dapat men-deploy API dan ESP ke Compute Engine. Secara umum, Anda melakukan semua langkah seperti yang biasa dilakukan untuk menjalankan kode server backend di Compute Engine.

  1. Buat, konfigurasikan, dan mulai instance VM Anda. Lihat dokumentasi Compute Engine.
  2. Instal Docker Enterprise Edition (EE) atau Docker Community Edition (CE) di instance VM Anda. Lihat Menginstal Docker.
  3. Membuat container Docker untuk kode server backend. Lihat Dokumentasi Cloud Build.
  4. Kirim container ke Container Registry atau registry lain.
  5. Pastikan Anda berhasil:

GKE

Saat Anda membuat cluster di Konsol Google Cloud, secara default, cakupan OAuth yang diberikan ke akun layanan cluster mencakup cakupan yang diperlukan Endpoint:

  • Kontrol Layanan: Diaktifkan
  • Pengelolaan Layanan: Hanya Baca

Saat membuat cluster menggunakan perintah gcloud container clusters create atau file konfigurasi pihak ketiga, pastikan Anda menentukan cakupan berikut:

  • "https://www.googleapis.com/auth/servicecontrol"
  • "https://www.googleapis.com/auth/service.management.readonly"

Untuk mengetahui informasi selengkapnya, lihat Apa yang dimaksud dengan cakupan akses?

Sebelum melakukan deployment:

Dengan menambahkan bagian kecil ke file manifes deployment, Anda dapat menjalankan image Docker ESP di cluster container bersama dengan aplikasi dalam container. Berikut adalah uraian secara umum langkah-langkah yang harus Anda ambil sebelum dapat men-deploy API dengan ESP ke GKE. Secara umum, Anda melakukan semua langkah seperti yang biasa dilakukan untuk menjalankan kode server backend di GKE.

  1. Deploy aplikasi dalam container ke cluster container. Langkah-langkah umum sebagaimana dijelaskan dalam dokumentasi GKE adalah:
    1. Kemas aplikasi Anda ke dalam image Docker.
    2. Upload image ke registry.
    3. Buat cluster container.
    4. Deploy aplikasi Anda ke cluster.
    5. Ekspos aplikasi Anda ke internet.
  2. Pastikan Anda berhasil:
    • Mulai server API Anda.
    • Mengirim permintaan ke API Anda.

Men-deploy API dan ESP Anda

App Engine

Untuk men-deploy API dan ESP ke App Engine:

  1. Dapatkan service name API Anda. Ini adalah nama yang Anda tentukan dalam kolom host pada dokumen OpenAPI Anda.
  2. Edit file app.yaml, dan tambahkan bagian bernama endpoints_api_service yang berisi nama layanan. Anda dapat menggunakan file app.yaml dari tutorial sebagai model:
    Java
    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed
    Python
    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed
    Mulai
    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed
    PHP
    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
      # previously run the deploy command, you can list your existing configuration
      # ids using the 'configs list' command as follows:
      #
      #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
      #
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed
    Ruby
    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed
    NodeJS
    endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed

    Ganti ENDPOINTS-SERVICE-NAME dengan nama layanan API Anda. Contoh:

    endpoints_api_service:
      name: example-project-12345.appspot.com
      rollout_strategy: managed
      

    Opsi rollout_strategy: managed mengonfigurasi ESP untuk menggunakan konfigurasi layanan yang terakhir di-deploy. Saat Anda menentukan opsi ini, hingga 5 menit setelah Anda men-deploy konfigurasi layanan baru, ESP akan mendeteksi perubahan tersebut dan mulai menggunakannya secara otomatis. Sebaiknya tentukan opsi ini, bukan ID konfigurasi khusus untuk digunakan ESP.

    Jika aplikasi Anda didasarkan pada microservice, Anda harus menyertakan bagian endpoints_api_service di setiap file app.yaml.

  3. Simpan file app.yaml (atau beberapa file).
  4. Deploy kode backend dan ESP Anda ke App Engine:
    gcloud app deploy
    

Karena Anda menambahkan bagian endpoints_api_service ke file app.yaml, perintah gcloud app deploy men-deploy dan mengonfigurasi ESP dalam container terpisah dengan lingkungan fleksibel App Engine Anda. Semua traffic permintaan diarahkan melalui ESP, dan menjadi proxy permintaan serta respons ke dan dari penampung yang menjalankan kode server backend Anda.

Jika Anda perlu mengonfigurasi ESP untuk menggunakan ID konfigurasi tertentu:

  1. Di bagian endpoints_api_service file app.yaml Anda, tambahkan kolom config_id dan tetapkan ke ID konfigurasi tertentu.
  2. Hapus rollout_strategy: managed atau tetapkan rollout_strategy ke fixed. Opsi fixed mengonfigurasi ESP agar menggunakan konfigurasi layanan yang Anda tentukan dalam config_id.
  3. Deploy ulang API dan ESP Anda: gcloud app deploy

Sebaiknya jangan mengonfigurasi ESP untuk menggunakan ID konfigurasi tertentu dalam waktu lama karena jika men-deploy konfigurasi layanan yang diperbarui, Anda harus memulai ulang ESP untuk menggunakan konfigurasi baru.

Untuk menghapus ID konfigurasi tertentu:

  1. Hapus opsi config_id dari file app.yaml.
  2. Tambahkan opsi rollout_strategy: managed.
  3. Berikan perintah gcloud app deploy

Saat Anda menggunakan opsi rollout_strategy: managed, jangan sertakan config_id: YOUR_SERVICE_CONFIG_ID dalam file app.yaml. Jika Anda melakukannya, gcloud app deploy akan gagal dengan error berikut:

config_id is forbidden when rollout_strategy is set to "managed".

Saat Anda men-deploy API ke lingkungan fleksibel App Engine untuk pertama kalinya, mungkin ada penundaan saat virtual machine (VM) dan infrastruktur lainnya disiapkan. Untuk informasi tambahan, lihat Memastikan deployment yang berhasil dalam dokumentasi App Engine.

Compute Engine

Untuk men-deploy API dengan ESP ke Compute Engine dengan Docker:

  1. Hubungkan ke instance VM Anda. Ganti INSTANCE_NAME dengan nama instance VM Anda.
    gcloud compute ssh INSTANCE_NAME
  2. Buat jaringan penampung Anda sendiri yang disebut esp_net:
    sudo docker network create --driver bridge esp_net
  3. Jalankan instance image kode server backend Anda dan hubungkan ke jaringan container esp_net:
    sudo docker run \
        --detach \
        --name=YOUR_API_CONTAINER_NAME \
        --net=esp_net \
        gcr.io/YOUR_PROJECT_ID/YOUR_IMAGE:1.0
    • Ganti YOUR_API_CONTAINER_NAME dengan nama penampung Anda.
    • Ganti YOUR_PROJECT_ID dengan project ID Google Cloud yang Anda gunakan saat mengirim image.
    • Ganti YOUR_IMAGE dengan nama image Anda.
  4. Dapatkan nama layanan API Anda. Ini adalah nama yang Anda tentukan dalam kolom host pada dokumen OpenAPI Anda.
  5. Jalankan instance image Docker ESP:
    sudo docker run \
        --name=esp \
        --detach \
        --publish=80:8080 \
        --net=esp_net \
        gcr.io/endpoints-release/endpoints-runtime:1 \
        --service=SERVICE_NAME \
        --rollout_strategy=managed \
        --backend=YOUR_API_CONTAINER_NAME:8080
    • Ganti SERVICE_NAME dengan nama layanan Anda.
    • Ganti YOUR_API_CONTAINER_NAME dengan nama penampung API Anda.

    Opsi --rollout_strategy=managed mengonfigurasi ESP untuk menggunakan konfigurasi layanan yang terakhir di-deploy. Saat Anda menentukan opsi ini, hingga 5 menit setelah Anda men-deploy konfigurasi layanan baru, ESP akan mendeteksi perubahan tersebut dan mulai menggunakannya secara otomatis. Sebaiknya tentukan opsi ini, bukan ID konfigurasi khusus untuk digunakan ESP.

Jika Anda perlu mengonfigurasi ESP untuk menggunakan ID konfigurasi tertentu:

  1. Sertakan opsi --version dan tetapkan ke ID konfigurasi tertentu.
  2. Hapus opsi --rollout_strategy=managed atau tetapkan --rollout_strategy ke fixed. Opsi fixed mengonfigurasi ESP agar menggunakan konfigurasi layanan yang Anda tentukan dalam --version.
  3. Berikan perintah docker run lagi.

Jika Anda menentukan opsi --rollout_strategy=managed dan --version, ESP akan memulai dengan konfigurasi yang Anda tentukan di --version, lalu berjalan dalam mode terkelola dan mendapatkan konfigurasi terbaru.

Sebaiknya jangan mengonfigurasi ESP untuk menggunakan ID konfigurasi tertentu dalam waktu lama karena jika men-deploy konfigurasi layanan yang diperbarui, Anda harus memulai ulang ESP untuk menggunakan konfigurasi baru.

Untuk menghapus ID konfigurasi tertentu:

  1. Pada tanda ESP untuk docker run, hapus opsi --version.
  2. Tambahkan opsi --rollout_strategy=managed.
  3. Berikan perintah docker run untuk memulai ulang ESP.

Lihat Opsi startup ESP untuk mengetahui daftar lengkap opsi yang dapat Anda tentukan saat memulai ESP.

GKE

Untuk men-deploy ESP ke GKE:

  1. Dapatkan nama layanan API Anda (nama yang Anda tentukan di kolom host pada dokumen OpenAPI).
  2. Buka file manifes Deployment Anda (disebut sebagai file deployment.yaml) dan tambahkan kode berikut ke bagian container:
    containers:
    - name: esp
      image: gcr.io/endpoints-release/endpoints-runtime:1
      args: [
        "--http_port=8081",
        "--backend=127.0.0.1:8080",
        "--service=SERVICE_NAME",
        "--rollout_strategy=managed"
      ]

    Ganti SERVICE_NAME dengan nama layanan API Anda.

    Opsi --rollout_strategy=managed" mengonfigurasi ESP untuk menggunakan konfigurasi layanan yang terakhir di-deploy. Saat Anda menentukan opsi ini, hingga 5 menit setelah Anda men-deploy konfigurasi layanan baru, ESP akan mendeteksi perubahan tersebut dan mulai menggunakannya secara otomatis. Sebaiknya tentukan opsi ini, bukan ID konfigurasi khusus untuk digunakan ESP.

  3. Mulai layanan Kubernetes menggunakan perintah kubectl create:
    kubectl create -f deployment.yaml

Jika Anda perlu mengonfigurasi ESP untuk menggunakan ID konfigurasi tertentu:

  1. Dalam file manifes Deployment Anda, tambahkan opsi --version dan tetapkan ke ID konfigurasi tertentu.
  2. Hapus --rollout_strategy=managed atau tetapkan --rollout_strategy ke fixed. Opsi fixed mengonfigurasi ESP agar menggunakan konfigurasi layanan yang Anda tentukan di --version.
  3. Mulai layanan Kubernetes: kubectl create -f deployment.yaml

Jika Anda menentukan opsi --rollout_strategy=managed dan --version, ESP akan memulai dengan konfigurasi yang Anda tentukan di --version, lalu berjalan dalam mode terkelola dan mendapatkan konfigurasi terbaru.

Sebaiknya jangan mengonfigurasi ESP untuk menggunakan ID konfigurasi tertentu dalam waktu lama karena jika men-deploy konfigurasi layanan yang diperbarui, Anda harus memulai ulang ESP untuk menggunakan konfigurasi baru.

Untuk menghapus ID konfigurasi tertentu:

  1. Dalam file manifes Deployment, hapus opsi --version.
  2. Tambahkan --rollout_strategy=managed.
  3. Mulai layanan Kubernetes: kubectl create -f deployment.yaml

Lihat Opsi startup ESP untuk mengetahui daftar lengkap opsi yang dapat Anda tentukan saat memulai ESP.

Aktivitas API pelacakan

Setelah men-deploy ESP dan backend API, Anda dapat menggunakan alat seperti curl atau Postman untuk mengirim permintaan ke API Anda. Jika Anda tidak mendapatkan respons yang berhasil, lihat Memecahkan masalah error respons.

Setelah mengirim beberapa permintaan, Anda dapat:

Langkah selanjutnya