設定使用者指定的服務帳戶

如要在 Cloud Build 中遵循最小權限原則，您可以將 Cloud Build 設為使用具備足夠權限的服務帳戶來執行建構作業。本頁面說明如何設定服務帳戶。

如未指定服務帳戶，Cloud Build 可能會自動選取服務帳戶，代表您執行建構作業。這個服務帳戶可能具備不必要的廣泛權限，例如存取 Cloud Source Repositories 和專案中的任何 Cloud Storage bucket。

為提升專案的安全性，並降低設定錯誤或惡意使用者可能造成的影響，建議您遵循最低權限原則。採用這項原則後，您就能為每個服務帳戶指派權限和角色，範圍限定在該帳戶執行的工作。舉例來說，您可以如Google Cloud 這篇網誌所示，使用一個服務帳戶建構映像檔並推送至 Artifact Registry。

事前準備

• 啟用 Cloud Build 和 IAM API。

  啟用 API 時所需的角色

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

  啟用 API

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

  啟用 API 時所需的角色

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

  啟用 API

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

授予 IAM 權限

如要允許建構作業存取連線所需的服務，您必須授予某些角色和權限：

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

   前往「權限」

2. 前往「服務帳戶」選單，然後選取服務帳戶。

3. 將要新增的角色狀態設為「啟用」。

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

如要進一步瞭解建構作業常用的角色，請參閱「設定 Cloud Build 資源的存取權」一文，以及 Cloud Build IAM 角色和權限的完整清單。

設定建構作業記錄檔

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

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

• Cloud Logging 值區。

如果您建立記錄檔 bucket，請確認該 bucket 沒有保留政策，否則 Cloud Build 可能無法將建構記錄寫入 bucket。

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

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

使用設定檔執行建構作業

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

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

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

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

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

     • 新增 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 觸發條件執行建構作業，請設定偏好的記錄選項，並在建立觸發條件時選取偏好的服務帳戶。

1. 在建構設定檔中：

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

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

     • 新增 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 值區。例如：gs://mylogsbucket。

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

   控制台

   如要使用 Google Cloud 控制台的「觸發條件」頁面執行建構作業，使用者指定的服務帳戶必須與建構觸發條件位於同一個專案。如要搭配使用自動建構觸發條件與跨專案服務帳戶，請使用 gcloud 工具建立自動建構觸發條件。

   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，在指令列中啟動建構作業。如要在 Google Cloud 控制台中使用「觸發程序」頁面，使用者指定的服務帳戶和自動建構觸發條件必須位於同一個專案中。

後續步驟

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