使用使用者管理的服務帳戶執行建構作業

本文說明如何設定建構作業，以使用使用者管理的服務帳戶。

如未指定建構作業的使用者管理服務帳戶，Cloud Build 會自動使用預設的 Cloud Build 服務帳戶。這個預設服務帳戶可能具備不必要的廣泛權限，例如存取 Cloud Source Repositories 和專案中的任何 Cloud Storage bucket。

建議您遵循最小權限原則，將權限和角色指派給服務帳戶，並將範圍限定在服務帳戶執行的工作。舉例來說，您可以透過一個服務帳戶，將映像檔建構及推送至 Artifact Registry，如Google Cloud 這篇網誌所示。

事前準備

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

  啟用 API 時所需的角色

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

  啟用 API

• 如果您打算使用這個帳戶建立及管理憑證 (例如建立短期憑證)，請啟用 IAM Service Account Credentials API。

  啟用 API 時所需的角色

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

  啟用 API

• 如果尚未建立服務帳戶，請建立一個。

設定服務帳戶

將 IAM 角色授予使用者管理的服務帳戶，讓該帳戶具備執行建構作業所需的權限。您也可以設定 Cloud Build，讓系統自動為新觸發條件選擇這個服務帳戶。

1. 前往 Google Cloud 控制台的 settings「Cloud Build Permissions」(Cloud Build 權限) 頁面：

   前往「權限」

2. 前往「服務帳戶」選單，然後選取您的服務帳戶。如要選擇其他專案中的服務帳戶，請按一下「切換專案」。

3. 如要將所選服務帳戶設為新觸發條件的服務帳戶，請開啟「設為新觸發條件的預先選取服務帳戶」。

4. 在 Google Cloud 服務清單中，啟用要授予服務帳戶的 IAM 角色。

5. 如果建構管道所需的角色未列於此處，您可以在 IAM 設定頁面中授予其他角色。

6. 如果您選取其他專案的服務帳戶，請完成「跨專案設定」中的步驟。

如要進一步瞭解建構作業通常需要的 IAM 角色，請參閱下列資訊：

• 預設 Cloud Build 服務帳戶。
• 設定 Cloud Build 資源的存取權。
• Cloud Build IAM 角色和權限。

設定建構記錄

為建構作業指定自己的服務帳戶時，您必須將建構記錄儲存在下列其中一種 bucket 類型中：

• 使用者專案中的 Cloud Storage bucket。這些值區可以是使用者建立的值區，也可以是Google Cloud建立並由使用者擁有的值區。

• Cloud Logging 值區。

如果您建立記錄檔 bucket，請務必不要設定保留政策，否則 Cloud Build 可能無法將建構記錄寫入 bucket。

您無法將記錄檔儲存在 Google Cloud擁有的記錄檔值區中。

如要進一步瞭解建構記錄的儲存位置，請參閱「建構記錄儲存選項」。

使用設定檔執行建構作業

如要使用設定檔手動執行建構作業，請按照下列步驟操作：

1. 在專案根目錄中，建立名為 cloudbuild.yaml 或 cloudbuild.json 的 Cloud Build 建構設定檔。

2. 新增 serviceAccount 欄位和偏好的記錄設定。

   • 如要將建構記錄儲存在 Cloud Logging 中，請新增 logging 欄位，並將該欄位的值設為 CLOUD_LOGGING_ONLY。

   • 如果將建構作業記錄儲存在使用者建立的 Cloud Storage bucket 中：

     • 新增 logging 欄位，並將值設為 GCS_ONLY。
     • 新增 logsBucket 欄位，並將值設為 Cloud Storage bucket 位置。

   以下範例會設定 Cloud Build，使用使用者管理的服務帳戶執行建構作業，並將建構記錄儲存在使用者建立的 Cloud Storage bucket 中：

   YAML

   steps:
   - name: 'bash'
     args: ['echo', 'Hello world!']
   logsBucket: 'LOGS_BUCKET_LOCATION'
   serviceAccount: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT'
   options:
     logging: GCS_ONLY
   

   JSON

   {
     "steps": [
     {
       "name": "bash",
       "args": [
         "echo",
         "Hello world!"
       ]
     }
     ],
     "logsBucket": "LOGS_BUCKET_LOCATION",
     "serviceAccount": "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT",
     "options": {
       "logging": "GCS_ONLY"
     }
   }
   
   

   將建構設定檔中的變數替換為下列項目：

   • LOGS_BUCKET_LOCATION 是用來儲存建構記錄的 Cloud Storage bucket。例如：gs://mylogsbucket。
   • PROJECT_ID 是執行建構作業的 Google Cloud 專案 ID。
   • SERVICE_ACCOUNT 是要為建構作業指定的服務帳戶電子郵件地址或專屬 ID。舉例來說，服務帳戶的電子郵件地址如下： service-account-name@project-id.iam.gserviceaccount.com。

3. 使用建構設定檔展開建構作業：

   gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
   

   將指令中的變數替換為下列值：

   • CONFIG_FILE_PATH 是建構設定檔的路徑。
   • SOURCE_DIRECTORY 是原始碼的路徑或網址。

   如果您未在 gcloud builds submit 指令中指定 CONFIG_FILE_PATH 和 SOURCE_DIRECTORY，Cloud Build 會假設建構設定檔和原始碼位於目前的工作目錄中。

使用觸發條件執行建構作業

如要使用自己的服務帳戶，透過 Cloud Build 觸發條件執行建構作業，請設定偏好的記錄選項，並在建立觸發條件時選取偏好的服務帳戶。

如要為所有新觸發條件使用相同的服務帳戶，可以設定 Cloud Build 自動選取服務帳戶。

1. 在建構設定檔中：

   • 如要將建構記錄儲存在 Cloud Logging 中，請新增 logging 欄位，並將該欄位的值設為 CLOUD_LOGGING_ONLY。

   • 如果將建構作業記錄儲存在使用者建立的 Cloud Storage bucket 中：

     • 新增 logging 欄位，並將值設為 GCS_ONLY。
     • 新增 logsBucket 欄位，並將值設為 Cloud Storage bucket 位置。

   以下範例會設定將建構記錄儲存在使用者建立的 Cloud Storage bucket 中：

   YAML

   steps:
   - name: 'bash'
     args: ['echo', 'Hello world!']
   logsBucket: 'LOGS_BUCKET_LOCATION'
   options:
     logging: GCS_ONLY
   

   JSON

   {
     "steps": [
     {
       "name": "bash",
       "args": [
         "echo",
         "Hello world!"
       ]
     }
     ],
     "logsBucket": "LOGS_BUCKET_LOCATION",
     "options": {
       "logging": "GCS_ONLY"
     }
   }
   

   將 LOGS_BUCKET_LOCATION 替換為用於儲存建構作業記錄的 Cloud Storage bucket。例如：gs://mylogsbucket。

2. 指定要用於自動建構觸發條件的服務帳戶：

   控制台

   1. 建立或編輯自動建構觸發條件。

   2. 在「服務帳戶」欄位中，指定您的服務帳戶。如要選擇其他專案中的服務帳戶，請按一下「切換專案」。

      如未指定服務帳戶，Cloud Build 會使用預設服務帳戶。

   3. 按一下「建立」來儲存自動建構觸發條件。

   gcloud

   建立自動建構觸發條件時，請使用 --service-account 旗標指定服務帳戶。在下列範例中，gcloud 指令會建立自動建構觸發條件，從 Git 存放區提取程式碼：

   gcloud builds triggers create github \
      --name=TRIGGER_NAME \
      --repo-name=REPO_NAME \
      --repo-owner=REPO_OWNER \
      --branch-pattern=BRANCH_PATTERN
      --build-config=BUILD_CONFIG_FILE
      --service-account=SERVICE_ACCOUNT
      --project=BUILD_PROJECT
   

   將建構設定檔中的變數替換為下列值：

   • TRIGGER_NAME 是自動建構觸發條件的名稱。
   • REPO_NAME 是存放區的名稱。
   • REPO_OWNER 是存放區擁有者的使用者名稱。
   • BRANCH_PATTERN 是存放區中的分支名稱，用於叫用建構作業。
   • TAG_PATTERN 是存放區中的標記名稱，用於叫用建構作業。
   • BUILD_CONFIG_FILE 是建構設定檔的路徑。
   • SERVICE_ACCOUNT 是您的服務帳戶，格式為 /projects/PROJECT_ID/serviceAccounts/ACCOUNT_ID_OR_EMAIL。
   • BUILD_PROJECT 是您要開始建構的專案。

跨專案設定

只有在iam.disableCrossProjectServiceAccountUsage機構政策限制未強制執行時，您才能使用使用者管理的服務帳戶，在與建立服務帳戶的專案不同的專案中執行建構作業。這項限制預設會強制執行。 瞭解詳情。

• 下列指令會停用該限制的強制執行，並授予必要存取權。貴機構必須先瞭解相關安全權衡取捨，再於組織政策中設定限制條件：

  gcloud resource-manager org-policies disable-enforce \
     iam.disableCrossProjectServiceAccountUsage \
     --project=SERVICE_ACCOUNT_PROJECT_ID
  

  在這個指令中，SERVICE_ACCOUNT_PROJECT_ID 是包含使用者自行管理的服務帳戶的專案

• 在具有使用者管理服務帳戶的專案中，針對您執行建構作業的專案，將 roles/iam.serviceAccountTokenCreator 角色授予 Cloud Build 服務代理：

  gcloud projects add-iam-policy-binding SERVICE_ACCOUNT_PROJECT_ID \
      --member="serviceAccount:BUILD_SERVICE_AGENT" \
      --role="roles/iam.serviceAccountTokenCreator"
  

  將指令中的變數替換為下列內容：

  • SERVICE_ACCOUNT_PROJECT_ID：包含使用者管理服務帳戶的專案 ID。
  • BUILD_SERVICE_AGENT：服務代理程式的電子郵件 ID，格式為 service-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com，其中 BUILD_PROJECT_NUMBER 是您執行建構作業的專案專案編號。您可以在專案設定頁面取得專案編號。

限制：

• Google Cloud 專案必須位於 Google Cloud 機構中。

• 您必須使用 gcloud builds submit 或 gcloud builds triggers create，在指令列中啟動建構作業。

後續步驟

• 進一步瞭解 Cloud Build IAM 角色和權限。
• 瞭解服務帳戶異動對建構作業的影響。