Memublikasikan dan menerima peristiwa dengan membuat bus dan pendaftaran

Memublikasikan dan menerima peristiwa dengan membuat bus dan pendaftaran

Lanjutan

Preview — Eventarc Advanced

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Panduan memulai ini menunjukkan cara memublikasikan dan menerima pesan peristiwa dengan membuat bus Eventarc Advanced dan pendaftaran di project Google CloudAnda.

Bus memungkinkan Anda memusatkan alur pesan melalui sistem, dan bertindak sebagai router. Peristiwa ini menerima peristiwa dari sumber pesan atau dipublikasikan oleh penyedia, dan mengevaluasinya sesuai dengan pendaftaran.

Pendaftaran mengidentifikasi langganan ke bus tertentu, dan menentukan kriteria pencocokan untuk pesan, sehingga pesan tersebut dirutekan sesuai dengan satu atau beberapa tujuan.

Dalam panduan memulai ini, Anda akan:

1. Buat subnet dan aktifkan Akses Google Pribadi.

2. Buat lampiran jaringan.

3. Men-deploy layanan penerima peristiwa ke Cloud Run.

4. Buat bus Eventarc Advanced.

5. Buat pendaftaran Eventarc Advanced.

6. Memublikasikan pesan peristiwa ke bus.

7. Lihat data peristiwa di log Cloud Run.

Anda dapat menyelesaikan panduan memulai ini menggunakan Google Cloud CLI.

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.

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs:

   gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

7. Install the Google Cloud CLI.

8. To initialize the gcloud CLI, run the following command:

   gcloud init

9. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

10. Make sure that billing is enabled for your Google Cloud project.

11. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs:

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

12. Perbarui komponen gcloud:

    gcloud components update

13. Login menggunakan akun Anda:

    gcloud auth login

14. Tetapkan variabel konfigurasi yang digunakan dalam panduan memulai ini:

    REGION=REGION

    Ganti REGION dengan lokasi yang didukung untuk bus.

15. Jika Anda adalah project creator, Anda diberi peran Pemilik dasar (roles/owner). Secara default, peran Identity and Access Management (IAM) ini mencakup izin yang diperlukan untuk akses penuh ke sebagian besar resource Google Cloud dan Anda dapat melewati langkah ini.

    Jika Anda bukan project creator, izin yang diperlukan harus diberikan pada project kepada akun utama yang sesuai. Misalnya, akun utama dapat berupa Akun Google (untuk pengguna akhir) atau akun layanan (untuk aplikasi dan workload komputasi).

    Perhatikan bahwa secara default, izin Cloud Build mencakup izin untuk mengupload dan mendownload artefak Artifact Registry.

    Izin yang diperlukan

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

    • Editor Cloud Build (roles/cloudbuild.builds.editor)
    • Cloud Run Admin (roles/run.admin)
    • Developer Eventarc (roles/eventarc.developer)
    • Eventarc Message Bus Admin (roles/eventarc.messageBusAdmin)
    • Logs View Accessor (roles/logging.viewAccessor)
    • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
    • Service Account Admin (roles/iam.serviceAccountAdmin)
    • Service Account User (roles/iam.serviceAccountUser)
    • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)

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

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

16. Berikan peran berikut pada project ke akun layanan default Compute Engine. Peran ini diperlukan saat mem-build dan men-deploy image container:
    • Artifact Registry Writer: untuk mengupload artefak Artifact Registry
    • Logs Writer: untuk menulis log ke Cloud Logging
    • Pengguna Objek Penyimpanan: untuk mengakses objek Cloud Storage

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/artifactregistry.writer
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/logging.logWriter
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/storage.objectUser

    Ganti PROJECT_NUMBER dengan Google Cloudnomor project Anda. Anda dapat menemukan nomor project di halaman Selamat Datang pada Konsol Google Cloud atau dengan menjalankan perintah berikut:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

17. Secara default, hanya Project Owner, Project Editor, dan Cloud Run Admin dan Invoker yang dapat memanggil layanan Cloud Run. Untuk menyiapkan autentikasi, berikan peran Cloud Run Invoker (run.invoker) di project Google Cloud Anda ke akun layanan:
    1. Membuat akun layanan. Untuk tujuan pengujian, Anda akan melampirkan akun layanan ini ke pipeline Eventarc Advanced untuk merepresentasikan identitas pipeline.

       gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

       Ganti SERVICE_ACCOUNT_NAME dengan nama untuk akun layanan Anda.
    2. Berikan peran IAM roles/run.invoker ke akun layanan:

       gcloud projects add-iam-policy-binding PROJECT_ID \
           --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
           --role=roles/run.invoker

    Perhatikan bahwa Anda dapat mengonfigurasi siapa saja yang dapat mengakses layanan Cloud Run Anda dengan salah satu cara berikut:

    • Berikan izin untuk memilih akun atau grup layanan yang akan mengizinkan akses ke layanan tersebut. Semua permintaan harus memiliki header Otorisasi HTTP yang berisi token OpenID Connect yang ditandatangani oleh Google untuk salah satu akun layanan yang diberikan otorisasi. Ini adalah cara akses dikonfigurasi dalam panduan memulai ini.
    • Berikan izin ke allUsers untuk mengizinkan akses tanpa autentikasi.

    Untuk mengetahui informasi selengkapnya, lihat Kontrol akses untuk Cloud Run.

Membuat subnet dan mengaktifkan Akses Google Pribadi

Kecuali jika Anda membuat kebijakan organisasi yang melarang beberapa jaringan VPC, project Google Cloud baru dimulai dengan jaringan Virtual Private Cloud (VPC) default (jaringan VPC mode otomatis) yang memiliki satu subnetwork (subnet) di setiap region. Subnet memiliki rentang alamat IP yang terkait dengannya.

Karena Anda merutekan pesan ke tujuan Cloud Run menggunakan alamat DNS, Anda harus mengaktifkan Akses Google Pribadi di subnet yang digunakan dalam lampiran jaringan. Jika tidak, alamat DNS tidak dapat di-resolve. Untuk mengetahui informasi selengkapnya tentang jaringan pribadi dan Cloud Run, lihat Menerima permintaan dari jaringan VPC.

Buat subnet di jaringan default project Anda dan gunakan flag --enable-private-ip-google-access untuk mengaktifkan Akses Google Pribadi:

gcloud compute networks subnets create SUBNET_NAME \
    --network=default \
    --range=10.8.0.0/24 \
    --region=$REGION \
    --enable-private-ip-google-access

Ganti SUBNET_NAME dengan nama subnet Anda, misalnya my-subnet.

Rentang IP subnet harus unik dan tidak tumpang-tindih dalam jaringan VPC dan jaringan VPC yang di-peering. Untuk mengetahui informasi selengkapnya tentang jenis subnet dan rentang subnet yang valid, lihat Subnet.

Membuat lampiran jaringan

Lampiran jaringan adalah resource yang memungkinkan jaringan VPC produsen memulai koneksi ke jaringan VPC konsumen. Untuk memublikasikan peristiwa, Eventarc Advanced menggunakan lampiran jaringan untuk membuat koneksi ke endpoint yang dihosting di jaringan VPC.

Buat lampiran jaringan di jaringan dan region yang sama yang berisi endpoint tujuan peristiwa, dan yang otomatis menerima koneksi dari antarmuka Private Service Connect mana pun yang merujuk ke lampiran jaringan:

gcloud compute network-attachments create ATTACHMENT_NAME \
   --region=$REGION \
   --connection-preference=ACCEPT_AUTOMATIC \
   --subnets=SUBNET_NAME

Ganti ATTACHMENT_NAME dengan nama lampiran jaringan Anda, misalnya, my-network-attachment.

Membuat repositori standar Artifact Registry

Buat repositori standar Artifact Registry untuk menyimpan image container Anda.

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Ganti REPOSITORY dengan nama unik untuk repositori Artifact Registry, misalnya my-repo.

Men-deploy layanan penerima peristiwa ke Cloud Run

Deploy layanan Cloud Run yang mencatat konten peristiwa ke dalam log. Layanan ini hanya dapat diakses dari jaringan VPC dalam project yang sama, dan URL layanan tidak dapat diakses secara langsung karena layanan hanya mengizinkan pemanggilan terautentikasi.

1. Buat clone repositori GitHub:

   git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

2. Ubah ke direktori yang memuat kode contoh Cloud Run:

   cd eventarc-samples/eventarc-advanced-quickstart/

3. Build image container Docker dan kirim image ke repositori Anda:

   gcloud builds submit \
       --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1

4. Men-deploy image container ke Cloud Run

   gcloud run deploy SERVICE_NAME \
       --image $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
       --platform managed \
       --ingress internal \
       --no-allow-unauthenticated \
       --region=$REGION

   Ganti SERVICE_NAME dengan nama layanan Anda, misalnya, my-service.

Jika Anda melihat URL layanan Cloud Run, berarti deployment telah selesai. Catat URL ini agar Anda dapat menggunakannya di langkah berikutnya.

Membuat bus Advanced Eventarc

Buat bus Eventarc Advanced di project Anda menggunakan perintah gcloud beta eventarc message-buses create:

gcloud beta eventarc message-buses create BUS_NAME \
    --location=$REGION

Ganti BUS_NAME dengan ID atau ID yang sepenuhnya memenuhi syarat dari bus Anda—misalnya, my-bus.

Catatan: Anda hanya dapat membuat satu bus per Google Cloud project.

Untuk informasi selengkapnya, lihat Membuat bus untuk merutekan pesan.

Membuat pendaftaran Eventarc Advanced

Pendaftaran menentukan pesan mana yang dirutekan ke tujuan. Fungsi ini juga menentukan pipeline yang akan digunakan untuk merutekan pesan. Pipeline digunakan untuk mengonfigurasi tujuan pesan peristiwa.

Untuk mengetahui informasi selengkapnya, lihat Membuat pendaftaran untuk menerima peristiwa.

Saat menggunakan gcloud CLI, Anda harus membuat pipeline terlebih dahulu, lalu membuat pendaftaran.

Catatan: Pembuatan pipeline mungkin memerlukan waktu lebih dari 10 menit.

1. Buat pipeline menggunakan perintah gcloud beta eventarc pipelines create:

   gcloud beta eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='CLOUD_RUN_SERVICE_URL',network_attachment=ATTACHMENT_NAME,google_oidc_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --location=$REGION

   Ganti kode berikut:

   • PIPELINE_NAME: ID pipeline atau nama yang sepenuhnya memenuhi syarat.
   • CLOUD_RUN_SERVICE_URL: URL layanan Cloud Run Anda yang sepenuhnya memenuhi syarat—misalnya, https://SERVICE_NAME-abcdef-uc.a.run.app. Ini adalah tujuan untuk pesan peristiwa Anda.

   Perhatikan bahwa kunci google_oidc_authentication_service_account menentukan email akun layanan yang digunakan untuk membuat token OIDC.

2. Buat pendaftaran menggunakan perintah gcloud beta eventarc enrollments create:

   gcloud beta eventarc enrollments create ENROLLMENT_NAME \
       --cel-match=MATCH_EXPRESSION \
       --destination-pipeline=PIPELINE_NAME \
       --message-bus=BUS_NAME \
       --message-bus-project=PROJECT_ID \
       --location=$REGION

   Ganti kode berikut:

   • ENROLLMENT_NAME: ID pendaftaran atau nama yang sepenuhnya memenuhi syarat.
   • MATCH_EXPRESSION: ekspresi yang cocok untuk enrolment ini menggunakan CEL—misalnya, "message.type == 'hello-world-type'".

Memublikasikan pesan peristiwa ke bus

Untuk memublikasikan pesan secara langsung ke bus, Anda dapat menggunakan perintah gcloud beta eventarc message-buses publish atau mengirim permintaan ke Eventarc Publishing REST API. Untuk informasi selengkapnya, lihat Memublikasikan peristiwa secara langsung.

Pesan harus dalam format CloudEvents yang merupakan spesifikasi untuk mendeskripsikan data peristiwa dengan cara yang umum. Elemen data adalah payload peristiwa Anda. JSON yang disusun dengan baik dapat dimasukkan ke kolom ini. Untuk informasi selengkapnya tentang atribut konteks CloudEvents, lihat Format peristiwa.

Berikut adalah contoh publikasi peristiwa secara langsung ke bus Eventarc Advanced:

Contoh 1

Anda dapat memublikasikan peristiwa ke bus menggunakan gcloud CLI dan --event-data serta flag atribut peristiwa lainnya:

gcloud beta eventarc message-buses publish BUS_NAME \
    --event-data='{"key": "hello-world-data"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

Contoh 2

Anda dapat memublikasikan peristiwa ke bus sebagai pesan JSON menggunakan gcloud CLI dan flag --json-message:

gcloud beta eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"key": "hello-world-data"}}'

Setelah memublikasikan peristiwa, Anda akan menerima pesan "Peristiwa berhasil dipublikasikan".

Melihat data peristiwa di log Cloud Run

Setelah memublikasikan peristiwa ke bus Eventarc Advanced, Anda dapat memeriksa log layanan Cloud Run untuk memverifikasi bahwa peristiwa diterima seperti yang diharapkan.

1. Filter entri log dan tampilkan output menggunakan perintah gcloud logging read:

   gcloud logging read 'textPayload: "hello-world-data"'
   

2. Cari entri log yang mirip dengan berikut ini:

   insertId: 670808e70002b5c6477709ae
   labels:
   instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
   logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
   receiveTimestamp: '2024-10-10T17:03:35.424659450Z'
   resource:
   labels:
   ...
   type: cloud_run_revision
   textPayload: "[2024-10-21 15:33:19,581] INFO in server: Body: b'{\"value\":\"hello-world-data\"\
     }'"
   timestamp: '2024-10-10T17:03:35.177606Z'
   

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

Anda telah berhasil membuat bus dan pendaftaran Eventarc Advanced, memublikasikan pesan peristiwa ke bus, dan memverifikasi hasil yang diharapkan dalam log layanan penerima peristiwa.

Pembersihan

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

1. Menghapus subnet VPC.

2. Menghapus lampiran jaringan VPC.

3. Menghapus repositori Artifact Registry.

4. Hapus layanan Cloud Run.

5. Hapus resource Eventarc Advanced:

   1. Menghapus pendaftaran.

   2. Menghapus pipeline.

   3. Menghapus bus.

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

Perhatian: Menghapus project memiliki efek berikut:

• Semua hal dalam project akan dihapus. Jika menggunakan project yang sudah ada untuk tugas dalam dokumen ini, saat Anda menghapusnya, pekerjaan lain yang telah Anda lakukan dalam project tersebut juga akan terhapus.
• Project ID kustom hilang. Saat membuat project ini, Anda mungkin telah membuat project ID kustom yang ingin digunakan di masa mendatang. Untuk mempertahankan URL yang menggunakan project ID, seperti URL appspot.com, hapus resource yang dipilih di dalam project, bukan menghapus seluruh project.

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

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Langkah berikutnya

• Memublikasikan peristiwa dari sumber Google
• Memublikasikan peristiwa secara langsung
• Mentransformasi peristiwa yang diterima
• Memformat peristiwa yang diterima