Creating and managing private pools

This page describes how to create, update, view, and delete Cloud Build private pools. If you're not familiar with private pools, read Private pools overview.

Before you begin

  1. Create a new Cloud project or choose an existing project. You'll use this project to create the private pool.

  2. Enable the Cloud Build API.

    Enable the API

  3. To use the command-line examples in this guide, install and configure the Cloud SDK.

  4. [Optional] For builds to access private resources from your Virtual Private Cloud network, you must set up a peering connection between your Virtual Private Cloud network and the Virtual Private Cloud network where private pools reside. For instructions, see set up your environment to create private pools.

Creating a new private pool

IAM permissions: You require Cloud Build WorkerPool Owner role to perform this task. For instructions on granting this role, see Configure access to Cloud Build resources.

You can create up to 10 private pools per Cloud project per region. To create a new private pool:

Console

  1. Open the Worker Pool page in the Google Cloud Console:

    Open the Cloud Build worker pool page

  2. Select the project where you want to create the private pool.

  3. In the Worker pool page, click Create.

  4. In the Create private pool side panel:

    1. Enter a name for your private pool. This value should be 1-63 characters, and valid characters are /[a-z][0-9]-/.

    2. Select the region in which you want the private pool to be created.

    3. Select the Compute Engine machine type you want to use for your private pool.

    4. Enter a disk size for your private pool. Specify a value greater than or equal to 100 and less than or equal to 1000. If not provided, Cloud Build uses a disk size of 100.

    5. Enter the project number of the Cloud project where your Virtual Private Cloud network is located. If you leave this field blank, your private pool uses the service producer network. For information on the available network configuration options and implications, see Setting up your environment.

    6. Enter the name of your VPC network. If you leave this field blank, your private pool uses the service producer network. For information on the available network configuration options and implications, see Setting up your environment.

    7. Assign external IPs is selected by default. Selecting this option allows private pool to access the public internet.

    8. Click Create.

gcloud

You have two options for creating a new private pool using gcloud: you can either pass in your worker pool config file to the gcloud command, or pass the configuration options directly to the gcloud command.

Passing the worker pool config file to the gcloud command:

  1. Create the worker pool config file in the YAML or the JSON format.

  2. Run the following gcloud command, where WORKERPOOL_ID is a unique identifier for your custom worker pool, WORKERPOOL_CONFIG_FILE is the name of your worker pool config file, and REGION is the region where you want to create your worker pool:

    gcloud builds worker-pools create WORKERPOOL_ID --config-from-file WORKERPOOL_CONFIG_FILE --region REGION
    

    You should see an output similar to the following:

    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
    

Passing the configuration options directly to the gcloud command:

Run the following gcloud command:

    gcloud builds worker-pools create WORKERPOOL_ID \
        --project=WORKERPOOL_PROJECT_ID \
        --region=REGION \
        --peered-network=PEERED_NETWORK \
        --worker-machine-type=WORKERPOOL_MACHINE_TYPE \
        --worker-disk-size=WORKERPOOL_DISK_SIZE_GB \
        --no-public-egress

Replace the placeholder values in the above commands with the following:

  • WORKERPOOL_ID: a unique identifier for your private pool. This value should be 1-63 characters, and valid characters are [a-zA-Z0-9_-]+.
  • WORKERPOOL_PROJECT_ID: the ID of the Cloud project where you want to create your private pool.
  • REGION: one of the supported regions.
  • PEERED_NETWORK: the network resource URL of the network that is peered to the service producer network. PEERED_NETWORK must be of the format projects/NETWORK_PROJECT_ID/global/networks/NETWORK_NAME, where NETWORK_PROJECT_ID is the project ID of the Cloud project that holds your VPC network and NETWORK_NAME is the name of your VPC network. If you don't specify a value, Cloud Build uses the service provider network.
  • WORKERPOOL_DISK_SIZE_GB: the size of the disk attached to the private pool. Specify a value greater than or equal to 100 and less than or equal to 1000. If not provided, Cloud Build uses a disk size of 100. --worker-disk-size is overridden if you specify a different disk size using --disk-size during gcloud builds submit.
  • WORKERPOOL_MACHINE_TYPE: the machine type of the worker. If left blank, Cloud Build uses the default value of e2-standard-2. For a list of supported machine types, see Worker pool config file schema. --worker-machine-type is overridden if you specify a different machine type using --machine-type during gcloud builds submit.
  • --no-public-egress: If this flag is set, the private pool is created without an external IP address. Set this flag if you're creating the private pool within a VPC Service Controls perimeter.

API

  1. Create your worker pool config file named workerpool.json.

  2. Use cURL to call the 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/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/?workerPoolId=WORKERPOOL_ID -d @workerpool.json
    

    Replace the placeholder values in the above command with the following:

    • WORKERPOOL_PROJECT_ID: the ID of the Cloud project where you want to create your private pool.
    • WORKERPOOL_ID: the ID for your private pool. This value should be 1-63 characters, and valid characters are [a-zA-Z0-9_-]+.
    • REGION: one of the supported regions to create your worker pool.

Creating a private pool within a VPC Service Controls perimeter

If you're creating a private pool within a VPC Service Controls perimeter, see Using VPC Service Controls.

Updating a private pool

IAM permissions: You require Cloud Build WorkerPool Editor role to perform this task. For instructions on granting this role, see Configuring access to Cloud Build resources.

You can update the worker disk size and worker machine type of an existing private pool. To update a private pool:

Console

  1. Open the Worker pool page in the Google Cloud Console:

    Open the Cloud Build worker pool page

  2. Select the project in which you created the private pool.

  3. Click on the worker pool name.

  4. In the Edit private pool side panel, update the machine type and/or the disk size.

  5. Click Save.

gcloud

By updating the worker pool config file:

  1. Update the field you wish to change in your worker pool config file.

  2. Run the following command, where WORKERPOOL_ID is the unique identifier for your private pool and WORKERPOOL_CONFIG_FILE is the name of your worker pool config file:

    gcloud builds worker-pools update WORKERPOOL_ID --config-from-file=WORKERPOOL_CONFIG_FILE
    

By passing in the value to update directly to the gcloud builds worker-pools update command:

   gcloud builds worker-pools update WORKERPOOL_ID  \
    --worker-disk-size=WORKERPOOL_DISK_SIZE \
    --worker-machine-type=WORKERPOOL_MACHINE_TYPE

Replace the placeholder values in the above commands with the following:

  • WORKERPOOL_ID: the ID of your existing private pool. You cannot update this value; you must specify an existing worker pool ID.
  • WORKERPOOL_DISK_SIZE: the updated disk size.
  • WORKERPOOL_MACHINE_TYPE is the updated machine type.

API

  1. In your worker pool config file, update the worker disk size and/or worker machine type.

  2. Use cURL to call the Cloud Build API, replacing the variables with the appropriate values:

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

    Replace the placeholder values in the above command with the following:

    • WORKERPOOL_ID: the ID of your private pool.
    • WORKERPOOL_PROJECT_ID: the ID of the Cloud project that contains your private pool.
    • REGION: one of the supported regions to create your worker pool.

Viewing the details of your private pool

IAM permissions: You require Cloud Build WorkerPool Viewer role to perform this task. For instructions on granting this role, see Configuring access to Cloud Build resources.

To view the details of a private pool:

Console

  1. Open the Worker pool page in the Cloud Console:

    Open the Cloud Build worker pool page

  2. Select the project in which you created the private pool

  3. Click on the worker pool name.

The Edit private pool side panel is displayed, which has the details of the private pool.

gcloud

If you don't know the ID of your private pool, run the following command to list the details of your private pool:

gcloud builds worker-pools list --project=WORKERPOOL_PROJECT_ID

where WORKERPOOL_PROJECT_ID is the ID of the Cloud project that contains the private pool.

You should see an output similar to the following:

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

If you know your private pool ID, run the following command to get more information about the worker pool:

gcloud builds worker-pools describe \
    --project=WORKERPOOL_PROJECT_ID WORKERPOOL_ID

Replace the placeholder values in the above command with the following:

  • WORKERPOOL_ID: the ID of your private pool.
  • WORKERPOOL_PROJECT_ID: the ID of the Cloud project that contains your private pool.

API

If you don't know the ID of your private pool, run the following cURL command to list the details of your private pool, where WORKERPOOL_PROJECT_ID is the ID of the Cloud project that contains the private pool:

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

If you know your private pool ID, run the following cURL command to get the details of your private pool:

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

Replace the placeholder values in the above commands with the following:

  • WORKERPOOL_ID: the ID of your private pool.
  • WORKERPOOL_PROJECT_ID: the ID of the Cloud project that contains your private pool.
  • REGION: the region where you created your worker pool.

Deleting a worker pool

IAM permissions: You require Cloud Build WorkerPool Owner role to perform this task. For instructions on granting this role, see Configuring access to Cloud Build resources.

To delete a private pool:

Console

  1. Open the Worker pool page in the Cloud Console:

    Open the Cloud Build worker pool page

  2. In the row with your private pool, click the trash icon.

gcloud

To delete a private pool, run the gcloud builds worker-pools delete command:

 gcloud builds worker-pools delete WORKERPOOL_ID \
     --project=WORKERPOOL_PROJECT_ID

Replace the placeholder values in the above command with the following:

  • WORKERPOOL_ID: the ID of your private pool.
  • WORKERPOOL_PROJECT_ID: the ID of the Cloud project that contains your private pool.

After the private pool is deleted, you should see an output similar to the following:

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

API

Use cURL to call the Cloud Build API:

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

Replace the placeholder values in the above commands with the following:

  • WORKERPOOL_ID: the ID of your private pool.
  • WORKERPOOL_PROJECT_ID: the ID of the Cloud project that contains your private pool.
  • REGION: the region where you created your worker pool.

What's next