Menerima peristiwa menggunakan pesan Pub/Sub (Terraform)

Menerima peristiwa menggunakan pesan Pub/Sub (Terraform)

Standard

Panduan memulai cepat ini menunjukkan cara menggunakan Terraform untuk membuat pemicu Eventarc yang menerima peristiwa langsung dari Pub/Sub dan merutekan peristiwa ke layanan Cloud Run. Untuk mengetahui informasi selengkapnya tentang cara menggunakan Terraform untuk membuat pemicu Eventarc, lihat Membuat pemicu menggunakan Terraform.

Dalam panduan memulai ini, Anda akan melakukan hal berikut:

1. Bersiap untuk men-deploy Terraform.

2. Tentukan konfigurasi Terraform yang melakukan hal berikut:

   1. Mengaktifkan API
   2. Membuat akun layanan.
   3. Buat topik Pub/Sub sebagai penyedia peristiwa.
   4. Men-deploy layanan ke Cloud Run sebagai tujuan peristiwa.
   5. Buat pemicu Eventarc.

3. Terapkan konfigurasi Terraform Anda.

Dengan begitu, Anda dapat membuat peristiwa dengan memublikasikan pesan ke topik Pub/Sub. Pemicu Eventarc merutekan pesan ke layanan penerima peristiwa yang di-deploy di Cloud Run, dan layanan mencatat pesan peristiwa, sehingga memberi Anda contoh langsung arsitektur berbasis peristiwa.

Sebelum memulai

Batasan keamanan yang ditentukan oleh organisasi mungkin mencegah Anda menyelesaikan langkah-langkah berikut. Untuk mengetahui informasi pemecahan masalah, lihat Mengembangkan aplikasi di lingkungan Google Cloud yang terbatas.

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan Cloud Resource Manager dan Identity and Access Management (IAM) API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

Jika Anda menggunakan shell lokal, buat kredensial autentikasi lokal untuk akun pengguna Anda:

gcloud auth application-default login

Anda tidak perlu melakukan langkah ini jika menggunakan Cloud Shell.

Jika error autentikasi ditampilkan, dan Anda menggunakan penyedia identitas (IdP) eksternal, konfirmasi bahwa Anda telah login ke gcloud CLI dengan identitas gabungan Anda.

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan Cloud Resource Manager dan Identity and Access Management (IAM) API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

Jika Anda menggunakan shell lokal, buat kredensial autentikasi lokal untuk akun pengguna Anda:

gcloud auth application-default login

Anda tidak perlu melakukan langkah ini jika menggunakan Cloud Shell.

Jika error autentikasi ditampilkan, dan Anda menggunakan penyedia identitas (IdP) eksternal, konfirmasi bahwa Anda telah login ke gcloud CLI dengan identitas gabungan Anda.

1. Jika Anda menggunakan project yang sudah ada untuk panduan ini, pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini. Jika berhasil membuat project baru, berarti Anda sudah memiliki izin yang diperlukan.

   Izin yang diperlukan

   Untuk mendapatkan izin yang Anda perlukan untuk menyelesaikan panduan memulai cepat ini, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

   • Admin Cloud Run (roles/run.admin)
   • Eventarc Admin (roles/eventarc.admin)
   • Logs View Accessor (roles/logging.viewAccessor)
   • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
   • Pub/Sub Publisher (roles/pubsub.publisher)
   • Service Account Admin (roles/iam.serviceAccountAdmin)
   • Service Account User (roles/iam.serviceAccountUser)

   Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

   Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Bersiap untuk men-deploy Terraform

Sebelum men-deploy resource Terraform, Anda harus membuat file konfigurasi Terraform. File konfigurasi Terraform memungkinkan Anda menentukan status akhir pilihan untuk infrastruktur menggunakan sintaksis Terraform.

1. Jika Anda menggunakan shell lokal, instal Terraform.

   Terraform sudah terintegrasi ke dalam lingkungan Cloud Shell dan Anda dapat menggunakan Cloud Shell untuk men-deploy resource Terraform tanpa harus menginstal Terraform.

2. Di Cloud Shell atau shell lokal, tetapkan project Google Cloud default tempat Anda ingin menerapkan konfigurasi Terraform. Anda hanya perlu menjalankan perintah ini sekali per project, dan dapat dijalankan di direktori mana pun:

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Ganti PROJECT_ID dengan ID project Google Cloud Anda.

   Perhatikan bahwa variabel lingkungan akan diganti jika Anda menetapkan nilai eksplisit dalam file konfigurasi Terraform.

3. Setiap file konfigurasi Terraform harus memiliki direktorinya sendiri (juga disebut modul root). Buat direktori dan file baru di dalam direktori tersebut:

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

   Ganti DIRECTORY dengan nama direktori Terraform Anda.

   Nama file harus memiliki ekstensi .tf—misalnya, dalam panduan memulai ini, file konfigurasi adalah main.tf.

Tentukan konfigurasi Terraform Anda

Salin cuplikan kode Terraform berikut ke dalam file main.tf Anda. Atau, untuk menyalin seluruh contoh kode dari GitHub, di pojok kanan atas cuplikan kode, klik > Lihat di GitHub.

Mengaktifkan API

Untuk mengaktifkan API yang diperlukan untuk menerapkan konfigurasi Terraform, gunakan resource Terraform google_project_service:

# Enable Cloud Run API
resource "google_project_service" "run" {
  service            = "run.googleapis.com"
  disable_on_destroy = false
}

# Enable Eventarc API
resource "google_project_service" "eventarc" {
  service            = "eventarc.googleapis.com"
  disable_on_destroy = false
}

# Enable Pub/Sub API
resource "google_project_service" "pubsub" {
  service            = "pubsub.googleapis.com"
  disable_on_destroy = false
}

Membuat akun layanan

Setiap pemicu Eventarc dikaitkan dengan akun layanan IAM. Untuk membuat akun layanan khusus untuk tujuan pengujian, gunakan resource Terraform google_service_account:

# Create a dedicated service account
resource "google_service_account" "eventarc" {
  account_id   = "eventarc-trigger-sa"
  display_name = "Eventarc trigger service account"
}

Jika Anda mengaktifkan agen layanan Pub/Sub pada atau sebelum 8 April 2021, berikan peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator) kepada agen layanan.

resource "google_project_iam_member" "tokencreator" {
  project  = data.google_project.project.id
  role     = "roles/iam.serviceAccountTokenCreator"
  member   = "serviceAccount:service-${data.google_project.project.number}@gcp-sa-pubsub.iam.gserviceaccount.com"
}

Membuat topik Pub/Sub sebagai penyedia peristiwa

Untuk membuat topik Pub/Sub, gunakan resource Terraform google_pubsub_topic. Untuk memberikan peran Pub/Sub Publisher (roles/pubsub.publisher) kepada akun layanan Anda di tingkat topik, gunakan resource Terraform google_pubsub_topic_iam_member:

# Create a Pub/Sub topic
resource "google_pubsub_topic" "default" {
  name = "pubsub_topic"
}

# Grant permission to publish messages to a Pub/Sub topic
resource "google_pubsub_topic_iam_member" "pubsubpublisher" {
  project    = google_pubsub_topic.default.project
  topic      = google_pubsub_topic.default.name
  member     = "serviceAccount:${google_service_account.eventarc.email}"
  role       = "roles/pubsub.publisher"
  depends_on = [google_pubsub_topic.default]
}

Men-deploy penerima peristiwa ke Cloud Run

Untuk membuat layanan Cloud Run sebagai tujuan peristiwa, gunakan resource Terraform google_cloud_run_v2_service. Untuk memberikan peran Cloud Run Invoker (roles/run.invoker) ke akun layanan Anda di tingkat layanan, gunakan resource Terraform google_cloud_run_v2_service_iam_member:

# Deploy a Cloud Run service
resource "google_cloud_run_v2_service" "default" {
  name     = "hello-events"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # This sample container listens to HTTP requests and logs received events
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    service_account = google_service_account.eventarc.email
  }

  depends_on = [google_project_service.run]
}

# Grant permission to invoke Cloud Run services
resource "google_cloud_run_v2_service_iam_member" "runinvoker" {
  project    = google_cloud_run_v2_service.default.project
  location   = google_cloud_run_v2_service.default.location
  name       = google_cloud_run_v2_service.default.name
  role       = "roles/run.invoker"
  member     = "serviceAccount:${google_service_account.eventarc.email}"
  depends_on = [google_cloud_run_v2_service.default]
}

Membuat pemicu Eventarc

Untuk membuat pemicu Eventarc yang memproses pesan Pub/Sub, gunakan resource Terraform google_eventarc_trigger:

# Create an Eventarc trigger, routing Pub/Sub events to Cloud Run
resource "google_eventarc_trigger" "default" {
  name     = "trigger-pubsub-cloudrun-tf"
  location = google_cloud_run_v2_service.default.location

  # Capture messages published to a Pub/Sub topic
  matching_criteria {
    attribute = "type"
    value     = "google.cloud.pubsub.topic.v1.messagePublished"
  }

  # Send events to Cloud Run
  destination {
    cloud_run_service {
      service = google_cloud_run_v2_service.default.name
      region  = google_cloud_run_v2_service.default.location
    }
  }

  transport {
    pubsub {
      topic = google_pubsub_topic.default.id
    }
  }

  service_account = google_service_account.eventarc.email
  depends_on = [
    google_project_service.eventarc,
    google_pubsub_topic_iam_member.pubsubpublisher
  ]
}

Catatan: Meskipun pemicu Anda langsung dibuat, diperlukan waktu hingga dua menit agar pemicu berfungsi sepenuhnya.

Menerapkan konfigurasi Terraform

Gunakan Terraform CLI untuk menyediakan infrastruktur berdasarkan file konfigurasi. Untuk mengetahui informasi selengkapnya, lihat Perintah Terraform dasar.

1. Lakukan inisialisasi Terraform. Anda hanya perlu melakukannya sekali per direktori.

   terraform init

   Secara opsional, untuk menggunakan versi penyedia Google terbaru, sertakan opsi -upgrade:

   terraform init -upgrade

2. Tinjau konfigurasi dan pastikan resource yang akan dibuat atau diupdate oleh Terraform sesuai yang Anda inginkan:

   terraform plan

   Perbaiki konfigurasi jika diperlukan.

3. Terapkan konfigurasi Terraform dengan menjalankan perintah berikut dan memasukkan yes pada prompt:

   terraform apply

   Biasanya, Anda menerapkan seluruh konfigurasi sekaligus. Namun, Anda juga dapat menargetkan resource tertentu. Contoh:

   terraform apply -target="google_eventarc_trigger.default"

   Setelah mengaktifkan API, mungkin perlu waktu beberapa menit agar tindakan tersebut diterapkan sebelum Anda dapat men-deploy resource lebih lanjut. Jika Anda mengalami masalah, coba terapkan konfigurasi Terraform lagi.

   Tunggu hingga Terraform menampilkan pesan "Apply complete!".

Memverifikasi pembuatan resource

1. Pastikan layanan Cloud Run telah dibuat:

   gcloud run services list --region us-central1
   

   Outputnya akan mirip dengan berikut ini:

   SERVICE: hello-events
   REGION: us-central1
   URL: https://hello-events-13335919645.us-central1.run.app
   LAST DEPLOYED BY: ...
   LAST DEPLOYED AT: 2024-12-16T15:00:52.606160Z
   

2. Pastikan pemicu Eventarc telah dibuat:

   gcloud eventarc triggers list --location us-central1
   

   Outputnya akan mirip dengan berikut ini:

   NAME: trigger-pubsub-cloudrun-tf
   TYPE: google.cloud.pubsub.topic.v1.messagePublished
   DESTINATION: Cloud Run service: hello-events
   ACTIVE: Yes
   LOCATION: us-central1
   

Membuat dan melihat peristiwa topik Pub/Sub

Anda dapat membuat peristiwa dengan memublikasikan pesan ke topik Pub/Sub. Pemicu Eventarc merutekan pesan ke layanan penerima peristiwa yang di-deploy di Cloud Run dan layanan mencatat pesan peristiwa.

1. Cari dan tetapkan topik Pub/Sub sebagai variabel lingkungan:

   gcloud config set eventarc/location us-central1
   export RUN_TOPIC=$(gcloud eventarc triggers describe trigger-pubsub-cloudrun-tf \
       --format='value(transport.pubsub.topic)')
   

2. Untuk membuat peristiwa, publikasikan pesan ke topik Pub/Sub:

   gcloud pubsub topics publish $RUN_TOPIC --message "Hello World!"
   

   Peristiwa dirutekan ke layanan Cloud Run, yang mencatat pesan peristiwa.

3. Memfilter entri log yang dibuat oleh layanan Anda:

   gcloud logging read 'jsonPayload.message: "Received event of type google.cloud.pubsub.topic.v1.messagePublished"'
   

4. Cari entri log yang mirip dengan berikut ini:

   jsonPayload:
   ...
   message: 'Received event of type google.cloud.pubsub.topic.v1.messagePublished.
       Event data: Hello World!'
   

   Catatan: Jika Anda tidak melihat entri log, tunggu beberapa menit dan coba perintah gcloud logging read lagi.

Anda telah berhasil menggunakan Terraform untuk men-deploy layanan penerima peristiwa ke Cloud Run dan membuat pemicu Eventarc. Setelah membuat peristiwa dari Pub/Sub, Anda dapat melihatnya di log Cloud Run.

Pembersihan

Setelah menyelesaikan tugas yang dijelaskan dalam panduan memulai ini, Anda dapat menghindari penagihan berkelanjutan dengan menghapus resource yang Anda buat.

Hapus resource yang sebelumnya diterapkan dengan konfigurasi Terraform Anda dengan menjalankan perintah berikut dan memasukkan yes pada prompt:

terraform destroy

Atau, Anda dapat menghapus project Google Cloud untuk menghindari tagihan. Menghapus project Google Cloud akan menghentikan penagihan untuk semua resource yang digunakan dalam project tersebut.

Perhatian: Menghapus project memiliki efek berikut:

• Semua hal dalam project akan dihapus. Jika Anda menggunakan project yang ada untuk mengerjakan tugas di dokumen ini, saat Anda menghapusnya, pekerjaan lain dalam project tersebut juga akan dihapus.
• Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin juga membuat project ID kustom yang masih ingin digunakan pada masa mendatang. Agar tidak kehilangan URL yang menggunakan project ID tersebut, seperti URL appspot.com, hapus resource yang dipilih di dalam project, bukan menghapus seluruh project.

Menghapus Google Cloud project:

gcloud projects delete PROJECT_ID

Jika Anda berencana mempelajari beberapa tutorial dan panduan memulai, menggunakan kembali project dapat membantu Anda agar tidak melampaui batas kuota project.

Langkah berikutnya

• Mengembangkan layanan untuk Cloud Run
• Dokumentasi Google Cloud Terraform