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

プレビュー — Eventarc for GKE destinations

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

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

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

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

注: Google プロバイダでダイレクト イベントと監査ログイベントの両方に対応している場合は、ダイレクト イベントをフィルタするトリガーを作成することをおすすめします。ダイレクト イベントには監査ログイベントよりも多くのメリットがあります。詳細については、イベントルートをご覧ください。

始める前に

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

Workload Identity Federation for GKE

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

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

イベント フォワーダー

Eventarc のイベント フォワーダーが Eventarc から新しいイベントを pull し、GKE の宛先に転送します。このコンポーネントは、Pub/Sub トランスポート層と GKE サービスの間の仲介役として機能し、設定やメンテナンスを簡素化します。また、既存のサービスで動作するだけでなく、シグナリング サービス（フルマネージド クラスタ外に公開されていないサービスを含む）にも対応しています。ネットワーク レベルでは、GKE サービスでイベントを受信するために、外部トラフィックに対してサービスを開く必要はありません。すべてのイベントは、同じ GKE クラスタ内に存在する送信元から配信されます。

イベント フォワーダーのライフサイクルは Eventarc によって管理されており、誤ってイベント フォワーダーを削除しても、Eventarc がこのコンポーネントを復元します。

GKE の宛先を参照するトリガーごとに、イベント フォワーダー（明示的に構成された gke-forwarder Pod）は次の処理を行います。

1. Pub/Sub API を使用して、トリガー トランスポーター（Pub/Sub トピックとサブスクリプション）への StreamingPull 接続を開き、利用可能になったイベントを受信します。

2. イベントを正しい CloudEvents 形式に変換してエンコードし、HTTP POST リクエストとしてターゲットの GKE サービスに配信します。

Eventarc サービス エージェントには、gke-forwarder インスタンスを実行して定期的に更新する権限が必要です。この権限は、プロジェクトごとに 1 回付与する必要があります。詳細については、このドキュメントの GKE の宛先を有効にするをご覧ください。

トリガーを作成する準備

Eventarc は、GKE サービスをターゲットとするトリガーごとにイベント フォワーダー コンポーネントを作成します。Eventarc には、コンポーネントをインストールして GKE クラスタ内のリソースを管理する権限が必要です。GKE の宛先に Eventarc トリガーを作成する前に、次のタスクを完了してください。

コンソール

1. Google Cloud コンソールのプロジェクト セレクタ ページで、Google Cloud プロジェクトを選択または作成します。

   注: この手順で作成するリソースをそのまま保持する予定でない場合、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。チュートリアルの終了後にそのプロジェクトを削除すれば、プロジェクトに関連するすべてのリソースを削除できます。

   プロジェクト セレクタに移動

2. Eventarc API、Eventarc Publishing API、Google Kubernetes Engine API、Resource Manager API を有効にします。

   API を有効にする

3. 該当する場合は、ダイレクト イベントに関連する API を有効にします。たとえば、 Cloud Storage イベントの場合はCloud Storage API を有効にします。

4. アカウントがない場合は、ユーザー管理のサービス アカウントを作成し、Eventarc がターゲット サービスのイベントを管理できるように、必要なロールと権限を付与します。

   1. Google Cloud コンソールで [サービス アカウントの作成] ページに移動します。

      [サービス アカウントの作成] に移動

   2. プロジェクトを選択します。

   3. [サービス アカウント名] フィールドに名前を入力します。Google Cloud コンソールでは、この名前に基づいて [サービス アカウント ID] フィールドの値が設定されます。

      [サービス アカウントの説明] フィールドに説明を入力します。例: Service account for event trigger

   4. [作成して続行] をクリックします。

   5. 適切なアクセス権を付与するには、[ロールを選択] リストで、サービス アカウントに必要な Identity and Access Management（IAM）ロールを選択します。詳細については、GKE ターゲットのロールと権限をご覧ください。

      ロールを追加するには、[別のロールを追加] をクリックします。

   6. [続行] をクリックします。

   7. アカウントの作成を完了するには、[完了] をクリックします。

5. Cloud Storage サービス エージェントに Pub/Sub パブリッシャーのロールを付与します。通常は [e-mail] であり、これにより、Cloud Storage サービス エージェントのメールアドレスを取得できます。

   1. Google Cloud コンソールの [IAM] ページに移動します。

      [IAM] に移動

   2. Cloud Storage サービス エージェントの行で、「プリンシパルを編集します」をクリックします（サービス エージェントがリストにない場合は、次のステップに進みます）。権限の編集ペインが開きます。

      1. [別のロールを追加] をクリックして、Pub/Sub パブリッシャーのロールを検索します。
      2. ロールを選択します。
      3. [保存] をクリックします。

   3. サービス エージェントがリストにない場合は、[アクセス権を付与] をクリックします。アクセス権の付与ペインが開きます。

      1. [新しいプリンシパル] フィールドに、サービス エージェントのメールアドレスを入力します。
      2. [ロールを選択] リストで、Pub/Sub パブリッシャー ロールを検索します。
      3. ロールを選択します。
      4. [保存] をクリックします。

gcloud

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

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

3. 該当する場合は、ダイレクト イベントに関連する API を有効にします。たとえば、 Cloud Storage イベントの場合は storage.googleapis.com を有効にします。

4. アカウントがない場合は、ユーザー管理のサービス アカウントを作成し、Eventarc がターゲット GKE の宛先のイベントを管理できるように、必要なロールと権限を付与します。

   1. サービス アカウントを作成します。

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      SERVICE_ACCOUNT_NAME は、サービス アカウントの名前に置き換えます。6～30 文字で、小文字の英数字とダッシュを使用できます。作成したサービス アカウントの名前は変更できません。

   2. 必要な Identity and Access Management（IAM）のロールまたは権限を付与します。詳細については、GKE ターゲットのロールと権限をご覧ください。

5. Cloud Storage サービス アカウントに pubsub.publisher ロールを付与します。

   SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:${SERVICE_ACCOUNT}" \
     --role="roles/pubsub.publisher"
   

GKE の宛先を有効にする

Eventarc が GKE クラスタ内のリソースを管理できるようにするには、GKE の宛先を有効にし、Eventarc サービス エージェントを必要なロールにバインドします。

1. Eventarc 用に GKE の宛先を有効にします。

   gcloud eventarc gke-destinations init

2. 必要なロールをバインドするよう求められたら、「y」と入力します。

   次のロールがバインドされます。

   • roles/compute.viewer
   • roles/container.developer
   • roles/iam.serviceAccountAdmin

トリガーを作成する

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

注: フィルタリングは完全一致を基本としています。ワイルドカードや正規表現はサポートされていません。

コンソール

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

   [トリガー] に移動

2. [トリガーを作成] をクリックします。
3. トリガー名を入力します。

   これはトリガーの ID で、先頭は英字にする必要があります。63 文字以下とし、小文字、数字、ハイフンを使用できます。

4. [トリガーのタイプ] で、[Google のソース] を選択します。
5. [イベント プロバイダ] リストで「Cloud Storage」を選択します。

   関連する Google Cloud のドキュメントでは、イベント プロバイダ名の前に Cloud または Google Cloud が付いていない場合があります。たとえば、Memorystore for Redis はコンソールで Google Cloud Memorystore for Redis と表示されます。

6. [イベントタイプ] リストで、直接イベントからイベントタイプを選択します。
   • google.cloud.storage.object.v1.archived: オブジェクトのライブ バージョンがアーカイブまたは削除された時点でイベントが送信されます。このイベントは、バージョニング対応バケットの場合にのみ送信されます。
   • google.cloud.storage.object.v1.delete: オブジェクトが完全に削除されたときにイベントが送信されます。バケットのオブジェクト バージョニングの設定に応じて、このイベントが持つ意味は以下のように異なります。
     • バージョニング対応バケットの場合、バージョンが完全に削除されたときにのみ、イベントが送信されます（オブジェクトがアーカイブされたときには送信されません）。
     • バージョニングに対応しないバケットの場合、オブジェクトが削除または上書きされると、イベントが送信されます。
   • google.cloud.storage.object.v1.finalized: バケット内で新しいオブジェクトが作成された時点（または既存のオブジェクトが上書きされ、そのオブジェクトの新しい世代が作成された時点）でイベントが送信されます。
   • google.cloud.storage.object.v1.metadataUpdated: 既存のオブジェクトの [メタデータ](/storage/docs/metadata) が変更されたときにイベントが送信されます。
7. [イベントデータのコンテンツ タイプ] リストで、イベント ペイロードのエンコードを選択します。

   Cloud Storageからの直接イベントの場合は、application/json にする必要があります。

8. Cloud Storage バケットのグローバル固有識別子を指定するか、参照します。

   Cloud Storage バケットの Google Cloud プロジェクトとロケーション（リージョンまたはマルチリージョン）は Eventarc トリガーと同じにする必要があります。

9. リージョンを選択します。

   Eventarc の Cloud Storage トリガーは、シングルリージョン、デュアルリージョン、マルチリージョンのロケーションで利用できます。Cloud Storage バケットの Google Cloud プロジェクトとロケーション（リージョンまたはマルチリージョン）は Eventarc トリガーと同じにする必要があります。

   イベントは、Cloud Storage からの Pub/Sub 通知を使用して配信されます。同一のバケットに対して過剰な数の通知を登録すると、エラー Cloud Storage bucket ...: Pub/Sub notification limit reached で示されるように、バケットの通知上限を超えてしまう可能性があります。特定のイベントをトリガーするように設定された通知構成は、最大 10 個までバケットに設定できます。Cloud Storage の割り当てと上限のページで、割り当てと上限の詳細をご確認ください。

10. サービスまたはワークフローを呼び出すサービス アカウントを選択します。

    新しいサービス アカウントを作成することもできます。

    これにより、トリガーに関連付けられた Identity and Access Management（IAM）サービス アカウントのメールアドレスが設定されます。このメールアドレスには、Eventarc が必要とする特定のロールがすでに付与されています。

11. [イベントの宛先] リストで、[Kubernetes Engine] を選択します。
12. サービスを選択します。
    

    これは、トリガーのイベントを受信するサービスの名前です。サービスはトリガーと同じプロジェクトに配置する必要があり、イベントが生成されるたびに、ルート URL パス（/）に送信された HTTP POST リクエストとしてイベントを受信します。

13. 必要に応じて、受信リクエストの送信先であるサービスの URL パスを指定できます。

    これは、トリガーのイベントの送信先である宛先サービスの相対パスです。例: /、/route、route、route/subroute

14. [作成] をクリックします。

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

gcloud

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

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="bucket=BUCKET" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

次のように置き換えます。

• TRIGGER: トリガーの ID または完全修飾識別子。
• LOCATION: Eventarc トリガーのロケーション。eventarc/location プロパティを設定することもできます（例: gcloud config set eventarc/location us-central1）。

  Cloud Storage バケットの Google Cloud プロジェクトとロケーション（リージョンまたはマルチリージョン）は Eventarc トリガーと同じする必要があります。詳細については、Eventarc のロケーションをご覧ください。

• 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: Cloud Storage イベントの識別子。次のいずれかになります。
  • google.cloud.storage.object.v1.finalized: バケット内で新しいオブジェクトが作成された時点（または既存のオブジェクトが上書きされ、そのオブジェクトの新しい世代が作成された時点）でイベントが送信されます。
  • google.cloud.storage.object.v1.archived: オブジェクトのライブ バージョンがアーカイブまたは削除された時点でイベントが送信されます。このイベントは、バージョニング対応バケットの場合にのみ送信されます。
  • google.cloud.storage.object.v1.deleted: オブジェクトが完全に削除された時点でイベントが送信されます。バケットのオブジェクト バージョニングの設定に応じて、このイベントが持つ意味は以下のように異なります。
    • バージョニング対応バケットの場合、バージョンが完全に削除されたときにのみ、イベントが送信されます（オブジェクトがアーカイブされたときには送信されません）。
    • バージョニングに対応しないバケットの場合、オブジェクトが削除または上書きされると、これが送信されます。
  • google.cloud.storage.object.v1.metadataUpdated: 既存のオブジェクトのメタデータが変更された時点でイベントが送信されます。
• BUCKET は、Cloud Storage バケットの、グローバルに一意の識別子です。
• SERVICE_ACCOUNT_NAME: ユーザー管理のサービス アカウントの名前。
• PROJECT_ID: Google Cloud プロジェクト ID。

注:

• 以下のフラグは必須です。
  • --event-filters="type=EVENT_FILTER_TYPE"
  • --event-filters="bucket=BUCKET"
• 各トリガーには複数のイベント フィルタを指定できます。その場合は、--event-filters=[ATTRIBUTE=VALUE,...] フラグにカンマ区切りで指定する必要があります。さらにフィルタを追加するには、このフラグを繰り返し指定します。すべてのフィルタに一致するイベントのみが宛先に送信されます。ワイルドカードと正規表現はサポートされていません。
• トリガーの作成後に、イベント フィルタのタイプを変更することはできません。別のイベントタイプには、新しいトリガーを作成して、古いトリガーを削除する必要があります。
• イベントは、Cloud Storage からの Pub/Sub 通知を使用して配信されます。同一のバケットに対して過剰な数の通知を登録すると、エラー Cloud Storage bucket ...: Pub/Sub notification limit reached で示されるように、バケットの通知上限を超えてしまう可能性があります。バケットには、特定のイベントをトリガーするように設定された通知構成を最大 10 個まで設定できます。Cloud Storage の割り当てと上限のページで、割り当てと上限の詳細をご確認ください。
• Cloud Storageからの直接イベントの場合、イベント ペイロードのエンコードは application/json です。
• --service-account フラグには、トリガーに関連付けられた Identity and Access Management（IAM）サービス アカウントのメールアドレスを指定します。

例:

gcloud eventarc triggers create helloworld-trigger \
    --location=us-central1 \
    --destination-gke-cluster=gke-events-cluster \
    --destination-gke-location=us-central1-a \
    --destination-gke-namespace=default \
    --destination-gke-service=helloworld-events \
    --destination-gke-path=/ \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=my-bucket" \
    --service-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

このコマンドは、Cloud Storage バケット my-bucket と google.cloud.storage.object.v1.finalized として識別されるイベントに対して helloworld-trigger というトリガーを作成します。

Terraform

Terraform を使用して、GKE の宛先のトリガーを作成できます。詳細については、Terraform を使用してトリガーを作成するをご覧ください。

注: トリガーはすぐに作成されますが、トリガーが伝播されてイベントがフィルタされるまでに最大で 2 分かかることがあります。

トリガーを一覧表示する

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

コンソール

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

   [トリガー] に移動

   このページには、すべてのロケーションのトリガーが一覧表示されます。また、名前、リージョン、イベント プロバイダ、宛先などの詳細情報も表示されます。

2. トリガーをフィルタするには:

   1. [ フィルタ] フィールドまたは [トリガーをフィルタリング] フィールドをクリックします。
   2. [プロパティ] リストで、トリガーをフィルタするオプションを選択します。

   1 つのプロパティを選択することも、論理演算子 OR を使用して複数のプロパティを追加することもできます。

3. トリガーを並べ替えるには、サポートされている列見出しの横にある [ 並べ替え] をクリックします。

gcloud

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

gcloud eventarc triggers list --location=-

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

次のステップ

• Eventarc の詳細を学習する。
• トリガーを管理する方法を確認する。