自動建構作業，因應 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 觸發條件。

事前準備

• Enable the Cloud Build API.

  Enable the 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. 開啟「觸發條件」頁面：

   開啟「Triggers」(觸發條件) 頁面

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

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

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

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

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

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

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

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

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

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

   • 來源：選取 Pub/Sub 觸發條件執行時要建構的來源。您可以指定「第 1 代」或「第 2 代」做為來源。

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

     • 存放區：從可用存放區清單中選取所需存放區。

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

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

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

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

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

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

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

     • 類型：選取要用於建構作業的設定類型。
       • 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 或建構包不支援內嵌建構設定。

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

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

     指定下列變數和值：

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

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

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

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

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

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

     將下列項目指定為篩選器：

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

     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 是 Cloud 專案的 ID。
• CONNECTION_NAME 是主機連線的名稱。
• REPO_NAME 是存放區的名稱。
• TOPIC_NAME 是您訂閱的 Pub/Sub 主題名稱。
• BUILD_CONFIG 是建構設定檔的路徑。
• INLINE_BUILD_CONFIG 是內嵌建構設定檔的路徑。
• TAG_NAME 是標記的名稱，如果您想將觸發條件設為根據標記建構，請輸入標記名稱。
• 如要將觸發條件設為在分支版本上建構，BRANCH_NAME 是分支版本的名稱。

建立可回應 Cloud Storage 事件的建構觸發條件

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

主控台

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

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

   開啟「Triggers」(觸發條件) 頁面

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

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

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

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

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

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

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

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

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

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

   • 來源：選取 Pub/Sub 觸發條件執行時要建構的來源。您可以指定「第 1 代」或「第 2 代」做為來源。

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

     • 存放區：從可用存放區清單中選取所需存放區。

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

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

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

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

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

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

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

     • 類型：選取要用於建構作業的設定類型。
       • 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 或建構包不支援內嵌建構設定。

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

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

     指定下列變數和值：

     變數名稱	變數值
     _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 訊息的自訂篩選器，就必須定義替代變數 (詳情請參閱下方的「篩選器」)。

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

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

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

     將下列項目指定為篩選器：

     • _EVENT_TYPE == OBJECT_FINALIZE
     • _OBJECT_ID 場比賽 ^<object-id>$
     • _BUCKET_ID 場比賽 ^<bucket-id>$

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

gcloud

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

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

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

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

後續步驟

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