Cloud Firestore のイベントを GKE に転送する

Eventarc トリガーは、特定のイベントまたは一連のイベントに関心があることを宣言します。イベントルーティングを構成するには、イベントソースと、GKE クラスタで実行されるターゲット Google Kubernetes Engine（GKE）サービスを含むトリガーのフィルタを指定します。なお、ターゲットには、パブリックエンドポイントがある（パブリックまたは限定公開の）GKE クラスタで実行されるサービスのみを含めることができます。プライベートエンドポイントを持つ GKE クラスタ内のサービスをターゲットにするには、内部 HTTP エンドポイントにイベントを転送します。

Eventarc は、HTTP リクエストを使用して、イベントを CloudEvents 形式でイベントレシーバーに配信します。

Cloud Firestore は、CloudEvents 形式の拡張属性として認証コンテキストをサポートしています。トリガーを作成するときに、このイベントタイプ属性を適用して、認証情報を含むイベントをフィルタリングできます。

以下では、Cloud Firestore 直接イベントによってトリガーされる GKE サービスへのイベントルーティングを構成する方法について説明します。詳細については、サポートされている直接イベントのリストをご覧ください。

始める前に

宛先サービスが実行されている GKE クラスタで Workload Identity を有効にする必要があります。Workload Identity は、イベントフォワーダーを適切に設定するために必要です。セキュリティのプロパティと管理性が優れているため、GKE 内で実行されているアプリケーションから Google Cloud サービスにアクセスする場合におすすめの方法です。

Workload Identity

GKE で実行されるアプリケーションで、Google Cloud APIs へのアクセスが必要になる場合があります。Workload Identity では、GKE クラスタ内の Kubernetes サービスアカウントが IAM サービスアカウントとして機能します。構成された Kubernetes サービスアカウントを使用する Pod は、Google Cloud APIs にアクセスするときに IAM サービスアカウントとして自動的に認証されます。Workload Identity を使用すると、クラスタ内のアプリケーションごとに詳細に設定した個別の ID と認可を割り当てることができます。Eventarc トリガーのサービスアカウントに特定の権限を付与する必要があります。このドキュメントのサービスアカウントの作成の手順をご覧ください。

GKE クラスタで Workload Identity を有効にして構成する方法については、Workload Identity の使用をご覧ください。

イベントフォワーダー

Eventarc のイベントフォワーダーが Eventarc から新しいイベントを pull し、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 インスタンスを実行して定期的に更新する権限が必要です。この権限は、プロジェクトごとに 1 回付与する必要があります。詳細については、このドキュメントの GKE の宛先を有効にするをご覧ください。

トリガーを作成する準備

Eventarc は、GKE サービスをターゲットとするトリガーごとにイベントフォワーダーコンポーネントを作成します。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

トリガーを作成する

Eventarc トリガーは、Google Cloud CLI または Google Cloud コンソールを使用して作成できます。

注: フィルタリングは完全一致を基本としています。ワイルドカードや正規表現には対応していません。ただし、次の 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 モード）のリソースに適用されます。パターンに一致する変更に応答するには、ワイルドカードを使用します。ワイルドカード * は単一のセグメントに一致し、マルチセグメントワイルドカード ** はパターン内の 0 個以上のセグメントに一致します。次に例を示します。

`/users/*` または `/users/{userId}`	`/users` コレクション内のすべてのドキュメントに一致します。`/users/marie/messages/33e2IxYBD9enzS50SJ68` のようなサブコレクション内のドキュメントには一致しません。
`/users/**`	`/users` コレクション内のすべてのドキュメントと、`/users/marie/messages/33e2IxYBD9enzS50SJ68` のようなサブコレクション内のドキュメントに一致します。

詳細については、パスパターンについてをご覧ください。

[属性の値 1] フィールドに、選択した演算子に応じて正確な値を入力するか、パスパターンを適用します。
適用可能な属性フィルタが他にもある場合は、[フィルタを追加] をクリックして適切な値を指定します。

サービスまたはワークフローを呼び出すサービスアカウントを選択します。
新しいサービスアカウントを作成することもできます。

これにより、トリガーに関連付けられた Identity and Access Management（IAM）サービスアカウントのメールアドレスが設定されます。このメールアドレスには、Eventarc が必要とする特定のロールがすでに付与されています。
[イベントの宛先] リストで、[Kubernetes Engine] を選択します。
サービスを選択します。
これは、トリガーのイベントを受信するサービスの名前です。サービスはトリガーと同じプロジェクトに配置する必要があり、イベントが生成されるたびに、ルート URL パス（/）に送信された HTTP POST リクエストとしてイベントを受信します。
必要に応じて、受信リクエストの送信先であるサービスの URL パスを指定できます。
これは、トリガーのイベントの送信先である宛先サービスの相対パスです。例: /、/route、route、route/subroute
[作成] をクリックします。

トリガーの作成後は、イベントソースのフィルタを変更できません。代わりに、新しいトリガーを作成して古いトリガーを削除します。詳しくは、トリガーの管理をご覧ください。

gcloud

トリガーを作成するには、必須フラグとオプションのフラグを指定して gcloud eventarc triggers create コマンドを実行します。

フラグは、Firestore をネイティブモードと Datastore モードのどちらで実行しているかによって異なります。詳細については、ネイティブモードと 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 サービスが実行されている Namespace。指定しない場合は、default Namespace が使用されます。
DESTINATION_GKE_SERVICE: トリガーのイベントを受け取る GKE サービスの名前。サービスは、GKE でサポートされているどのロケーションにも配置できます。トリガーと同じロケーションに配置する必要はありません。ただし、サービスはトリガーと同じプロジェクトに配置する必要があり、イベントが生成されるたびに、ルート URL パス（/）に送信された 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"。

パターンに一致するドキュメントの変更に応答するには、ワイルドカードを使用します。ワイルドカード * は単一のセグメントに一致し、マルチセグメントワイルドカード ** はパターン内の 0 個以上のセグメントに一致します。次に例を示します。

`/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 という名前で作成し、users/my-document- と一致する document パスのイベントをフィルタします。

トリガーを一覧表示する

トリガーの作成を確認するには、Google Cloud CLI または Google Cloud コンソールを使用して Eventarc トリガーを一覧表示します。

コンソール

Google Cloud コンソールで、[Eventarc] の [トリガー] ページに移動します。

[トリガー] に移動

このページには、すべてのロケーションのトリガーが一覧表示されます。また、名前、リージョン、イベントプロバイダ、宛先などの詳細情報も表示されます。
トリガーをフィルタするには:
1. [ フィルタ] フィールドまたは [トリガーをフィルタリング] フィールドをクリックします。
2. [プロパティ] リストで、トリガーをフィルタするオプションを選択します。
1 つのプロパティを選択することも、論理演算子 OR を使用して複数のプロパティを追加することもできます。
トリガーを並べ替えるには、サポートされている列見出しの横にある [ 並べ替え] をクリックします。

gcloud

次のコマンドを実行してトリガーを一覧表示します。

gcloud eventarc triggers list --location=-

すべてのロケーションのトリガーが一覧表示されます。名前、タイプ、宛先、ステータスなどの詳細情報も表示されます。

Cloud Firestore のイベントを GKE に転送する

始める前に

Workload Identity

イベント フォワーダー

トリガーを作成する準備

コンソール

gcloud

GKE の宛先を有効にする

トリガーを作成する

コンソール

gcloud

ネイティブ モード

Datastore モード

トリガーを一覧表示する

コンソール

gcloud

次のステップ

イベントフォワーダー

ネイティブモード