Menggunakan Eventarc untuk menerima peristiwa dari Cloud Storage


Tutorial ini menunjukkan cara men-deploy aplikasi dalam container menggunakan layanan Cloud Run terautentikasi yang menerima peristiwa melalui Eventarc.

Dengan menentukan filter untuk pemicu Eventarc, Anda dapat mengonfigurasi pemilihan rute peristiwa, termasuk sumber peristiwa dan target peristiwa. Dalam hal ini, update pada bucket Cloud Storage akan memicu peristiwa tersebut dan permintaan akan dikirim ke layanan Cloud Run Anda dalam bentuk permintaan HTTP.

Tujuan

Dalam tutorial ini, Anda akan:

  1. Membuat bucket Cloud Storage untuk menjadi sumber peristiwa.

  2. Men-deploy layanan penerima peristiwa ke Cloud Run yang memerlukan pemanggilan yang diautentikasi.

  3. Membuat pemicu Eventarc yang merutekan peristiwa dari bucket Cloud Storage ke layanan Cloud Run.

  4. Membuat peristiwa dengan mengupload file ke bucket Cloud Storage dan menampilkan peristiwa tersebut di log Cloud Run.

Biaya

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih berikut:

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga. Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

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.

    • 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. Install the Google Cloud CLI.
  7. To initialize the gcloud CLI, run the following command:

    gcloud init
  8. Create or select a Google Cloud 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.

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

  10. Jika tidak menggunakan Cloud Shell, update komponen Google Cloud CLI dan login menggunakan akun Anda:
    gcloud components update
    gcloud auth login
  11. Aktifkan API:
    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        storage.googleapis.com
  12. Tetapkan variabel konfigurasi yang digunakan dalam tutorial ini:
    export REGION=us-central1
    gcloud config set run/region ${REGION}
    gcloud config set run/platform managed
    gcloud config set eventarc/location ${REGION}
  13. Anda atau administrator harus memberikan peran IAM berikut kepada akun deployer, identitas pemicu, dan secara opsional, agen layanan Pub/Sub.

    Peran yang diperlukan untuk akun deployer

    1. 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). Untuk mengetahui informasi selengkapnya, lihat halaman eran dan izin untuk tujuan peristiwa Anda.

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

      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.

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

    Peran yang diperlukan untuk identitas pemicu

    1. Catat akun layanan default Compute Engine karena Anda akan melampirkan akun tersebut ke pemicu Eventarc untuk merepresentasikan identitas pemicu untuk tujuan pengujian. Akun layanan ini dibuat secara otomatis setelah mengaktifkan atau menggunakan layanan Google Cloud yang menggunakan Compute Engine, dan dengan format email berikut:

      PROJECT_NUMBER-compute@developer.gserviceaccount.com

      Ganti PROJECT_NUMBER dengan Google Cloud nomor 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)'

      Untuk lingkungan produksi, sebaiknya buat akun layanan baru dan berikan satu atau beberapa peran IAM yang berisi izin minimum yang diperlukan dan ikuti prinsip hak istimewa terendah.

    2. Secara default, layanan Cloud Run hanya dapat dipanggil oleh Project Owner, Project Editor, Cloud Run Admin dan Invoker. Anda dapat mengontrol akses per layanan; namun, untuk tujuan pengujian, berikan peran Cloud Run Invoker (run.invoker) di project Google Cloud ke akun layanan Compute Engine. Peran ini akan memberikan peran tersebut di semua layanan dan tugas Cloud Run dalam suatu project.
      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
          --role=roles/run.invoker

      Perhatikan bahwa pemicu akan berhasil dibuat dan diaktifkan jika Anda membuat pemicu untuk layanan Cloud Run yang diautentikasi tanpa memberikan peran Cloud Run Namun, pemicu tidak akan berfungsi seperti yang diharapkan dan pesan yang mirip dengan berikut ini akan muncul di log:

      The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
    3. Berikan Peran Eventarc Event Receiver (roles/eventarc.eventReceiver) pada project ke akun layanan default Compute Engine agar pemicu Eventarc dapat menerima peristiwa dari penyedia peristiwa.
      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
          --role=roles/eventarc.eventReceiver

    Peran opsional untuk agen layanan Pub/Sub

    • Jika Anda mengaktifkan agen layanan Cloud Pub/Sub pada atau sebelum 8 April 2021, untuk mendukung permintaan push Pub/Sub yang diautentikasi, berikan peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator) ke agen layanan. Jika tidak, peran ini akan diberikan secara default:
      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
          --role=roles/iam.serviceAccountTokenCreator

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.

Membuat bucket Cloud Storage

Membuat bucket Cloud Storage untuk digunakan sebagai sumber peristiwa:

gcloud storage buckets create gs://PROJECT_ID-bucket/ --location=us-central1

Setelah sumber peristiwa dibuat, Anda dapat men-deploy layanan penerima peristiwa di Cloud Run.

Men-deploy penerima peristiwa ke Cloud Run

Men-deploy layanan Cloud Run yang menerima dan mencatat peristiwa ke dalam log.

  1. Buat clone repositori GitHub:

    Node.js

    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

    Atau, Anda dapat mendownload contoh dalam file ZIP dan mengekstraknya.

    Python

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

    Atau, Anda dapat mendownload contoh dalam file ZIP dan mengekstraknya.

    Go

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

    Atau, Anda dapat mendownload contoh dalam file ZIP dan mengekstraknya.

    Java

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

    Atau, Anda dapat mendownload contoh sebagai file ZIP dan mengekstraknya.

    C#

    git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git

    Atau, Anda dapat mendownload contoh sebagai file ZIP dan mengekstraknya.

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

    Node.js

    cd nodejs-docs-samples/eventarc/audit-storage/

    Python

    cd python-docs-samples/eventarc/audit-storage/

    Go

    cd golang-samples/eventarc/audit_storage/

    Java

    cd java-docs-samples/eventarc/audit-storage/

    C#

    cd dotnet-docs-samples/eventarc/audit-storage/
  3. Build container untuk layanan Cloud Run:

    export PROJECT_ID=$(gcloud config get-value project)
    export SERVICE_NAME=helloworld-events
    gcloud builds submit --tag $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1
  4. Men-deploy image container ke Cloud Run:

    gcloud run deploy ${SERVICE_NAME} \
        --image $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1
  5. Pada perintah Allow unauthenticated invocations to helloworld-events (y/N)?, respons n dengan "No".

Jika Anda melihat URL layanan Cloud Run, berarti deployment telah selesai.

Membuat pemicu Eventarc

Pemicu Eventarc mengirimkan peristiwa dari bucket Cloud Storage ke helloworld-events di layanan Cloud Run. Layanan memerlukan autentikasi, dan peristiwa harus dipicu oleh pemanggil yang memiliki akun layanan dengan peran dan izin IAM yang diperlukan untuk menggunakan resource.

  1. Buat pemicu yang memfilter peristiwa Cloud Storage:

    gcloud eventarc triggers create ${SERVICE_NAME} \
        --destination-run-service=${SERVICE_NAME} \
        --destination-run-region=${REGION} \
        --location=${REGION} \
        --event-filters="type=google.cloud.storage.object.v1.finalized" \
        --event-filters="bucket=PROJECT_ID-bucket" \
        --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Tindakan ini akan membuat pemicu yang disebut helloworld-events.

    Perhatikan bahwa saat membuat pemicu Eventarc untuk pertama kalinya dalam project Google Cloud , mungkin akan ada penundaan dalam penyediaan agen layanan Eventarc. Masalah ini biasanya dapat diatasi dengan mencoba membuat ulang pemicu. Untuk informasi selengkapnya, lihat Error izin ditolak.

  2. Konfirmasi bahwa pemicu telah berhasil dibuat. Perhatikan bahwa meskipun pemicu Anda langsung dibuat, diperlukan waktu hingga dua menit agar pemicu berfungsi sepenuhnya.

    gcloud eventarc triggers list --location=${REGION}

    Output-nya akan mirip dengan berikut ini:

    NAME: helloworld-events
    TYPE: google.cloud.storage.object.v1.finalized
    DESTINATION: Cloud Run service: helloworld-events
    ACTIVE: Yes
    

Membuat dan melihat peristiwa

Upload file teks ke bucket Cloud Storage untuk membuat peristiwa yang dirutekan ke layanan Cloud Run. Layanan Cloud Run mencatat peristiwa ke dalam log layanan.

  1. Untuk membuat peristiwa:

    Upload file teks ke Cloud Storage:

     echo "Hello World" > random.txt
     gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt
    

    Hasil upload ini akan membuat peristiwa dan layanan Cloud Run akan mencatat pesan peristiwa tersebut ke dalam log.

  2. Untuk melihat entri log:

    1. Filter entri log dan tampilkan output dalam format JSON:

      gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
      
    2. Cari entri log yang mirip dengan:

      "textPayload": "Detected change in Cloud Storage bucket: objects/random.txt"
      

Log mungkin memerlukan waktu beberapa saat untuk ditampilkan. Jika Anda tidak melihatnya, periksa lagi setelah satu menit.

Anda telah berhasil men-deploy layanan penerima peristiwa ke Cloud Run, membuat pemicu Eventarc, membuat peristiwa dari Cloud Storage, dan menampilkannya di log Cloud Run.

Pembersihan

Jika Anda membuat project baru untuk tutorial ini, hapus project tersebut. Jika Anda menggunakan project yang ada dan ingin mempertahankannya tanpa perubahan yang ditambahkan dalam tutorial ini, hapus resource yang dibuat untuk tutorial.

Menghapus project

Cara termudah untuk menghilangkan penagihan adalah dengan menghapus project yang Anda buat untuk tutorial.

Untuk menghapus project:

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Menghapus referensi tutorial

  1. Hapus layanan Cloud Run yang Anda deploy dalam tutorial ini:

    gcloud run services delete SERVICE_NAME

    Dengan SERVICE_NAME adalah nama layanan pilihan Anda.

    Anda juga dapat menghapus layanan Cloud Run dari Google Cloud Console.

  2. Hapus konfigurasi default gcloud CLI yang Anda tambahkan selama penyiapan tutorial.

    Contoh:

    gcloud config unset run/region

    atau

    gcloud config unset project

  3. Hapus resource Google Cloud lain yang dibuat dalam tutorial ini:

    • Hapus pemicu Eventarc:
      gcloud eventarc triggers delete TRIGGER_NAME
      
      Ganti TRIGGER_NAME dengan nama pemicu Anda.

Langkah berikutnya