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

本快速入門導覽課程說明如何設定 Google Kubernetes Engine (GKE) 服務做為目的地，使用 Eventarc 接收 Pub/Sub 主題事件。

在本快速入門導覽課程中，您將：

  1. 完成準備工作，例如啟用 API 和設定服務帳戶。
  2. 建立 GKE 叢集。
  3. 在 Eventarc 中初始化 GKE 目的地。
  4. 部署接收事件的 GKE 服務。
  5. 建立 Eventarc 觸發條件，將 Pub/Sub 主題連結至 GKE 服務。
  6. 產生及查看 Pub/Sub 事件。

事前準備

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. 安裝 Google Cloud CLI。

  3. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  4. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  5. 建立或選取 Google Cloud 專案。

    選取或建立專案所需的角色

    • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
    • 建立專案：如要建立專案，您需要「專案建立者」角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    • 建立 Google Cloud 專案：

      gcloud projects create PROJECT_ID

      將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

    • 選取您建立的 Google Cloud 專案：

      gcloud config set project PROJECT_ID

      將 PROJECT_ID 替換為 Google Cloud 專案名稱。

  6. 確認專案已啟用計費功能 Google Cloud 。

  7. 安裝 Google Cloud CLI。

  8. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  9. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  10. 建立或選取 Google Cloud 專案。

    選取或建立專案所需的角色

    • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
    • 建立專案：如要建立專案，您需要「專案建立者」角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    • 建立 Google Cloud 專案：

      gcloud projects create PROJECT_ID

      將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

    • 選取您建立的 Google Cloud 專案：

      gcloud config set project PROJECT_ID

      將 PROJECT_ID 替換為 Google Cloud 專案名稱。

  11. 確認專案已啟用計費功能 Google Cloud 。

  12. 更新 Google Cloud CLI 元件： 
    gcloud components update
  13. 啟用 Eventarc、Resource Manager 和 Google Kubernetes Engine API：
    gcloud services enable eventarc.googleapis.com \
   cloudresourcemanager.googleapis.com \
   container.googleapis.com

  14. 設定本快速入門導覽課程中使用的設定變數： 
    PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=events-cluster
SERVICE_NAME=hello-gke
LOCATION=us-central1

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

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

    所需權限

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

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

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

  16. 記下 Compute Engine 預設服務帳戶，因為您會將其附加至 Eventarc 觸發條件，代表觸發條件的身分，以利進行測試。啟用或使用採用 Compute Engine 的服務後，系統會自動建立這個服務帳戶，電子郵件地址格式如下： Google Cloud 

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    將 PROJECT_NUMBER 替換為 Google Cloud專案編號。您可以在 Google Cloud 控制台的「歡迎」頁面找到專案編號，也可以執行下列指令：

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    在正式環境中，我們強烈建議建立新的服務帳戶，並授予一或多個包含最低必要權限的 IAM 角色，同時遵循最低權限原則。

  17. 將專案的 Pub/Sub 訂閱者角色 (roles/pubsub.subscriber) 授予 Compute Engine 預設服務帳戶，讓 Eventarc 觸發程序可以從 Pub/Sub 提取事件。
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/pubsub.subscriber

  18. 如果您是在 2021 年 4 月 8 日當天或之前啟用 Cloud Pub/Sub 服務代理，請將服務帳戶權杖建立者角色 (roles/iam.serviceAccountTokenCreator) 授予服務代理，以支援已驗證的 Pub/Sub 推送要求。否則，系統會預設授予這個角色： 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

建立 GKE 叢集

GKE 叢集至少包含一個叢集控制層機器，以及多個稱為「節點」的工作站機器。節點為 Compute Engine 虛擬機器 (VM) 執行個體，執行所需的 Kubernetes 程序，使節點成為叢集的一部分。您將應用程式部署至叢集後，應用程式會在節點上運作。

建立名為 events-cluster 的 Autopilot 叢集：

gcloud container clusters create-auto $CLUSTER_NAME \
    --region $LOCATION

叢集會在幾分鐘內建立完畢。叢集建立完成後，輸出內容應如下所示：

Creating cluster events-cluster...done.
Created [https://container.googleapis.com/v1/projects/MY_PROJECT/zones/us-central1/clusters/events-cluster].
[...]
STATUS: RUNNING

這會在專案中建立名為 events-cluster 的 GKE 叢集，專案的 Google Cloud 專案 ID 為 MY_PROJECT。

啟用 GKE 目的地

針對以 GKE 服務為目標的每個觸發條件，Eventarc 會建立事件轉送器元件，從 Pub/Sub 提取事件並轉送至目標。如要在 GKE 叢集中建立元件及管理資源，請授予 Eventarc 服務代理程式權限：

  1. 為 Eventarc 啟用 GKE 目的地：

    gcloud eventarc gke-destinations init

  2. 系統提示繫結必要角色時，請輸入 y。

    下列角色已繫結至服務帳戶：

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

建立 GKE 服務目的地

部署 GKE 服務，使用預先建構的映像檔 us-docker.pkg.dev/cloudrun/container/hello 接收及記錄事件：

  1. Kubernetes 使用名為 kubeconfig 的 YAML 檔案，儲存 kubectl 的叢集驗證資訊。使用憑證和端點資訊更新 kubeconfig 檔案，將 kubectl 指向 GKE 叢集：

    gcloud container clusters get-credentials $CLUSTER_NAME \
    --region $LOCATION

  2. 建立 Kubernetes 部署：

    kubectl create deployment $SERVICE_NAME \
    --image=us-docker.pkg.dev/cloudrun/container/hello

  3. 將其公開為 Kubernetes 服務：

    kubectl expose deployment $SERVICE_NAME \
    --type ClusterIP \
    --port 80 \
    --target-port 8080

建立 Eventarc 觸發條件

訊息發布至 Pub/Sub 主題時，Eventarc 觸發程序會將訊息傳送至 hello-gke GKE 服務。

  1. 建立 GKE 觸發條件，監聽 Pub/Sub 訊息：

    新增 Pub/Sub 主題

    gcloud eventarc triggers create gke-trigger-pubsub \
    --location="$LOCATION" \
    --destination-gke-cluster=$CLUSTER_NAME \
    --destination-gke-location=$LOCATION \
    --destination-gke-namespace=default \
    --destination-gke-service=$SERVICE_NAME \
    --destination-gke-path=/ \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --service-account="PROJECT_NUMBER-compute@developer.gserviceaccount.com"

    這會建立新的 Pub/Sub 主題，以及名為 gke-trigger-pubsub 的觸發條件。

    現有 Pub/Sub 主題

    gcloud eventarc triggers create gke-trigger-pubsub \
    --location="$LOCATION" \
    --destination-gke-cluster=$CLUSTER_NAME \
    --destination-gke-location=$LOCATION \
    --destination-gke-namespace=default \
    --destination-gke-service=$SERVICE_NAME \
    --destination-gke-path=/ \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --service-account="PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --transport-topic=projects/PROJECT_ID/topics/TOPIC_ID

    更改下列內容：

    • PROJECT_ID：您的 Google Cloud 專案 ID
    • TOPIC_ID：現有 Pub/Sub 主題的 ID。這會為現有 Pub/Sub 主題建立名為 gke-trigger-pubsub 的觸發條件。

  2. 確認觸發條件是否已成功建立。觸發條件最多可能需要兩分鐘才能正常運作。

     gcloud eventarc triggers list

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

    NAME: gke-trigger-pubsub
TYPE: google.cloud.pubsub.topic.v1.messagePublished
DESTINATION: GKE: hello-gke
ACTIVE: Yes
LOCATION: us-central1

產生及查看活動

您可以將訊息發布至 Pub/Sub 主題，產生事件來觸發 GKE 服務。然後您就可以在 Pod 記錄中查看訊息。

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

    TOPIC=$(gcloud eventarc triggers describe gke-trigger-pubsub \
    --location=us-central1 \
    --format='value(transport.pubsub.topic)')

  2. 將訊息傳送到 Pub/Sub 主題，產生事件：

    gcloud pubsub topics publish $TOPIC --message="Hello World"

    GKE 服務會記錄事件的訊息。

  3. 如要查看活動訊息，請按照下列步驟操作：

    1. 找出 pod ID：

      kubectl get pods

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

      NAME                                         READY   STATUS             RESTARTS   AGE
hello-gke-645964f578-2mjjt                   1/1     Running            0          35s

      複製 pod 的 NAME，以便在下一步中使用。

    2. 檢查 Pod 的記錄：

      kubectl logs NAME

      將 NAME 替換為您複製的 Pod 名稱。

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

      2022/02/24 22:23:49 Hello from Cloud Run! The container started successfully and is listening for HTTP requests on $PORT
{"severity":"INFO","eventType":"google.cloud.pubsub.topic.v1.messagePublished","message":"Received event of type google.cloud.pubsub.topic.v1.messagePublished. Event data: Hello World"[...]}

清除所用資源

完成本文所述工作後，您可以刪除建立的資源，避免繼續計費。

您可以：

  1. 刪除 Eventarc 觸發條件。

    這也會刪除相關聯的 Pub/Sub 主題。

  2. 刪除 GKE 叢集。

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

刪除 Google Cloud 專案：

gcloud projects delete PROJECT_ID

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

後續步驟

使用 Cloud 稽核記錄接收事件 (Google Cloud CLI)