Mengamankan traffic ke layanan dengan gcloud CLI

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

Ikuti langkah-langkah di bawah ini untuk men-deploy API baru guna mengakses layanan backend di Cloud Functions menggunakan Google Cloud CLI. Panduan memulai ini juga menjelaskan cara menggunakan kunci API untuk melindungi backend Anda dari akses yang tidak sah.

Sebelum memulai

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

    Buka halaman Dashboard

  2. Pastikan penagihan diaktifkan untuk project Anda.

    Pelajari cara mengaktifkan penagihan

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

    Mendownload gcloud CLI

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

Gateway API 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

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

/**
 * 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 Cloud Functions dan men-deploy layanan backend Cloud Function.

Membuat API

Sekarang Anda siap untuk membuat API di API Gateway.

  1. Masukkan perintah berikut, dengan kondisi:

    • API_ID menentukan nama API Anda. Lihat persyaratan ID API untuk 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 akan 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'

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

Membuat konfigurasi API

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

Anda dapat membuat konfigurasi API menggunakan spesifikasi OpenAPI yang berisi anotasi khusus untuk menentukan perilaku Gateway API yang diinginkan. Spesifikasi OpenAPI yang digunakan untuk panduan memulai ini berisi petunjuk pemilihan rute ke backend Cloud Function 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 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 GCP dari fungsi yang di-deploy dan PROJECT_ID dengan nama project Google Cloud Anda.

  4. Masukkan perintah berikut, dengan kondisi:

    • 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 bagi 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 diterapkan ke sistem downstream. Pembuatan konfigurasi API yang kompleks dapat memerlukan waktu hingga sepuluh menit agar 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 menunjukkan detail konfigurasi API Anda, termasuk nama dan status, seperti yang ditunjukkan pada contoh di bawah:

    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 pada gateway. Men-deploy konfigurasi API pada gateway 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 Gateway API:

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 akan 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'

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

Menguji deployment API Anda

Sekarang Anda dapat mengirim permintaan ke API menggunakan URL yang dihasilkan setelah deployment gateway Anda.

Masukkan perintah curl berikut, dengan kondisi:

  • DEFAULT_HOSTNAME menentukan bagian nama host URL gateway yang Anda deploy.
  • hello adalah jalur yang ditetapkan 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 Gateway API.

Mengamankan akses dengan menggunakan kunci API

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

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

Untuk mengamankan akses ke gateway Anda menggunakan kunci API:

  1. Mengaktifkan dukungan kunci API untuk layanan Anda. Masukkan perintah berikut, dengan kondisi:
    • MANAGED_SERVICE_NAME menentukan nama layanan terkelola yang dibuat saat Anda men-deploy API. 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
    Contoh: 
    gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
  2. Ubah spesifikasi OpenAPI yang digunakan untuk membuat konfigurasi API guna menyertakan petunjuk untuk menerapkan kebijakan keamanan validasi kunci API pada semua traffic. Tambahkan jenis security dan securityDefinitions seperti yang ditunjukkan di bawah ini: 
      # 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 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 dimodifikasi 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
    Contoh: 
    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 mengupdate 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
    Contoh: 
    gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1 --project=my-project

Menguji kunci API Anda

Setelah Anda membuat dan men-deploy API yang dimodifikasi, coba buat permintaan terhadap API tersebut.

Masukkan perintah curl berikut, dengan kondisi:

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

Contoh: 

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

Hal 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 di mana:

  • DEFAULT_HOSTNAME menentukan bagian nama host URL gateway yang Anda deploy.
  • hello adalah jalur yang ditetapkan 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 Anda.

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

Pembersihan

Agar tidak menimbulkan biaya 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