将 Cloud Firestore 事件路由到 GKE

Eventarc 触发器声明您对某个事件或一系列事件感兴趣。如需配置事件路由，您可以为触发器指定过滤条件，包括事件来源以及在 Google Kubernetes Engine (GKE) 集群中运行的目标 GKE 服务。请注意，目标只能包含在具有公共端点的（公共或专用）GKE 集群中运行的服务。如需定位具有专用端点的 GKE 集群中的服务，请将事件路由到内部 HTTP 端点。

Eventarc 通过 HTTP 请求以 CloudEvents 格式将事件传送到事件接收器。

Cloud Firestore 支持使用身份验证上下文作为 CloudEvents 格式的扩展属性。创建触发器时，您可以应用此事件类型属性来过滤包含身份验证信息的事件。

以下说明介绍如何配置到 GKE 服务的事件路由（由直接Cloud Firestore 事件触发）。如需了解详情，请参阅支持的直接事件列表。

准备工作

您必须在运行目标服务的 GKE 集群上启用 Workload Identity Federation for GKE。正确设置事件转发器需要使用 Workload Identity Federation for GKE，由于 Workload Identity Federation for GKE 增强的安全属性和可管理性，因此它是从 GKE 中运行的应用访问 Google Cloud 服务的推荐方法。

Workload Identity Federation for GKE

在 GKE 上运行的应用可能需要访问 Google Cloud API。Workload Identity Federation for GKE 支持 GKE 集群中的 Kubernetes 服务账号充当 IAM 服务账号。访问 Google Cloud API 时，使用已配置的 Kubernetes 服务账号的 Pod 会自动以 IAM 服务账号身份进行身份验证。利用 Workload Identity Federation for GKE，您可以为集群中的每个应用分配不同的精细身份和授权。请注意，您必须向 Eventarc 触发器的服务账号授予特定权限。在本文档中，请参阅创建服务账号的步骤。

如需详细了解如何在 GKE 集群上启用和配置 Workload Identity Federation for GKE，请参阅使用 Workload Identity Federation for GKE。

事件转发器

Eventarc 的事件转发器会从 Eventarc 拉取新事件并将其转发到 GKE 目标。此组件充当 Pub/Sub 传输层与 GKE 服务之间的中介。它适用于现有服务，还支持信令服务（包括未在全代管式集群外部公开的服务），同时简化设置和维护。在网络级层，如需接收 GKE 服务中的事件，您无需向外部流量开放服务，因为所有事件都从位于同一 GKE 集群中的来源传送。

请注意，事件转发器的生命周期由 Eventarc 管理，如果您不小心删除了事件转发器，Eventarc 将恢复此组件。

对于指向 GKE 目标的每个触发器，事件转发器（专门配置的 gke-forwarder Pod）会执行以下操作：

事件转发器使用 Pub/Sub API 打开与触发器传输器（Pub/Sub 主题和订阅）的 StreamingPull 连接，并在事件可用时接收事件。
事件转发器将事件转换为正确的 CloudEvents 格式，对其进行编码并将其作为 HTTP POST 请求传送到目标 GKE 服务。

Eventarc 服务代理需要运行并定期更新 gke-forwarder 实例的权限。您必须为每个项目授予一次此权限。如需了解详情，请参阅本文档中的启用 GKE 目标。

准备创建触发器

对于以 GKE 服务为目标的每个触发器，Eventarc 会创建一个事件转发器组件。Eventarc 需要具有在 GKE 集群中安装组件和管理资源的权限。在为 GKE 目标创建 Eventarc 触发器之前，请务必完成以下任务。

控制台

在 Google Cloud 控制台的“项目选择器”页面上，选择或创建 Google Cloud 项目。

注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，这会移除与该项目关联的所有资源。

转到“项目选择器”
启用 Eventarc API、Eventarc Publishing API、Google Kubernetes Engine API 和 Resource Manager API。

启用 API
如果适用，请启用与直接事件相关的 API。例如，对于 Cloud Firestore 事件，请启用Cloud Firestore API。
如果您还没有用户管理的服务账号，请创建一个，然后为其授予必要的角色和权限，以便 Eventarc 可以管理目标服务的事件。
1. 在 Google Cloud 控制台中，进入创建服务账号页面。
  
  转到“创建服务账号”
2. 选择您的项目。
3. 在服务账号名称字段中，输入一个名称。Google Cloud 控制台会根据此名称填充服务账号 ID 字段。
  
  在服务账号说明字段中，输入说明。例如 Service account for event trigger。
4. 点击创建并继续。
5. 如需提供适当的访问权限，请在选择角色列表中，选择要向服务账号授予的所需 Identity and Access Management (IAM) 角色。如需了解详情，请参阅 GKE 目标的角色和权限。
  
  如需添加其他角色，请点击 添加其他角色，然后添加其他各个角色。
6. 点击继续。
7. 如需完成账号的创建过程，请点击完成。

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

启用 Eventarc API、Eventarc Publishing API、Google Kubernetes Engine API 和 Resource Manager API。

gcloud services enable eventarc.googleapis.com \
    eventarcpublishing.googleapis.com \
    container.googleapis.com \
    cloudresourcemanager.googleapis.com

如果适用，请启用与直接事件相关的 API。例如，对于 Cloud Firestore 事件，请启用 firestore.googleapis.com。
如果您还没有用户管理的服务账号，请创建一个，然后为其授予必要的角色和权限，以便 Eventarc 可以管理目标 GKE 目标的事件。
1. 创建服务账号：
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
```
  将 SERVICE_ACCOUNT_NAME 替换为服务账号的名称。该名称必须介于 6 到 30 个字符之间，且可以包含小写字母数字字符和短划线。在服务账号创建完毕后，无法再更改其名称。
2. 授予所需的 Identity and Access Management (IAM) 角色或权限。如需了解详情，请参阅 GKE 目标的角色和权限。

启用 GKE 目标

如需允许 Eventarc 管理 GKE 集群中的资源，请启用 GKE 目标，并将 Eventarc 服务代理与所需的角色绑定。

为 Eventarc 启用 GKE 目标：
```
gcloud eventarc gke-destinations init
```
在系统提示绑定所需角色时，输入 y。

绑定以下角色：
- roles/compute.viewer
- roles/container.developer
- roles/iam.serviceAccountAdmin

创建触发器

您可以使用 Google Cloud CLI 或通过 Google Cloud 控制台创建 Eventarc 触发器。

注意：过滤是通过完全匹配完成的，不支持通配符或正则表达式。不过，您可以在以下 gcloud CLI 命令中使用 --event-filters-path-pattern 标志，或通过控制台定义路径模式。如需了解详情，请参阅了解路径模式。

控制台

在 Google Cloud 控制台中，进入 Eventarc 触发器页面。
转到“触发器”
点击 创建触发器。
输入触发器名称。
这是触发器的 ID，必须以字母开头。最多可包含 63 个小写字母、数字或连字符。
在触发器类型部分，选择 Google 来源。
在事件提供方列表中，选择 Cloud Firestore。
请注意，关联的 Google Cloud 文档中使用的事件提供方名称可能没有 Cloud 或 Google Cloud 前缀。例如，在控制台中，Memorystore for Redis 称为 Google Cloud Memorystore for Redis。
在事件类型列表中，从“直接”事件中选择事件类型。
在事件数据内容类型列表中，选择事件载荷的编码。
对于来自 Cloud Firestore的直接事件，编码必须是 application/protobuf，并且事件数据是字节数组。如需详细了解 Cloud Firestore 事件的 protobuf 消息，请参阅常见事件。
在区域列表中，选择生成事件的 Google Cloud 服务所在的区域。
如需了解详情，请参阅 Eventarc 位置。

如果适用于事件提供方，请点击添加过滤条件并指定以下内容：

在属性 1 字段中，根据您选择的直接事件，选择可用作事件过滤条件的资源 ID。

选择一个运算符：

等于

路径模式：适用于 document（原生模式）和 entity（Datastore 模式）资源。使用通配符响应与模式匹配的更改。通配符 * 与单个分段匹配，多段通配符 ** 与模式中的零个或多个分段匹配。例如：

`/users/*` 或 `/users/{userId}`	与 `/users` 集合中的所有文档匹配。与子集合（如 `/users/marie/messages/33e2IxYBD9enzS50SJ68`）中的文档不匹配
`/users/**`	与 `/users` 集合中的所有文档以及 `/users/marie/messages/33e2IxYBD9enzS50SJ68` 等子集合中的文档匹配

如需了解详情，请参阅了解路径模式。

在属性值 1 字段中，根据您选择的运算符，输入确切的值或应用路径模式。
如果有更多属性过滤条件适用，请点击添加过滤条件并指定适当的值。

选择将调用您的服务或工作流的服务账号。
或者，您可以创建新的服务账号。

这用于指定与触发器相关联且您之前向其授予 Eventarc 所需的特定角色的 Identity and Access Management (IAM) 服务账号电子邮件。
在事件目的地列表中，选择 Kubernetes Engine。
选择一项服务。
这是接收触发器事件的服务的名称。该服务必须与触发器位于同一项目中，并在事件生成时，接收作为 HTTP POST 请求发送到其根网址路径 (/) 的事件。
（可选）您可以指定将传入请求发送到的服务网址路径。
这是触发器的事件应该发送到的目的地服务上的相对路径。例如：/、/route、route、route/subroute。
点击创建。

创建触发器之后，您便无法修改事件来源过滤条件。请创建新触发器，并删除旧触发器。如需了解详情，请参阅管理触发器。

gcloud

您可以通过运行包含必需和可选标志的 gcloud eventarc triggers create 命令来创建触发器。

这些标志取决于您是以原生模式还是 Datastore 模式运行 Firestore。如需了解详情，请参阅在原生模式和 Datastore 模式之间进行选择。

原生模式

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-gke-cluster=DESTINATION_GKE_CLUSTER \
    --destination-gke-location=DESTINATION_GKE_LOCATION \
    --destination-gke-namespace=DESTINATION_GKE_NAMESPACE \
    --destination-gke-service=DESTINATION_GKE_SERVICE \
    --destination-gke-path=DESTINATION_GKE_PATH \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="document=DOCUMENT" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Datastore 模式

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-gke-cluster=DESTINATION_GKE_CLUSTER \
    --destination-gke-location=DESTINATION_GKE_LOCATION \
    --destination-gke-namespace=DESTINATION_GKE_NAMESPACE \
    --destination-gke-service=DESTINATION_GKE_SERVICE \
    --destination-gke-path=DESTINATION_GKE_PATH \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="entity=ENTITY" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

替换以下内容：

TRIGGER：触发器的 ID 或完全限定标识符

LOCATION：Eventarc 触发器的位置。或者，您可以设置 eventarc/location 属性；例如 gcloud config set eventarc/location us-central1。

Eventarc 的 Cloud Firestore 触发器仅在特定位置提供，并且触发器必须与 Cloud Firestore 数据库位于同一位置。如需了解详情，请参阅 Eventarc 位置和 Cloud Firestore 位置。
DESTINATION_GKE_CLUSTER：运行接收事件的目标 GKE 服务的 GKE 集群的名称。
DESTINATION_GKE_LOCATION：（可选）在其中运行目标 GKE 服务的 GKE 集群的 Compute Engine 区域。如果未指定，系统会假定该集群是区域级集群，并且与触发器位于同一区域。
DESTINATION_GKE_NAMESPACE：（可选）运行目标 GKE 服务的命名空间。如果未指定，则使用 default 命名空间。
DESTINATION_GKE_SERVICE：接收触发器事件的 GKE 服务名称。该服务可以位于任何 GKE 支持位置，无需与触发器位于同一位置。但是，该服务必须与触发器位于同一项目中，并在事件生成时，接收作为 HTTP POST 请求发送到其根网址路径 (/) 的事件。
DESTINATION_GKE_PATH：（可选）您在目标 GKE 服务上指定的相对路径，触发器的事件应发送到该路径。例如：/、/route、route、route/subroute。
EVENT_FILTER_TYPE：事件的标识符。方法的 API 调用成功时会生成事件。对于长时间运行的操作，事件仅会在操作结束时生成，并且仅在操作成功执行时才会生成。如需查看受支持的事件类型列表，请参阅 Eventarc 支持的事件类型。

仅在原生模式

google.cloud.firestore.document.v1.created：首次写入文档时发送事件
google.cloud.firestore.document.v1.created.withAuthContext：首次写入文档时发送具有身份验证信息属性的事件
google.cloud.firestore.document.v1.updated：在文档已存在并且值已更改时发送事件
google.cloud.firestore.document.v1.updated.withAuthContext：在文档已存在并且任何值已更改时发送具有身份验证信息属性的事件
google.cloud.firestore.document.v1.deleted：在删除文档时发送事件
google.cloud.firestore.document.v1.deleted.withAuthContext：在删除文档时发送具有身份验证信息属性的事件
google.cloud.firestore.document.v1.written：在创建、更新或删除文档时发送事件
google.cloud.firestore.document.v1.written.withAuthContext：在创建、更新或删除文档时发送具有身份验证信息属性的事件。

Cloud Firestore 仅在 Datastore 模式下支持以下事件类型。在 Datastore 模式下 Firestore 中的数据对象称为实体。

google.cloud.datastore.entity.v1.created：首次写入实体时发送事件
google.cloud.datastore.entity.v1.created.withAuthContext：首次写入实体时发送具有身份验证信息属性的事件
google.cloud.datastore.entity.v1.updated：在实体已存在并且值已更改时发送事件
google.cloud.datastore.entity.v1.updated.withAuthContext：在实体已存在并且任何值已更改时发送具有身份验证信息属性的事件
google.cloud.datastore.entity.v1.deleted：在删除实体时发送事件
google.cloud.datastore.entity.v1.deleted.withAuthContext：在删除实体时发送具有身份验证信息属性的事件
google.cloud.datastore.entity.v1.written：在创建、更新或删除实体时发送事件
google.cloud.datastore.entity.v1.written.withAuthContext：在创建、更新或删除实体时发送具有身份验证信息属性的事件

DATABASE：Firestore 数据库。对于默认数据库名称，请使用 (default)。
NAMESPACE（可选）：Firestore 数据库命名空间。对于 Datastore 模式下的默认命名空间，请使用 (default)。如果未指定，则对任何发生实例进行通配符匹配 (*)。

DOCUMENT（可选）：仅适用于在原生模式下运行的数据库实例。在相应路径中创建、更新或删除数据时，您希望从中接收事件的数据库路径。运算符可以是以下项之一：

等于；例如 --event-filters="document=DOCUMENT"

路径模式；例如 --event-filters-path-pattern="document=DOCUMENT"。

使用通配符响应与模式匹配的文档中的更改。通配符 * 与单个分段匹配，多段通配符 ** 与模式中的零个或多个分段匹配。例如：

`/users/*` 或 `/users/{userId}`	与 `/users` 集合中的所有文档匹配。与 `/users/marie/messages/33e2IxYBD9enzS50SJ68` 等子集合中的文档不匹配
`/users/**`	与 `/users` 集合中的所有文档以及子集合（如 `/users/marie/messages/33e2IxYBD9enzS50SJ68`）中的文档匹配

如需了解详情，请参阅了解路径模式。

ENTITY（可选）：仅适用于在 Datastore 模式下运行的数据库实例。在相应路径中创建、更新或删除数据时，您希望从中接收事件的数据库路径。运算符可以是以下项之一：
- 等于；例如 --event-filters="document=ENTITY"
- 路径模式；例如 --event-filters-path-pattern="ENTITY=ENTITY"
  如需了解详情，请参阅了解路径模式。
  
  请注意，您可能需要对种类 ID 和实体 ID 中的字符进行转义。对字符进行转义可让事件过滤条件正确解释 ID。如需了解详情，请参阅字符转义。

EVENT_DATA_CONTENT_TYPE：事件载荷的编码。对于来自 Firestore 的直接事件，编码必须为 application/protobuf，并且事件数据是字节数组。如需详细了解 Cloud Firestore 事件的 protobuf 消息，请参阅常见事件。
SERVICE_ACCOUNT_NAME：用户管理的服务账号的名称。
PROJECT_ID：您的 Google Cloud 项目 ID。

注意：

对于来自 Cloud Firestore的直接事件，事件载荷的编码为 application/protobuf。
--event-filters="type=EVENT_FILTER_TYPE" 标志是必需的。如果未设置其他事件过滤条件，则匹配所有资源的事件。
EVENT_FILTER_TYPE 创建后无法更改。如需更改 EVENT_FILTER_TYPE，请创建一个新触发器并删除旧触发器。
每个触发器可以有多个事件过滤条件，在一个 --event-filters=[ATTRIBUTE=VALUE,...] 标志内以英文逗号分隔，您也可以重复使用该标志来添加更多过滤条件。只有符合所有过滤条件的事件会被发送到目的地。不支持通配符和正则表达式；但是，使用 --event-filters-path-pattern 标志时，您可以定义资源路径模式。
--service-account 标志用于指定与触发器关联的 Identity and Access Management (IAM) 服务账号电子邮件地址。

示例：

gcloud eventarc triggers create helloworld-trigger \
  --location=us-east1 \
  --destination-gke-cluster=gke-events-cluster \
  --destination-gke-location=us-east1-b \
  --destination-gke-namespace=default \
  --destination-gke-service=helloworld-events \
  --destination-gke-path=/ \
  --event-filters="type=google.cloud.firestore.document.v1.updated" \
  --event-filters="database=my-database" \
  --event-filters-path-pattern="document=users/my-document-*" \
  --event-data-content-type="application/protobuf" \
  --service-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

此命令会为在原生模式下运行的 my-database 数据库实例中标识为 google.cloud.firestore.document.v1.updated 的事件创建一个名为 helloworld-trigger 的触发器，并为 document 路径过滤与 users/my-document- 匹配的事件。

列出触发器

如需确认触发器已创建，您可以使用 Google Cloud CLI 或通过 Google Cloud 控制台列出 Eventarc 触发器。

控制台

在 Google Cloud 控制台中，进入 Eventarc 触发器页面。

转到“触发器”

此页面会列出所有位置的触发器，并包含名称、区域、事件提供方、目标位置等详细信息。
如需过滤触发器，请执行以下操作：
1. 点击过滤或过滤触发器字段。
2. 在属性列表中，选择要作为触发器过滤条件的选项。
您可以选择单个属性，或使用逻辑运算符 OR 添加更多属性。
如需对触发器进行排序，请点击任意受支持的列标题旁边的排序。

gcloud

运行以下命令可列出触发器：

gcloud eventarc triggers list --location=-

此命令会列出所有位置的触发器，并包含名称、类型、目标位置和状态等详细信息。

将 Cloud Firestore 事件路由到 GKE

准备工作

Workload Identity Federation for GKE

事件转发器

准备创建触发器

控制台

gcloud

启用 GKE 目标

创建触发器

控制台

gcloud

原生模式

Datastore 模式

列出触发器

控制台

gcloud

后续步骤