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

本快速入门介绍了如何使用 Terraform 创建 Eventarc 触发器，以接收来自 Pub/Sub 的直接事件并将事件路由到 Cloud Run 服务。如需详细了解如何使用 Terraform 创建 Eventarc 触发器，请参阅使用 Terraform 创建触发器。

在本快速入门中，您将执行以下操作：

  1. 准备部署 Terraform。

  2. 定义一个 Terraform 配置，用于执行以下操作：

    1. 启用 API。
    2. 创建一个服务账号，并向其授予必要的 Identity and Access Management (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. Enable the Cloud Resource Manager and IAM APIs: 

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

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

  9. Install the Google Cloud CLI.

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

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

    gcloud init

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

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

  14. Enable the Cloud Resource Manager and IAM APIs: 

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

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

  16. 如果您是项目创建者，则会被授予基本 Owner 角色 (roles/owner)。默认情况下，此 Identity and Access Management (IAM) 角色可提供完全访问大多数 Google Cloud资源所需的权限，您可以跳过此步骤。

    如果您不是项目创建者，则必须向主账号授予项目的必需权限。例如，主账号可以是 Google 账号（针对最终用户）或服务账号（针对应用和计算工作负载）。如需了解详情，请参阅事件目标位置的角色和权限页面。

    所需权限

    如需获得完成本快速入门所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

    如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

    您也可以通过自定义角色或其他预定义角色来获取所需的权限。

准备部署 Terraform

创建 Terraform 配置文件，为部署 Terraform 资源做好准备。借助 Terraform 配置文件，您可以使用 Terraform 语法为基础架构定义自己偏好的最终状态。

  1. 如果您使用的是本地 Shell，请安装并配置 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 服务代理，请向该服务代理授予 Service Account Token Creator 角色 (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 显示“应用完成！”消息。

验证资源的创建

  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 日志中查看该事件。

清理

完成本快速入门中所述的任务后，您可以通过删除所创建的资源来避免继续计费。

通过运行以下命令并在提示符处输入 yes，移除之前使用 Terraform 配置应用的资源：

terraform destroy

或者，您也可以删除 Google Cloud 项目，以避免产生费用。删除 Google Cloud 项目后，系统即会停止对该项目中使用的所有资源计费。

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

如果您打算探索多个教程和快速入门，重复使用项目可以帮助您避免超出项目配额上限。

后续步骤