自動執行建構作業，因應 Pub/Sub 事件

第 1 代 第 2 代

Cloud Build Pub/Sub 觸發條件可讓您執行建構作業，以回應透過 Pub/Sub 發布的 Google Cloud 事件。您可以根據 Pub/Sub 事件的資訊，為建構作業設定參數，並決定是否要執行建構作業來回應事件。Pub/Sub 觸發條件可設定為監聽任何 Pub/Sub 主題。

本頁說明如何建立 Pub/Sub 觸發條件，自動執行建構作業，以回應 Artifact Registry 和 Cloud Storage 的事件。

注意： Pub/Sub 觸發條件是與 Cloud Build 相關聯的觸發條件類型。 Google Cloud 除非明確說明，否則在其他情境中使用的 Pub/Sub 觸發條件可能不是指 Cloud Build Pub/Sub 觸發條件。

限制

使用 VPC Service Controls 時，系統不支援 Cloud Build Pub/Sub 觸發條件。

事前準備

• 如果尚未啟用，請啟用 Cloud Build API。

  啟用 API 時所需的角色

  如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

  啟用 API

• 請確認原始碼包含建構設定檔，或存放區中含有 Dockerfile。

• 如要使用本頁的 gcloud 指令，請安裝 Google Cloud CLI。

  注意： 如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認目前使用的是最新版本。

建立可回應 Artifact Registry 事件的自動建構觸發條件

您可以建立 Pub/Sub 觸發條件，回應 Artifact Registry 事件，例如映像檔推送、標記或刪除時。本節將說明如何建立 Pub/Sub 觸發條件，在將新標記推送至現有映像檔時叫用建構作業。如果您不熟悉 Artifact Registry，請參閱 Artifact Registry 總覽。

注意： Pub/Sub 觸發條件無法透過 Cloud Build 的內建整合功能，建構 GitHub Enterprise、Bitbucket Data Center 和 Bitbucket Server 存放區。如要透過外部原始碼管理系統複製及建構存放區，請參閱「建立及管理自動建構觸發條件」，瞭解如何內嵌指定建構設定。

控制台

如要使用 Google Cloud 控制台建立觸發條件，監聽推送至 Artifact Registry 現有映像檔的新標記，請按照下列步驟操作：

1. 開啟「觸發條件」頁面：

   開啟「觸發條件」頁面

2. 從頁面頂端選取專案，然後按一下「開啟」。

3. 按一下「建立觸發條件」。

4. 輸入下列觸發條件設定：

   • 名稱：輸入觸發條件的名稱。

   • 區域：選取觸發條件的區域。

     • 如果與觸發條件相關聯的建構設定檔指定了私人集區，Cloud Build 會使用該私人集區執行建構作業。在這種情況下，您在觸發條件中指定的區域必須與建立私人集區的區域相符。
     • 如果與觸發條件相關聯的建構設定檔「未」指定私人集區，Cloud Build 會使用預設集區，在與觸發條件相同的區域中執行建構作業。

   • 「說明」 (選用)：輸入觸發條件的說明。

   • 「Event」(事件)：選取「Pub/Sub message」(Pub/Sub 訊息) 做為叫用觸發條件的事件。

   • 訂閱項目：選取要訂閱的 Pub/Sub 主題做為觸發事件。下拉式選單會顯示專案中的所有現有主題。

     • Pub/Sub 主題：從下拉式選單中選取 gcr 主題，或按照「設定 Pub/Sub 通知」一文中的說明手動建立主題。
     注意： 建立觸發條件後，系統會自動為您建立觸發條件的訂閱項目。您可以在「Pub/Sub subscriptions」(Pub/Sub 訂閱項目) 頁面查看訂閱項目。

   • 來源：選取在 Pub/Sub 觸發條件執行時要建構的來源。

     注意： 存放區的區域必須與觸發程序的區域相符。

   • 存放區代別：選取「第 2 代」。

   • 存放區：選取存放區。

   • 分支版本或標記：指定要比對的分支版本或標記值的規則運算式。如要瞭解可接受的規則運算式語法，請參閱 RE2 語法。

   • 留言控制項：如果您選取「提取要求 (僅限 GitHub 應用程式)」做為「事件」，請選擇下列其中一個選項，控制觸發條件是否會自動執行建構作業：

     警告： 凡是可以讀取這個存放區的使用者，都能提交提取要求。提取要求可能會執行版本，內含提取要求中的原始碼變更。如要防止這種行為，建議您採用手動核准功能，在有人對公開存放區發出提取要求時，針對建構作業進行把關。如要進一步瞭解觸發條件的建構時間權限，請參閱「自動建構觸發條件和 Cloud Build 服務帳戶」一文。

     • 必要 (擁有者和協作者除外)：存放區擁有者或協作者建立或更新提取要求時，觸發條件會自動執行建構作業。如果外部貢獻者啟動動作，只有在擁有者或協作者對提取要求加註 /gcbrun 後，才會執行建構作業。

     • 必要：當任何貢獻者建立或更新提取要求時，只有在擁有者或協作者在提取要求中留言 /gcbrun 後，才會執行建構作業。每當提取要求有變更時，系統就會執行建構作業。

     • 不需設定：任何貢獻者建立或更新提取要求時，觸發條件會自動執行建構作業。

5. 「設定」：選取建構設定檔 (位於遠端存放區中)，或建立內嵌建構設定檔，以用於建構作業。

   • 類型：選取要用於建構作業的設定類型。
     • Cloud Build 設定檔 (YAML 或 JSON)： 使用建構設定檔進行設定。
     • Dockerfile：使用 Dockerfile 進行設定。
     • 建構包：使用 buildpacks 進行設定。

   • 位置：指定設定的位置。

     • 存放區：如果設定檔位於遠端存放區，請提供建構設定檔、Dockerfile 目錄或建構套件目錄的位置。如果建構設定類型為 Dockerfile 或建構套件，您需要為產生的映像檔提供名稱，並視需要為建構作業設定逾時時間。提供 Dockerfile 或建構套件映像檔名稱後，您會看到建構作業執行的 docker build 或 pack 指令預覽畫面。
     • Buildpack 環境變數 (選用)：如果選取 buildpacks 做為設定類型，請按一下「新增套件環境變數」，指定 buildpack 環境變數和值。如要進一步瞭解建構包環境變數，請參閱「環境變數」。

     • 內嵌：如果您選取「Cloud Build 設定檔 (yaml 或 json)」做為設定選項，可以內嵌指定建構設定。點選「開啟編輯器」，在Google Cloud 控制台使用 YAML 或 JSON 語法編寫建構設定檔。按一下「完成」即可儲存建構設定。

       注意： Dockerfile 或建構包不支援內嵌建構設定。

6. 替換 (選用)：如果您選取建構設定檔做為建構設定選項，可以使用這個欄位定義觸發程序專用的替換變數。

   在下列範例中，我們要從酬載和與 gcr 事件相關聯的動作中，取得圖片標記的名稱。如要這麼做，請使用酬載繫結建立替代變數。

   指定下列變數和值：

   變數名稱	變數值
   _IMAGE_TAG	$(body.message.data.tag)
   _ACTION	$(body.message.data.action)

   body.message 參照發布者發布的 PubSubMessage，並由訂閱者取用。如要查看更多 Pub/Sub 通知酬載範例，請參閱「通知範例」。

   注意： 定義替代變數是選用步驟，但如要設定 Pub/Sub 訊息的自訂篩選器，就必須定義替代變數 (詳情請參閱下方的「篩選器」)。

7. 篩選器 (選用)：您可以在觸發條件中建立篩選器，藉此指定替代變數的篩選條件，判斷觸發條件是否會執行建構作業來回應傳入的酬載。篩選運算式必須評估為 true，才能執行建構作業。

   如果主題有多則訊息，我們建議在設定 Pub/Sub 觸發條件時使用篩選功能。您可以使用篩選器精確控管因應傳入 Pub/Sub 訊息而執行的建構作業。如要瞭解設定不含篩選器的觸發條件會帶來哪些風險，請參閱「不含篩選器的觸發條件相關風險」。

   在以下範例中，我們希望在將新標記推送至現有映像檔時，觸發條件會執行建構作業。我們使用篩選條件運算子檢查 _IMAGE_TAG 變數是否與現有代碼名稱相符，以及 _ACTION 變數是否與 INSERT 相符，藉此尋找新加入的資料。

   將下列項目指定為篩選條件：

   • _IMAGE_TAG != ""
   • _ACTION == INSERT
   注意： 您也可以指定下列布林運算子，將條件巢狀化：&& (and) 和 || (or)。系統不支援「非」!符號。

   Pub/Sub 觸發條件中的篩選語法會使用一般運算語言 (CEL) 評估運算式。如要進一步瞭解 CEL，請參閱 cel-spec 存放區。

5. 按一下「建立」即可建立自動建構觸發條件。

gcloud

如要建立觸發程序，監聽推送至 Artifact Registry 現有映像檔的新標記，請使用 gcloud 指令：

1. 開啟終端機視窗。

2. 執行 gcloud 指令，在專案中建立自動建構觸發條件。在下列範例中，觸發條件會根據替代變數 _IMAGE_TAG 定義的指定酬載，設定為回應標記符合 prod 的建構作業，以及動作符合 INSERT 的建構作業。

    gcloud builds triggers create pubsub \
      --region=REGION \
      --name=TRIGGER_NAME \
      --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \
      --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
      --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
      --substitutions=\
        '_IMAGE_TAG_="$(body.message.data.tag)",' \
        '_ACTION="$(body.message.data.action)"' \
      --subscription-filter='_IMAGE_TAG != "" && _ACTION == "INSERT"' \
      --tag=TAG_NAME  # or --branch=BRANCH_NAME
   

其中：

• REGION 是觸發條件的區域。
• TRIGGER_NAME 是觸發條件的名稱。
• PROJECT_ID 是您的雲端專案 ID。
• CONNECTION_NAME 是主機連線的名稱。
• REPO_NAME 是存放區的名稱。
• TOPIC_NAME 是您訂閱的 Pub/Sub 主題名稱。
• BUILD_CONFIG 是建構設定檔的路徑。
• INLINE_BUILD_CONFIG 是內嵌建構設定檔的路徑。
• 如要根據代碼設定觸發條件，TAG_NAME 是代碼的名稱。
• 如要將觸發條件設為在分支版本上建構，BRANCH_NAME 是分支版本的名稱。

建立會回應 Cloud Storage 事件的自動建構觸發條件

您可以建立 Pub/Sub 觸發程序，回應 Cloud Storage 事件，例如將新二進位檔推送至現有儲存空間 bucket 時。本節將說明如何建立 Pub/Sub 觸發條件，以便在將新二進位檔部署至上傳的 bucket 時，以建構作業做為回應。如果不熟悉 Cloud Storage，請參閱快速入門導覽課程。

控制台

如要使用 Google Cloud 控制台建立監聽 Cloud Storage 事件的觸發條件，請按照下列步驟操作：

1. 開啟「觸發條件」頁面：

   開啟「觸發條件」頁面

2. 從頁面頂端選取專案，然後按一下「開啟」。

3. 按一下「建立觸發條件」。

4. 輸入下列觸發條件設定：

   • 名稱：輸入觸發條件的名稱。

   • 區域：選取觸發條件的區域。

     • 如果與觸發條件相關聯的建構設定檔指定了私人集區，Cloud Build 會使用該私人集區執行建構作業。在這種情況下，您在觸發條件中指定的區域必須與建立私人集區的區域相符。
     • 如果與觸發條件相關聯的建構設定檔「未」指定私人集區，Cloud Build 會使用預設集區，在與觸發條件相同的區域中執行建構作業。

   • 「說明」 (選用)：輸入觸發條件的說明。

   • 「Event」(事件)：選取「Pub/Sub message」(Pub/Sub 訊息) 做為叫用觸發條件的事件。

   • 訂閱項目：選取要訂閱的 Pub/Sub 主題，用來當做觸發事件。下拉式選單會顯示專案中的所有現有主題。

     • Pub/Sub 主題：從下拉式選單中選取 gcs 主題，或按照「為 Cloud Storage 設定 Pub/Sub 通知」中的操作說明手動建立主題。
     注意： 建立觸發條件後，系統會自動為您建立觸發條件的訂閱項目。您可以在「Pub/Sub subscriptions」(Pub/Sub 訂閱項目) 頁面查看訂閱項目。

   • 來源：選取在 Pub/Sub 觸發條件執行時要建構的來源。

     注意： 存放區的區域必須與觸發程序的區域相符。

   • 存放區代別：選取「第 2 代」。

   • 存放區：選取存放區。

   • 分支版本或標記：指定要比對的分支版本或標記值的規則運算式。如要瞭解可接受的規則運算式語法，請參閱 RE2 語法。

   • 留言控制項：如果您選取「提取要求 (僅限 GitHub 應用程式)」做為「事件」，請選擇下列其中一個選項，控制觸發條件是否會自動執行建構作業：

     警告： 凡是可以讀取這個存放區的使用者，都能提交提取要求。提取要求可能會執行版本，內含提取要求中的原始碼變更。如要防止這種行為，建議您採用手動核准功能，在有人對公開存放區發出提取要求時，針對建構作業進行把關。如要進一步瞭解觸發條件的建構時間權限，請參閱「自動建構觸發條件和 Cloud Build 服務帳戶」一文。

     • 必要 (擁有者和協作者除外)：存放區擁有者或協作者建立或更新提取要求時，觸發條件會自動執行建構作業。如果外部貢獻者啟動動作，只有在擁有者或協作者對提取要求加註 /gcbrun 後，才會執行建構作業。

     • 必要：當任何貢獻者建立或更新提取要求時，只有在擁有者或協作者在提取要求中留言 /gcbrun 後，才會執行建構作業。每當提取要求有變更時，系統就會執行建構作業。

     • 不需設定：任何貢獻者建立或更新提取要求時，觸發條件會自動執行建構作業。

5. 「設定」：選取建構設定檔 (位於遠端存放區中)，或建立內嵌建構設定檔，以用於建構作業。

   • 類型：選取要用於建構作業的設定類型。
     • Cloud Build 設定檔 (YAML 或 JSON)： 使用建構設定檔進行設定。
     • Dockerfile：使用 Dockerfile 進行設定。
     • 建構包：使用 buildpacks 進行設定。

   • 位置：指定設定的位置。

     • 存放區：如果設定檔位於遠端存放區，請提供建構設定檔、Dockerfile 目錄或建構套件目錄的位置。如果建構設定類型為 Dockerfile 或建構套件，您需要為產生的映像檔提供名稱，並視需要為建構作業設定逾時時間。提供 Dockerfile 或建構套件映像檔名稱後，您會看到建構作業執行的 docker build 或 pack 指令預覽畫面。
     • Buildpack 環境變數 (選用)：如果您選取 buildpacks 做為設定類型，請按一下「新增套件環境變數」，指定 buildpack 環境變數和值。如要進一步瞭解建構套件環境變數，請參閱「環境變數」。

     • 內嵌：如果您選取「Cloud Build 設定檔 (yaml 或 json)」做為設定選項，可以內嵌指定建構設定。點選「開啟編輯器」，在Google Cloud 控制台使用 YAML 或 JSON 語法編寫建構設定檔。按一下「完成」即可儲存建構設定。

       注意： Dockerfile 或建構包不支援內嵌建構設定。

6. 替代項目 (選用)：如果您選取建構設定檔做為建構設定選項，可以選擇使用這個欄位定義觸發條件專屬的替代變數。

   在這個範例中，我們希望在二進位檔上傳至值區時，監控新二進位檔的部署作業。如要取得這項資料，可以使用酬載繫結建立替代變數。

   指定下列變數和值：

   變數名稱	變數值
   _EVENT_TYPE	$(body.message.attributes.eventType)
   _BUCKET_ID	$(body.message.attributes.bucketId)
   _OBJECT_ID	$(body.message.attributes.objectId)

   body.message 參照發布者發布的 PubSubMessage，並由訂閱者取用。如要查看更多 Pub/Sub 通知酬載範例，請參閱「通知範例」。

   注意： 定義替代變數是選用步驟，但如要設定 Pub/Sub 訊息的自訂篩選器，就必須定義替代變數 (詳情請參閱下方的「篩選器」)。

7. 篩選器 (選用)：您可以在觸發條件中建立篩選器，藉此指定替代變數的篩選條件，判斷觸發條件是否會執行建構作業來回應傳入的酬載。篩選運算式必須評估為 true，才能執行建構作業。

   如果主題有多則訊息，我們建議在設定 Pub/Sub 觸發條件時使用篩選功能。您可以使用篩選器精確控管因應傳入 Pub/Sub 訊息而執行的建構作業。如要瞭解設定不含篩選器的觸發條件會帶來哪些風險，請參閱「不含篩選器的觸發條件相關風險」。

   由於我們希望在新的二進位檔部署至特定值區時，觸發條件能執行建構作業，因此可以使用「==」運算子檢查是否完全相符。如要使用規則運算式比對，也可以使用「matches」關鍵字。

   將下列項目指定為篩選條件：

   • _EVENT_TYPE == OBJECT_FINALIZE
   • _OBJECT_ID符合 ^<object-id>$
   • _BUCKET_ID符合 ^<bucket-id>$

5. 按一下「建立」即可建立自動建構觸發條件
。

gcloud

如要建立自動建構觸發條件，監聽 Cloud Storage 中特定事件類型的建構事件，請按照下列步驟操作：

1. 開啟終端機視窗。

2. 執行 gcloud 指令，在專案中建立自動建構觸發條件。在下列範例中，觸發條件設定為回應建構作業，並將 Cloud Storage 事件與推送至現有儲存空間 bucket 的新二進位檔建立關聯：

    gcloud builds triggers create pubsub \
      --region=REGION \
      --name=TRIGGER_NAME \
      --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \
      --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
      --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
      --substitutions=\
        '_EVENT_TYPE="$(body.message.attributes.eventType)",' \
        '_BUCKET_ID="$(body.message.attributes.bucketId)",' \
        '_OBJECT_ID="$(body.message.attributes.objectId)"' \
      --subscription-filter='_EVENT_TYPE == "OBJECT_FINALIZE" && _OBJECT_ID.matches("<object-id>") && _BUCKET_ID.matches("<bucket-id>")' \
      --tag=TAG_NAME  # or --branch=BRANCH_NAME
   

其中：

• REGION 是觸發程序的區域。
• TRIGGER_NAME 是觸發條件的名稱。
• PROJECT_ID 是您的雲端專案 ID。
• CONNECTION_NAME 是主機連線的名稱。
• REPO_NAME 是存放區的名稱。
• TOPIC_NAME 是您訂閱的 Pub/Sub 主題名稱。
• BUILD_CONFIG 是建構設定檔的路徑。
• INLINE_BUILD_CONFIG 是內嵌建構設定檔的路徑。
• 如要根據代碼設定觸發條件，TAG_NAME 是代碼的名稱。
• 如要將觸發條件設為在分支版本上建構，BRANCH_NAME 是分支版本的名稱。

未經過濾的觸發條件相關風險

如果尚未在 Pub/Sub 觸發程序上設定篩選器，且觸發程序修改了構件或物件，導致系統意外將新訊息發布至觸發程序監聽的主題，觸發程序可能會無限次叫用建構作業。舉例來說，如果觸發條件符合下列情況，可能會無限次數觸發建構作業：

• 指向 gcr 主題。
• 在 gcr 中建立任何圖片或標記。
• 指向值區中特定物件的 gcs 主題，並修改該物件。

如果遇到無限迴圈，可以刪除觸發條件或更新觸發條件，指向其他主題，避免每次叫用建構作業時產生額外費用。

後續步驟

• 瞭解如何使用 gcloud 指令或 Cloud Build API 手動啟動建構作業。
• 瞭解如何建立及管理觸發條件。
• 瞭解如何查看建構結果。
• 瞭解如何排解建構錯誤。