Mengamankan traffic ke layanan dengan gcloud CLI

Halaman ini menunjukkan cara men-deploy API di API Gateway untuk mengamankan traffic ke layanan backend.

Gunakan langkah-langkah berikut untuk men-deploy API baru guna mengakses layanan backend di fungsi Cloud Run menggunakan Google Cloud CLI. Panduan memulai ini juga menjelaskan cara menggunakan kunci API untuk melindungi backend Anda dari akses tanpa izin.

Sebelum memulai

  1. Di konsol Google Cloud, buka halaman Dasbor, lalu pilih atau buat project Google Cloud.

    Buka Dasbor

  2. Konfirmasi bahwa penagihan diaktifkan untuk project Anda.

    Mengaktifkan penagihan

  3. Pastikan Google Cloud CLI telah didownload dan diinstal di komputer Anda.

    Mendownload gcloud CLI

  4. Perbarui komponen gcloud:

    gcloud components update

  5. Tetapkan project default. Ganti PROJECT_ID dengan ID project Google Cloud Anda.

    gcloud config set project PROJECT_ID

Mengaktifkan layanan yang diperlukan

API Gateway mengharuskan Anda mengaktifkan layanan Google berikut:

Nama Judul
apigateway.googleapis.com API Gateway API
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

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 apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Untuk mengetahui informasi selengkapnya tentang layanan gcloud, lihat layanan gcloud.

Men-deploy backend API

API Gateway berada di depan layanan backend yang di-deploy dan menangani semua permintaan masuk. Dalam panduan memulai ini, API Gateway merutekan panggilan masuk ke backend fungsi Cloud Run bernama helloGET yang berisi fungsi berikut:

/**
 * HTTP Cloud Function.
 * This function is exported by index.js, and is executed when
 * you make an HTTP request to the deployed function's endpoint.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */

exports.helloGET = (req, res) => {
  res.send('Hello World!');
};

Ikuti langkah-langkah di Panduan memulai: Menggunakan Google Cloud CLI untuk mendownload contoh kode fungsi Cloud Run dan men-deploy layanan backend fungsi Cloud Run.

Membuat API

Sekarang Anda siap membuat API di API Gateway.

  1. Masukkan perintah berikut, dengan:

    • API_ID menentukan nama API Anda. Lihat Persyaratan ID API untuk mengetahui pedoman penamaan API.
    • PROJECT_ID menentukan nama project Google Cloud Anda.
    gcloud api-gateway apis create API_ID --project=PROJECT_ID

    Contoh:

    gcloud api-gateway apis create my-api --project=my-project

  2. Setelah berhasil diselesaikan, Anda dapat menggunakan perintah berikut untuk melihat detail tentang API baru:

    gcloud api-gateway apis describe API_ID --project=PROJECT_ID

    Contoh:

    gcloud api-gateway apis describe my-api --project=my-project

    Perintah ini menampilkan hal berikut:

      createTime: '2020-02-29T21:52:20.297426875Z'
  displayName: my-api
  managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog
  name: projects/my-project/locations/global/apis/my-api
  state: ACTIVE
  updateTime: '2020-02-29T21:52:20.647923711Z'

Perhatikan nilai properti managedService. Nilai ini digunakan untuk mengaktifkan API Anda di langkah berikutnya.

Membuat konfigurasi API

Sebelum dapat digunakan untuk mengelola traffic ke backend API yang di-deploy, API Gateway memerlukan konfigurasi API.

Anda dapat membuat konfigurasi API menggunakan spesifikasi OpenAPI yang berisi anotasi khusus untuk menentukan perilaku API Gateway yang dipilih. Spesifikasi OpenAPI yang digunakan untuk panduan memulai ini berisi petunjuk pemilihan rute ke backend fungsi Cloud Run kami:

# openapi2-functions.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

Untuk mengupload spesifikasi OpenAPI ini dan membuat konfigurasi API menggunakan gcloud CLI:

  1. Dari command line, buat file baru bernama openapi2-functions.yaml.

  2. Salin dan tempel konten spesifikasi OpenAPI yang ditampilkan di atas ke dalam file yang baru dibuat.

  3. Edit file sebagai berikut:

    1. Di kolom title, ganti API_ID dengan nama API Anda dan ganti optional-string dengan deskripsi singkat pilihan Anda. Nilai kolom ini digunakan saat membuat kunci API yang memberikan akses ke API ini.
    2. Di kolom address, ganti GCP_REGION dengan region Google Cloud dari fungsi yang di-deploy dan PROJECT_ID dengan nama project Google Cloud Anda.

  4. Masukkan perintah berikut, dengan:

    • CONFIG_ID menentukan nama konfigurasi API Anda.
    • API_ID menentukan nama API Anda.
    • API_DEFINITION menentukan nama file spesifikasi OpenAPI.
    • PROJECT_ID menentukan nama project Google Cloud Anda.
    • SERVICE_ACCOUNT_EMAIL menentukan akun layanan yang digunakan untuk menandatangani token untuk backend dengan autentikasi yang dikonfigurasi. Untuk informasi selengkapnya, lihat Mengonfigurasi akun layanan. 
    gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

    Contoh:

    gcloud api-gateway api-configs create my-config \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com

    Operasi ini mungkin memerlukan waktu beberapa menit hingga selesai karena konfigurasi API disebarkan ke sistem downstream. Membuat konfigurasi API yang kompleks dapat memerlukan waktu hingga sepuluh menit untuk berhasil diselesaikan.

  5. Setelah konfigurasi API dibuat, Anda dapat melihat detailnya dengan menjalankan perintah ini:

    gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID

    Contoh:

    gcloud api-gateway api-configs describe my-config \
  --api=my-api --project=my-project

    Output menampilkan detail konfigurasi API Anda, termasuk nama dan status, seperti yang ditunjukkan pada contoh berikut:

    createTime: '2020-02-07T18:17:01.839180746Z'
displayName: my-config
gatewayConfig:
backendConfig:
  googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com
name: projects/my-project/locations/global/apis/my-api/configs/my-config
serviceRollout:
rolloutId: 2020-02-07r0
state: ACTIVE
updateTime: '2020-02-07T18:17:02.173778118Z'

Membuat gateway

Sekarang, deploy konfigurasi API di gateway. Men-deploy konfigurasi API di gateway akan menentukan URL eksternal yang dapat digunakan klien API untuk mengakses API Anda.

Jalankan perintah berikut untuk men-deploy konfigurasi API yang baru saja Anda buat ke API Gateway:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

dengan:

  • GATEWAY_ID menentukan nama gateway.
  • API_ID menentukan nama API Gateway API yang terkait dengan gateway ini.
  • CONFIG_ID menentukan nama konfigurasi API yang di-deploy ke gateway.

  • GCP_REGION adalah region Google Cloud untuk gateway yang di-deploy.

  • PROJECT_ID menentukan nama project Google Cloud Anda.

Contoh:

gcloud api-gateway gateways create my-gateway \
  --api=my-api --api-config=my-config \
  --location=us-central1 --project=my-project

Setelah berhasil diselesaikan, gunakan perintah berikut untuk melihat detail tentang gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Contoh:

gcloud api-gateway gateways describe my-gateway \
  --location=us-central1 --project=my-project

Perintah ini menampilkan hal berikut:

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: my-gateway
name: projects/my-project/locations/us-central1/gateways/my-gateway
serviceAccount:
      email: 0000000000000-compute@developer.gserviceaccount.com
state: ACTIVE
updateTime: '2020-02-05T13:45:00.844705087Z'

Perhatikan nilai properti defaultHostname. Ini adalah bagian nama host dari URL gateway yang Anda gunakan untuk menguji deployment di langkah berikutnya.

Menguji deployment API

Sekarang Anda dapat mengirim permintaan ke API menggunakan URL yang dibuat saat gateway di-deploy.

Masukkan perintah curl berikut, dengan:

  • DEFAULT_HOSTNAME menentukan bagian nama host dari URL gateway yang di-deploy.
  • hello adalah jalur yang ditentukan dalam konfigurasi API Anda.
curl https://DEFAULT_HOSTNAME/hello

Contoh: 

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

Output-nya adalah:

Hello World!

Anda telah berhasil membuat dan men-deploy API Gateway.

Mengamankan akses menggunakan kunci API

Untuk mengamankan akses ke backend API, buat kunci API yang terkait dengan project Anda dan berikan akses kunci tersebut untuk memanggil API Anda. Lihat Membatasi akses API dengan kunci API untuk mengetahui informasi selengkapnya.

Jika belum memiliki kunci API yang terkait dengan project Google Cloud yang Anda gunakan dalam panduan memulai ini, Anda dapat menambahkannya dengan mengikuti langkah-langkah di Membuat Kunci API.

Untuk mengamankan akses ke gateway menggunakan kunci API:

  1. Aktifkan dukungan kunci API untuk layanan Anda. Masukkan perintah berikut, dengan:
    • MANAGED_SERVICE_NAME menentukan nama layanan terkelola yang dibuat saat Anda men-deploy API. Hal ini dapat dilihat di properti Layanan Terkelola yang tercantum dengan perintah gcloud apigee-gateway apis describe.
    • PROJECT_ID menentukan nama project Google Cloud Anda.
    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
     Misalnya: 
    gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
  2. Ubah spesifikasi OpenAPI yang digunakan untuk membuat konfigurasi API Anda agar menyertakan petunjuk untuk menerapkan kebijakan keamanan validasi kunci API di semua traffic. Tambahkan jenis security dan securityDefinitions seperti yang ditunjukkan: 
      # openapi2-functions.yaml
  swagger: '2.0'
  info:
    title: API_ID optional-string
    description: Sample API on API Gateway with a Google Cloud Functions backend
    version: 1.0.0
  schemes:
    - https
  produces:
    - application/json
  paths:
    /hello:
      get:
        summary: Greet a user
        operationId: hello
        x-google-backend:
          address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
        security:
        - api_key: []
        responses:
          '200':
            description: A successful response
            schema:
              type: string
  securityDefinitions:
    # This section configures basic authentication with an API key.
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"
     securityDefinition mengonfigurasi API Anda untuk mewajibkan kunci API yang diteruskan sebagai parameter kueri bernama key saat meminta akses ke semua jalur yang ditentukan dalam spesifikasi.
  3. Buat konfigurasi API baru dengan spesifikasi OpenAPI yang diubah menggunakan perintah berikut: 
    gcloud api-gateway api-configs create NEW_CONFIG_ID \
--api=API_ID --openapi-spec=NEW_API_DEFINITION \
--project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
     Misalnya: 
    gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com
  4. Jalankan perintah berikut untuk memperbarui gateway yang ada dengan konfigurasi API baru: 
    gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID
     Misalnya: 
    gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1 --project=my-project

Menguji kunci API

Setelah membuat dan men-deploy API yang diubah, coba buat permintaan ke API tersebut.

Masukkan perintah curl berikut, dengan:

  • DEFAULT_HOSTNAME menentukan bagian nama host dari URL gateway yang di-deploy.
  • hello adalah jalur yang ditentukan dalam konfigurasi API Anda.
curl https://DEFAULT_HOSTNAME/hello

Contoh: 

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

Tindakan ini akan menghasilkan error berikut:

UNAUTHENTICATED: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.

Sekarang, masukkan perintah curl berikut dengan:

  • DEFAULT_HOSTNAME menentukan bagian nama host dari URL gateway yang di-deploy.
  • hello adalah jalur yang ditentukan dalam konfigurasi API Anda.
  • API_KEY menentukan kunci API yang Anda buat di langkah sebelumnya.
curl https://DEFAULT_HOSTNAME/hello?key=API_KEY

Sekarang Anda akan melihat Hello World! dalam respons dari API.

Selamat! Anda telah berhasil melindungi backend API dengan API Gateway. Sekarang Anda dapat mulai melakukan aktivasi klien API baru dengan membuat kunci API tambahan.

Pembersihan

Agar tidak menimbulkan tagihan pada akun Google Cloud Anda untuk resource yang digunakan dalam panduan memulai ini, Anda dapat:

Atau, Anda juga dapat menghapus project Google Cloud yang digunakan untuk tutorial ini.

Langkah selanjutnya