儲存及查看建構作業記錄

執行建構作業時，Cloud Build 會收集並儲存建構記錄。本頁說明如何儲存、查看及刪除建構記錄。

選擇要將建構記錄傳送到何處

您可以設定 Cloud Build 將建構記錄傳送至 Cloud Storage 值區、Cloud Logging 值區，或同時傳送至這兩個值區。

• 如要控管所儲存建構記錄的保留期限，請將記錄傳送至 Cloud Logging。Cloud Logging 也提供更多選項，可搜尋特定建構記錄的 bucket。

• 在某些情況下，建構記錄產生後，要經過一段時間 Logging 才會收到。將建構記錄傳送至 Cloud Storage 中的值區，或許可以縮短延遲時間。

Cloud Storage 和 Logging 都允許您將記錄儲存在 Google 建立的預設 bucket，或使用者建立的自訂 bucket。預設值區可讓您查看儲存在值區中的記錄，但無法變更值區的任何設定。如果您需要完全控管用於儲存建構記錄的 bucket，請將記錄傳送至使用者建立的 bucket。

將建構記錄檔儲存在預設 bucket 中

Cloud Logging 和 Cloud Storage 都有預設值區，可供您儲存建構記錄。這些 buckets 由 Google 建立及擁有，可接收來自多個區域的記錄。如要將建構記錄傳送至其中一個值區，請使用下列其中一個值設定建構設定檔的 LoggingMode：

• GCS_ONLY：記錄會儲存在預設的 Cloud Storage 值區中。

• CLOUD_LOGGING_ONLY：記錄檔會儲存在預設的 Logging bucket 中。

• LEGACY：記錄檔會儲存在兩個預設 bucket 中。

預設的記錄檔 bucket 會對儲存的記錄套用 30 天的保留政策。如要為儲存在 Logging 中的建構記錄設定自訂保留政策，請將建構記錄儲存在自訂 bucket 中。

預設 Cloud Storage bucket 沒有保留政策。

使用 Dockerfile 建構映像檔

您可以使用 Dockerfile 建構 Docker 映像檔，無須另外建立建構設定檔。這麼做時，建構記錄會同時儲存在預設的 Cloud Storage 和 Logging bucket 中。如要變更建構記錄的儲存方式，請在執行 gcloud builds submit 時，將 --default-buckets-behavior 旗標值設為 regional-user-owned-bucket。這項設定會在與建構作業相同的專案和區域中建立 bucket。

將建構記錄儲存在使用者擁有的特定區域 Cloud Storage bucket 中

如果您將建構記錄傳送至預設的 Cloud Storage 值區，Cloud Build 會將記錄儲存在 Google 指定的區域，該區域可能與您執行建構作業的位置不同。不過，您也可以設定建構作業，讓 Cloud Build 將建構記錄傳送至使用者擁有的 Cloud Storage bucket，該 bucket 必須與您執行建構作業的區域相同。這項設定可讓您進一步控管建構記錄資料的位置，有助於遵守資料落地規定。

注意： 在自有值區中儲存記錄檔會產生費用。如要瞭解定價詳情，請參閱 Cloud Storage 定價。

授予 IAM 權限：

如果 Cloud Storage 值區和 Cloud Build 位於 Google Cloud 同一個專案，且您使用 Cloud Build 舊版服務帳戶，則該服務帳戶預設會具備必要的 IAM 權限。您不必授予任何額外權限。如果沒有，請按照下列步驟操作：

為確保 具備必要權限，能在使用者擁有的特定區域 bucket 中儲存建構記錄，請要求管理員在用於建構的服務帳戶中，授予 Storage 管理員 (roles/storage.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

管理員或許也能透過自訂角色或其他預先定義的角色，授予必要權限。

設定特定區域的 Cloud Storage bucket：

1. 在建構設定檔中，新增 defaultLogsBucketBehavior 選項並將其值設為 REGIONAL_USER_OWNED_BUCKET：

   YAML

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ]
   options:
     defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET
   

   JSON

   {
     "steps": [
       {
         "name": "gcr.io/cloud-builders/docker",
         "args": [
           "build",
           "-t",
           "us-central1-docker.pkg.dev/myproject/myrepo/myimage",
           "."
         ]
       }
       ],
       "options": {
         "defaultLogsBucketBehavior": "REGIONAL_USER_OWNED_BUCKET"
       }
   }
   

2. 使用建構設定檔透過指令列、API 或觸發條件展開建構作業。

   執行建構作業時，Cloud Build 會在您執行建構作業的區域中建立新 bucket，然後將建構記錄檔儲存在這個 bucket 中。只要 REGIONAL_USER_OWNED_BUCKET 處於啟用狀態，同一專案和區域的後續建構作業就會使用現有 bucket。這個值區屬於使用者擁有，因此您可以像設定使用者建立的值區一樣設定這個值區。

如果您設定 REGIONAL_USER_OWNED_BUCKET 選項，然後在多個區域中建立建構作業，Cloud Build 會為建構記錄建立多個 bucket。

區域專屬的預設 Cloud Storage 值區沒有保留政策。不過，您可以設定物件生命週期規則，自動刪除值區中的建構記錄。

將建構作業記錄檔儲存在使用者建立的 bucket 中

使用者建立的值區可讓您進一步控管記錄檔值區的管理和設定。

將建構記錄儲存在使用者建立的 Cloud Logging 值區中

使用者建立的記錄檔值區可讓您調整所儲存建構記錄的保留期限。如要將建構記錄儲存在 Logging 中使用者建立的 bucket，請按照下列步驟操作：

授予 IAM 權限：

為確保 具備必要權限，能將建構記錄儲存在使用者建立的 Cloud Logging bucket 中，請要求管理員在您專案的帳戶或服務帳戶中，授予 記錄檔設定寫入者 (roles/logging.configWriter) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

管理員或許也能透過自訂角色或其他預先定義的角色，授予必要權限。

設定記錄 bucket：

1. 建立 bucket，並為「保留期限」欄位設定值。

2. 建立接收器 ，將建構記錄檔傳送至新值區：

   1. 為接收器的建構納入篩選器輸入下列內容：

      logName = "projects/PROJECT_ID/logs/cloudbuild"
      

      將 PROJECT-ID 替換為專案 ID。 Google Cloud

   2. (選用) 如要防止記錄檔傳送至預設的 Logging bucket，請按照「停止在記錄檔 bucket 中儲存記錄項目」一文中的範例操作。

將建構記錄檔儲存在使用者建立的 Cloud Storage bucket 中

如要將建構記錄檔儲存在使用者建立的 Cloud Storage bucket 中，請按照下列步驟操作：

授予 IAM 權限：

如果 Cloud Storage 值區和 Cloud Build 位於 Google Cloud 同一個專案，且您使用的是 Cloud Build 舊版服務帳戶，則 Cloud Build 舊版服務帳戶預設會具備必要的 IAM 權限。您不必授予任何額外權限。如果沒有，請按照下列步驟操作：

為確保 具備必要權限，能將建構記錄檔儲存在使用者建立的 Cloud Storage bucket 中，請要求管理員針對建構作業使用的服務帳戶，將 Storage 管理員 (roles/storage.admin) IAM 角色授予 。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

管理員或許也能透過自訂角色或其他預先定義的角色，授予必要權限。

設定 Cloud Storage bucket：

1. 在 Google Cloud 專案中，建立 Cloud Storage 值區，且未設定保留政策，用於儲存建構記錄。

2. 在建構設定檔中，新增指向您建立的 Cloud Storage 值區的 logsBucket 欄位，用來儲存建構記錄。下列範例建構設定檔包含建構容器映像檔的操作說明，並將建構記錄儲存在名為 mylogsbucket 的值區中：

   YAML

       steps:
       - name: 'gcr.io/cloud-builders/docker'
         args: [ 'build', '-t', 'us-east1-docker.pkg.dev/myproject/myimage', '.' ]
       logsBucket: 'gs://mylogsbucket'
       options:
         logging: GCS_ONLY
   

   JSON

       {
         "steps": [
          {
            "name": "gcr.io/cloud-builders/docker",
            "args": [
              "build",
              "-t",
              "us-east1-docker.pkg.dev/myproject/myimage",
              "."
            ]
          }
          ],
          "logsBucket": "gs://mylogsbucket",
          "options": {
            "logging": "GCS_ONLY"
          }
       }
   

3. 使用建構設定檔透過指令列、API 或觸發條件展開建構作業。

建構完成後，Cloud Build 會將記錄儲存在建構設定檔中指定的 Cloud Storage bucket。

記錄設定的優先順序

如果您在 logsBucket 中定義使用者建立的 Cloud Storage 值區，Cloud Build 會將建構記錄傳送至使用者建立的值區，而不是預設的 Cloud Storage 值區。

如果您要將 defaultLogsBucketBehavior 選項新增至現有的建構設定檔，且先前已設定 logging 或 logsBucket 選項，建議您刪除這些設定，以免設定之間發生衝突。具體來說，如果已設定下列項目，defaultLogsBucketBehavior將無法運作：

• logging: CLOUD_LOGGING_ONLY，將建構記錄儲存在 Cloud Logging 中。
• logging: NONE 即可關閉記錄功能。

如果您執行建構作業時，建構設定檔中未設定任何記錄選項，Cloud Build 會設定 logging: LEGACY，並將建構記錄儲存在預設的 Cloud Storage 值區。將 defaultLogsBucketBehavior 設為 REGIONAL_USER_OWNED_BUCKET 會覆寫 logging: LEGACY。

查看建構作業記錄

如要查看建構記錄，請按照下列步驟操作：

授予 IAM 權限：

為確保 具備必要權限，可在 Cloud Storage 或 Logging 中查看建構記錄，請要求管理員在用於建構的服務帳戶中，授予 下列 IAM 角色：

• 在使用者建立或擁有的 Cloud Storage bucket 中查看建構記錄：
  • Storage 物件檢視者 (roles/storage.objectViewer)：要查看建構記錄的主體
  • 記錄檔檢視存取者 (roles/logging.viewAccessor)：想要查看建構記錄的主體
• 在預設 Cloud Storage bucket 中查看建構記錄： 檢視者 (roles/viewer) - 設定建構作業的專案
• 在 Logging 中查看建構作業記錄： 記錄檢視器 (roles/logging.viewer) - 要查看建構作業記錄的主體

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

管理員或許也能透過自訂角色或其他預先定義的角色，授予必要權限。

注意： 將「擁有者」(roles/owner) 或「編輯者」(roles/editor) 角色授予專案，主體也能從預設 bucket 查看建構記錄。不過，如要在預設 Cloud Storage 值區中查看建構記錄，建議使用「檢視者」角色，確保角色指派作業符合最低權限安全原則。

注意： 如要避免授予基本「檢視者」角色，請將建構記錄儲存在使用者指定的值區中。如果建構作業是由觸發程序叫用，且您只希望授予叫用建構作業和查看建構進度的權限，則特別建議採用這個做法。

在 Google Cloud中查看建構作業記錄

控制台

1. 在 Google Cloud 控制台中開啟 Cloud Build 頁面。

   開啟 Cloud Build 頁面

2. 選取您的專案並按一下 [Open] (開啟)。

3. 在「Region」(區域) 下拉式選單中，選取建構作業的區域。

4. 在「Build history」(建構歷史記錄) 頁面中，選取特定建構。

5. 在「Build details」(建構作業詳細資料) 頁面的「Steps」(步驟) 下方，按一下「Build summary」(建構作業摘要)，即可查看整個建構作業的建構記錄，或是選取建構步驟來查看該步驟的建構記錄。

6. 如果記錄檔儲存在 Cloud Logging 中，請在「建構記錄」面板中點選 圖示，即可在 Logs Explorer 中查看記錄。

gcloud

執行 gcloud builds log 指令，其中 build-id 是您要取得建構記錄的建構 ID。執行 gcloud builds submit 時，建構 ID 會顯示在建構提交程序結束時，執行 gcloud builds list 時則會顯示在 ID 欄中。

gcloud builds log build-id

在 GitHub 和 GitHub Enterprise 中查看建構記錄

如果您使用 gcloud CLI 或 Cloud Build API 建立 GitHub 或 GitHub Enterprise 觸發條件，並指定 --include-logs-with-status 做為選項，則可以在 GitHub 和 GitHub Enterprise 中查看建構記錄。

如要在 GitHub 和 GitHub Enterprise 中查看建構作業記錄，請按照下列步驟操作：

1. 前往與觸發條件相關聯的存放區。

2. 前往提交清單。

3. 找到要查看建構記錄的修訂版本資料列。

4. 按一下該提交所在列的結果圖示。

   系統會列出與提交內容相關的檢查。

5. 找出要查看建構記錄的資料列，然後按一下「詳細資料」。

   您會看到與認可相關聯的「摘要」頁面。 如果您使用 --include-logs-with-status 旗標建立觸發條件，頁面的「詳細資料」部分下方會顯示建構記錄。

注意： 用於觸發程序的服務帳戶必須包含 roles/logging.viewer 角色，才能將建構記錄傳送至 GitHub。

刪除建構記錄和值區

為確保 具備必要權限，能刪除 Cloud Storage 中的建構記錄和值區，請要求管理員在用於建構的服務帳戶中，授予 下列 IAM 角色：

• 刪除使用者建立或擁有的 Cloud Storage 值區中的建構記錄： Storage Admin (roles/storage.admin) - 刪除建構記錄的使用者或服務帳戶
• 刪除使用者建立或擁有的 Cloud Storage bucket： Storage 管理員 (roles/storage.admin) - 刪除 bucket 的使用者或服務帳戶
• 刪除使用者建立的記錄檔儲存空間： 記錄檔設定寫入者 (roles/logging.configWriter) - 您的專案

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

管理員或許也能透過自訂角色或其他預先定義的角色，授予必要權限。

如要刪除使用者建立或擁有的 Cloud Storage bucket 中的建構記錄，請按照 Cloud Storage 說明文件中的「刪除物件」一節操作。

如要刪除使用者建立或擁有的 Cloud Storage bucket，請按照 Cloud Storage 說明文件中的「刪除 bucket」一節操作。

如要刪除使用者建立的記錄 bucket，請按照 Logging 說明文件中的「刪除 bucket」一節操作。

後續步驟

• 瞭解 Cloud Build 建立的稽核記錄。
• 瞭解如何查看建構結果。
• 進一步瞭解 Cloud Build 身分與存取權管理權限。