使用 Pub/Sub 訊息接收事件 (Terraform)

本快速入門說明如何使用 Terraform 建立 Eventarc 觸發事件，以便接收來自 Pub/Sub 的直接事件，並將事件路由至 Cloud Run 服務。如要進一步瞭解如何使用 Terraform 建立 Eventarc 觸發條件，請參閱「使用 Terraform 建立觸發條件」一文。

在本快速入門導覽課程中，您將執行以下操作：

  1. 準備部署 Terraform。

  2. 定義 Terraform 設定，執行下列操作：

    1. 啟用 API。
    2. 建立服務帳戶，並授予必要的身分與存取權管理 (IAM) 角色。
    3. 將服務部署至 Cloud Run 做為事件目的地。
    4. 建立 Pub/Sub 主題做為事件供應器。
    5. 建立 Eventarc 觸發條件。

  3. 套用 Terraform 設定。

  4. 將訊息發布至 Pub/Sub 主題，產生事件，並在 Cloud Run 記錄檔中查看該事件。

事前準備

貴機構定義的安全性限制，可能會導致您無法完成下列步驟。如需疑難排解資訊，請參閱「在受限的 Google Cloud 環境中開發應用程式」。

  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. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

  5. 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.

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

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  8. Install the Google Cloud CLI.

  9. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

  11. 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.

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

  13. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  14. 如果您是專案建立者，系統會授予您基本擁有者角色 (roles/owner)。根據預設，這個身分與存取權管理 (IAM) 角色會包含完整存取大多數 Google Cloud資源所需的權限，因此您可以略過這個步驟。

    如果您不是專案建立者，則必須將必要權限授予專案中的適當實體。舉例來說，主體可以是 Google 帳戶 (適用於使用者)，也可以是服務帳戶 (適用於應用程式和運算工作負載)。詳情請參閱活動目的地的角色和權限頁面。

    所需權限

    如要取得完成這份快速入門課程所需的權限，請要求管理員為您授予專案的下列 IAM 角色：

    如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

    您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

準備部署 Terraform

建立 Terraform 設定檔，準備部署 Terraform 資源。您可以使用 Terraform 語法，透過 Terraform 設定檔定義基礎架構的偏好最終狀態。

  1. 如果您使用本機殼層，請安裝及設定 Terraform。

    Terraform 已整合至 Cloud Shell 環境，您可以使用 Cloud Shell 部署 Terraform 資源，而無須安裝 Terraform。

  2. 在 Cloud Shell 或本機 Shell 中，設定要套用 Terraform 設定的預設 Google Cloud 專案。您只需為每個專案執行這個指令一次，而且可以在任何目錄中執行：

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    將 PROJECT_ID 替換為您的 Google Cloud 專案 ID。

請注意，如果您在 Terraform 設定檔中設定明確的值，系統會覆寫環境變數。

準備目錄

每個 Terraform 設定檔都必須有專屬的目錄 (也稱為「根模組」)。建立目錄，並在該目錄中建立新檔案：

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

檔案名稱必須包含 .tf 副檔名，例如在本快速入門課程中，檔案會稱為 main.tf。

定義 Terraform 設定

將下列 Terraform 程式碼片段複製到您新建立的 main.tf 檔案中。您也可以從 GitHub 複製程式碼。(在程式碼片段的右上角，依序點選 >「在 GitHub 上查看」)。

啟用 API

Terraform 範例通常會假設您已在Google Cloud 專案中啟用必要的 API。使用下列程式碼片段，啟用本快速入門所需的 API：

# 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
}

建立服務帳戶並設定存取權

每個 Eventarc 觸發事件都會與 IAM 服務帳戶建立關聯。如要完成這份快速入門，您必須將下列 IAM 角色授予使用者管理的服務帳戶：

使用下列程式碼片段建立專用服務帳戶，並授予該帳戶特定的 IAM 角色，以便管理事件：

# Used to retrieve project information later
data "google_project" "project" {}

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

# Grant permission to invoke Cloud Run services
resource "google_project_iam_member" "runinvoker" {
  project = data.google_project.project.id
  role    = "roles/run.invoker"
  member  = "serviceAccount:${google_service_account.eventarc.email}"
}

# Grant permission to publish messages to a Pub/Sub topic
resource "google_project_iam_member" "pubsubpublisher" {
  project = data.google_project.project.id
  member  = "serviceAccount:${google_service_account.eventarc.email}"
  role    = "roles/pubsub.publisher"
}

如果您是在 2021 年 4 月 8 日當天或之前啟用 Pub/Sub 服務代理，請將 服務帳戶憑證建立者角色 (roles/iam.serviceAccountTokenCreator) 授予服務代理。

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"
}

將事件接收器部署至 Cloud Run

使用 google_cloud_run_v2_service Terraform 資源，建立 Cloud Run 服務做為 Eventarc 觸發事件的事件目的地：

# 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 container will log received events
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    service_account = google_service_account.eventarc.email
  }

  depends_on = [google_project_service.run]
}

建立 Pub/Sub 主題做為事件供應器

使用 google_pubsub_topic Terraform 資源建立 Pub/Sub 主題：

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

建立 Eventarc 觸發條件

使用 google_eventarc_trigger Terraform 資源建立 Eventarc 觸發條件，以便監聽 Pub/Sub 訊息：

# 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_project_iam_member.pubsubpublisher
  ]
}

套用 Terraform

使用 Terraform CLI 根據設定檔佈建基礎架構。

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。

  1. 初始化 Terraform。這項操作只需對每個目錄執行一次。

    terraform init

    如要使用最新的 Google 供應器版本，請視需要加入 -upgrade 選項：

    terraform init -upgrade

  2. 檢查設定，確認 Terraform 將要建立或更新的資源符合您的預期：

    terraform plan

    視需要修正設定。

  3. 執行下列指令，並在提示訊息中輸入 yes，即可套用 Terraform 設定：

    terraform apply

    通常，您會一次套用整個設定。不過，您也可以指定特定資源。例如：

    terraform apply -target="google_eventarc_trigger.default"

    啟用 API 後，您可能需要稍候幾分鐘，相關動作才會生效，您才能部署其他資源。如果遇到問題，請嘗試再次套用 Terraform 設定。

    等待 Terraform 顯示「Apply complete!」(套用完成) 訊息。

確認資源建立作業

  1. 確認已建立 Cloud Run 服務：

    gcloud run services list --region us-central1

    畫面會顯示如下的輸出內容：

    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. 確認已建立 Eventarc 觸發條件：

    gcloud eventarc triggers list --location us-central1

    畫面會顯示如下的輸出內容：

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

產生及查看 Pub/Sub 主題事件

您可以將訊息發布至 Pub/Sub 主題，藉此產生事件。Eventarc 觸發條件會將訊息轉送至在 Cloud Run 上部署的事件接收器服務，而該服務會記錄事件訊息。

  1. 找出並將 Pub/Sub 主題設為環境變數：

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

  2. 將訊息發布至 Pub/Sub 主題，產生事件：

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

    事件會轉送至 Cloud Run 服務，該服務會記錄事件訊息。

  3. 如要查看服務建立的事件相關記錄項目，請執行下列指令：

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

  4. 尋找類似下列內容的記錄項目：

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

您已成功使用 Terraform 將事件接收器服務部署至 Cloud Run，並建立 Eventarc 觸發條件。從 Pub/Sub 產生事件後，您可以在 Cloud Run 記錄中查看事件。

清除所用資源

完成本快速入門課程中的任務後，您可以刪除已建立的資源，避免繼續計費。

如要移除先前透過 Terraform 設定套用的資源，請執行下列指令，並在提示訊息中輸入 yes：

terraform destroy

您也可以刪除 Google Cloud 專案，避免產生費用。刪除 Google Cloud 專案後，系統就會停止對專案使用的所有資源收取費用。

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

如果打算進行多個教學課程及快速入門導覽課程，重複使用專案有助於避免超出專案配額限制。

後續步驟