建立及管理私人集區

本頁說明如何建立、更新、查看及刪除 Cloud Build 私有集區。如果您不熟悉私人集區，請參閱私人集區總覽。

事前準備

  1. 建立新 Google Cloud 專案或選擇現有專案。您將使用這個專案建立私人集區。

  2. Enable the Cloud Build API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  3. 如要使用本指南提供的指令列範例，請安裝及設定 Google Cloud CLI。

  4. 選用：如要讓建構作業存取虛擬私有雲網路中的私人資源，您必須在虛擬私有雲網路與私人集區所在的虛擬私有雲網路之間，設定對等互連連線。如需操作說明，請參閱設定環境來建立私人集區。

  5. 選用：熟悉機型設定和區域可用性。詳情請參閱私人集區設定檔結構定義說明文件中的workerconfig。

建立私人集區

如要取得建立私人集區所需的權限，請要求管理員授予您服務帳戶的「Cloud Build WorkerPool Owner」 (roles/cloudbuild.workerPoolOwner) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

每個專案在每個區域最多可建立 10 個私有集區。 Google Cloud 如要建立私人集區，請執行下列步驟：

Google Cloud 控制台

  1. 在 Google Cloud 控制台中開啟「Worker Pool」(工作站集區) 頁面：

    開啟 Cloud Build 工作站集區頁面

  2. 按一下「建立私人集區」。

    系統隨即會顯示「Create private pool」(建立私人集區) 頁面。

    輸入下列資訊來建立私人集區：

  3. 名稱：輸入私人集區的名稱。這個值只能包含英數字元 /[a-z][0-9]/ 或連字號 -。私人集區名稱長度必須介於 1 至 63 個字元之間。

  4. 地區：選取要建立私人集區的地區。

  5. 「機器設定」：設定下列項目：

    1. 系列：選擇機器系列。

    2. 機器類型：這項設定會根據您選取的機器系列，顯示工作站集區可使用的機器類型。可用的機器類型因地區而異。

    3. 磁碟大小：輸入私人集區的磁碟大小。 請指定大於或等於 100 且小於或等於 4000 的值。如未提供值，Cloud Build 會使用 100 的磁碟大小。

    4. 巢狀虛擬化：如果您選取 C3 系列機器，可以啟用巢狀虛擬化。 有了這項功能，您就能在其他虛擬機器 (VM) 中執行 VM 執行個體，自行建立虛擬化環境。

  6. 在「網路類型」下方，選取下列任一選項：

    1. 預設網路：如果可透過公開網際網路存取執行個體，請選取這個選項。選取「預設網路」選項後，私人集區會使用服務供應商網路。詳情請參閱「設定環境，在虛擬私有雲網路中使用私人集區」。

    2. 私人網路：如果執行個體託管於私人網路，請選取這個選項，然後執行下列操作：

      1. 專案：選取 Google Cloud 專案 ID。

      2. 網路：從下拉式選單中選取網路。如果您尚未建立網路，請參閱「建立及管理虛擬私有雲網路」，瞭解如何建立網路。

      3. IP 範圍：輸入 Cloud Build 生產者網路可使用的內部 IP 範圍，以便分配給與私人存放區維持連線的 VM。

        您可以使用無類別跨網域路由 (CIDR) 路由標記法指定範圍，格式為 STARTING_IP_ADDRESS/SUBNET_PREFIX_SIZE。舉例來說，192.0.2.0/24 的前置碼長度為 24。IP 範圍的前 24 個位元會做為子網路遮罩 (192.0.2.0)，而可能的主機位址範圍則介於 192.0.2.0 到 192.0.2.255 之間。

        前置字串長度值不得超過 /29。如未指定範圍值，系統會自動指派預設值 /24。如果未指定前置字元長度，系統會自動在對等互連的 VPC 網路中指派 IP 位址。如果未指定 IP 位址值，系統會自動在對等互連的 VPC 網路中指派 IP 位址範圍。

    3. 指派外部 IP： 預設會選取這個選項，允許私人集區存取公用網際網路。取消勾選這個方塊，即可限制存取私人網路。

  7. 按一下「建立」即可建立私人集區。

gcloud

您可以使用 gcloud 建立新的私人集區，方法有兩種：將私人集區設定檔傳送至 gcloud 指令，或將設定選項直接傳送至 gcloud 指令。

將私人集區設定檔傳遞至 gcloud 指令：

  1. 以 YAML 或 JSON 格式建立私有集區設定檔。

  2. 執行下列 gcloud 指令，其中 PRIVATEPOOL_ID 是私人集區的不重複 ID，PRIVATEPOOL_CONFIG_FILE 是私人集區設定檔的名稱，而 REGION 是要建立私人集區的區域：

    gcloud builds worker-pools create PRIVATEPOOL_ID --config-from-file PRIVATEPOOL_CONFIG_FILE --region REGION

    畫面會顯示類似以下的輸出：

    Created [https://cloudbuild.googleapis.com/v1/projects/gcb-docs-project/locations/us-central1/workerPools/private-pool].
NAME                 CREATE_TIME                STATUS
private-pool  2018-11-19T16:08:24+00:00  RUNNING

將設定選項直接傳送給 gcloud 指令：

執行下列 gcloud 指令：

    gcloud builds worker-pools create PRIVATEPOOL_ID \
        --project=PRIVATEPOOL_PROJECT_ID \
        --region=REGION \
        --peered-network=PEERED_NETWORK \
        --worker-machine-type=PRIVATEPOOL_MACHINE_TYPE \
        --worker-disk-size=PRIVATEPOOL_DISK_SIZE_GB \
        --no-public-egress

其中：

  • PRIVATEPOOL_ID：私人集區的專屬 ID。 這個值的長度應為 1 至 63 個字元，有效字元為 [a-zA-Z0-9_-]+。
  • PRIVATEPOOL_PROJECT_ID：您要建立私有集區的 Google Cloud 專案 ID。
  • REGION：支援的區域之一。
  • PEERED_NETWORK：與服務供應商網路對等互連的網路資源網址。PEERED_NETWORK 必須採用 projects/NETWORK_PROJECT_ID/global/networks/NETWORK_NAME 格式，其中 NETWORK_PROJECT_ID 是保存虛擬私有雲網路的專案 ID， Google Cloud 是虛擬私有雲網路的名稱。NETWORK_NAME如未指定值，Cloud Build 會使用服務供應商網路。
  • PRIVATEPOOL_DISK_SIZE_GB：連結至私有集區的磁碟大小。請指定大於或等於 100 且小於或等於 4000 的值。如未提供，Cloud Build 會使用 100 的磁碟大小。如果您在 gcloud builds submit 期間使用 --disk-size 指定不同的磁碟大小，則會覆寫 --worker-disk-size。
  • PRIVATEPOOL_MACHINE_TYPE：工作站的機器類型。如果留空，Cloud Build 會使用 e2-standard-2 的預設值。如需支援的機器類型清單，請參閱「私人集區設定檔結構定義」。如果您在 gcloud builds submit 期間使用 --machine-type 指定不同的機器類型，則會覆寫 --worker-machine-type。
  • --no-public-egress：如果設定這個旗標，系統會建立沒有外部 IP 位址的私人集區。如果您要在 VPC Service Controls 範圍內建立私人集區，請設定這個旗標。

API

  1. 建立名為 workerpool.json 的私人集區設定檔。

  2. 請使用 cURL 呼叫 Cloud Build API：

        curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)"
        -H "Content-Type: application/json" \
        https://cloudbuild.googleapis.com/v1/projects/PRIVATEPOOL_PROJECT_ID/locations/REGION/workerPools/?workerPoolId=PRIVATEPOOL_ID -d @workerpool.json

    其中：

    • PRIVATEPOOL_PROJECT_ID：您要建立私有集區的 Google Cloud 專案 ID。
    • PRIVATEPOOL_ID：私人集區的 ID。這個值的長度應為 1 至 63 個字元，有效字元為 [a-zA-Z0-9_-]+。
    • REGION：建立私人集區的支援區域。

在 VPC Service Controls 範圍內建立私人集區

如要建立具有 VPC Service Controls 範圍的私人集區，請參閱「使用 VPC Service Controls」。

更新私人集區

如要取得建立私人集區所需的權限，請要求管理員在服務帳戶中授予 Cloud Build WorkerPool 編輯者 (roles/cloudbuild.workerPoolEditor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

如要更新私人集區的設定，請執行下列步驟：

主控台

  1. 在 Google Cloud 控制台中開啟「Worker pool」(工作站集區) 頁面：

    開啟 Cloud Build 工作站集區頁面

  2. 選取您建立私人集區的專案。

  3. 按一下私人集區名稱。

  4. 在「編輯私人集區」頁面中，視需要更新機型和磁碟大小。

  5. 按一下 [儲存]。

gcloud

透過更新私人集區設定檔：

  1. 在私人集區設定檔中更新要變更的欄位。

  2. 執行下列指令，其中 PRIVATEPOOL_ID 是私人集區的不重複 ID，REGION 是私人集區所在的區域，PRIVATEPOOL_CONFIG_FILE 是私人集區設定檔的名稱：

    gcloud builds worker-pools update PRIVATEPOOL_ID \
    --region=REGION \
    --config-from-file=PRIVATEPOOL_CONFIG_FILE

透過將要更新的值直接傳送給 gcloud builds worker-pools update 指令：

   gcloud builds worker-pools update PRIVATEPOOL_ID \
       --region=REGION \
       --worker-disk-size=PRIVATEPOOL_DISK_SIZE \
       --worker-machine-type=PRIVATEPOOL_MACHINE_TYPE

其中：

  • PRIVATEPOOL_ID：現有私人集區的 ID。您無法更新這個值，必須指定現有的私人集區 ID。
  • REGION：建立私人集區的區域。
  • PRIVATEPOOL_DISK_SIZE：更新後的磁碟大小。
  • PRIVATEPOOL_MACHINE_TYPE 是更新後的機器類型。

API

  1. 在私人集區設定檔中，視需要更新磁碟大小和機器類型。

  2. 請使用 cURL 呼叫 Cloud Build API，並以適當的值取代變數：

    curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://cloudbuild.googleapis.com/v1/projects/PRIVATEPOOL_PROJECT_ID/locations/REGION/workerPools/PRIVATEPOOL_ID \
    -d @workerpool.json

    其中：

    • PRIVATEPOOL_ID：私人集區的 ID。
    • PRIVATEPOOL_PROJECT_ID：包含私人集區的 Google Cloud 專案 Google Cloud ID。
    • REGION：建立私人集區的區域。

查看私人集區的詳細資料

如要取得建立私人集區所需的權限，請要求管理員授予服務帳戶「Cloud Build WorkerPool 檢視者」 (roles/cloudbuild.workerPoolViewer) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

如要查看私有集區的詳細資料：

主控台

  1. 在 Google Cloud 控制台中開啟「Worker pool」(工作站集區) 頁面：

    開啟 Cloud Build 工作站集區頁面

  2. 選取您建立私人群組的專案

  3. 按一下私人集區名稱。

    系統會顯示「編輯私人集區」頁面。

gcloud

如果您不知道私人集區的 ID，請執行下列指令來列出私人集區的詳細資料：

gcloud builds worker-pools list --region=REGION --project=PRIVATEPOOL_PROJECT_ID

其中：

  • PRIVATEPOOL_PROJECT_ID 是包含私有集區的Google Cloud 專案 ID。
  • REGION 是私人集區的區域。

畫面會顯示類似以下的輸出：

NAME                                                                  CREATE_TIME                STATUS
projects/[PRIVATEPOOL_PROJECT_ID]/locations/us-central1/workerPools/[PRIVATEPOOL_ID]      2018-11-19T16:08:24+00:00  RUNNING

如果您知道私人集區 ID，請執行下列指令，進一步瞭解私人集區：

gcloud builds worker-pools describe PRIVATEPOOL_ID \
    --region=REGION \
    --project=PRIVATEPOOL_PROJECT_ID

地點

  • PRIVATEPOOL_ID：私人集區的 ID。
  • REGION：建立私人集區的區域。
  • PRIVATEPOOL_PROJECT_ID：包含私人集區的 Google Cloud 專案 Google Cloud ID。

API

如果您不知道私人集區的 ID，請執行下列 cURL 指令，列出私人集區的詳細資料，其中 PRIVATEPOOL_PROJECT_ID 是包含私人集區的專案 ID： Google Cloud 

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        https://cloudbuild.googleapis.com/v1/projects/PRIVATEPOOL_PROJECT_ID/locations/REGION/workerPools

如果您知道私人集區 ID，請執行下列 curl 指令來取得私人集區的詳細資料：

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        https://cloudbuild.googleapis.com/v1/projects/PRIVATEPOOL_PROJECT_ID/locations/REGION/workerPools/PRIVATEPOOL_ID

地點

  • PRIVATEPOOL_ID：私人集區的 ID。
  • PRIVATEPOOL_PROJECT_ID：包含私人集區的 Google Cloud 專案 Google Cloud ID。
  • REGION：您建立私人集區的區域。

查看私人集區的預估價格

建立或更新私人集區時，「建立私人集區」和「編輯私人集區」頁面上的「每月預估」側欄會顯示集區每月預估的執行費用。計算時會考量下列因素：

  • 虛擬 CPU 數量
  • 機型
  • 記憶體
  • 建構分鐘數
  • 區域 (僅適用於 N2D 和 C3 機器)

預估價格不含超過預設 100 GB 的額外磁碟大小費用。預估價格可能與最終價格不同，具體取決於最終建構設定、實際使用的建構分鐘數和其他因素。詳情請參閱 Cloud Build 定價。

刪除私人集區

如要取得建立私人集區所需的權限，請要求管理員授予您服務帳戶的「Cloud Build WorkerPool Owner」 (roles/cloudbuild.workerPoolOwner) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

如要刪除私人集區，請按照下列步驟操作：

主控台

  1. 在 Google Cloud 控制台中開啟「Worker pool」(工作站集區) 頁面：

    開啟 Cloud Build 工作站集區頁面

  2. 在您的私人集區那一列中，點選「垃圾桶」圖示。

gcloud

如要刪除私人集區，請執行 gcloud builds worker-pools delete 指令：

 gcloud builds worker-pools delete PRIVATEPOOL_ID \
     --region=REGION \
     --project=PRIVATEPOOL_PROJECT_ID

其中：

  • PRIVATEPOOL_ID：私人集區的 ID。
  • PRIVATEPOOL_PROJECT_ID：包含私人集區的 Google Cloud 專案 Google Cloud ID。
  • REGION：您建立私人集區的區域。

刪除私人集區後，畫面會顯示類似以下的輸出：

 Deleted [https://cloudbuild.googleapis.com/v1/projects/gcb-docs-project/locations/us-central1/workerPools/[PRIVATEPOOL_ID].

API

請使用 cURL 呼叫 Cloud Build API：

  curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      https://cloudbuild.googleapis.com/v1/projects/PRIVATEPOOL_PROJECT_ID/locations/REGION/workerPools/PRIVATEPOOL_ID

其中：

  • PRIVATEPOOL_ID：私人集區的 ID。
  • PRIVATEPOOL_PROJECT_ID：包含私人集區的 Google Cloud 專案 Google Cloud ID。
  • REGION：您建立私人集區的區域。

後續步驟