Create and manage 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

Create a new Google Cloud project or choose an existing project. You'll use this project to create the private pool.
Enable the Cloud Build API.
Enable the API
To use the command-line examples in this guide, install and configure the Google Cloud CLI.

Note: If you've installed gcloud CLI previously, make sure you have the latest available version by running gcloud components update.
[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 Google Cloud project per region. To create a new private pool:

Console

Open the Worker Pool page in the Google Cloud console:

Open the Cloud Build worker pool page
Select the project where you want to create the private pool.
In the Worker pool page, click Create.

You will see the Create private pool side panel.

Enter the following information to create your private pool:
1. Name: Enter a name for your private pool. This value can only contain alphanumeric characters /[a-z][0-9]/ or dashes -. The name of your private pool must be between 1 and 63 characters.
2. Region: Select the region in which you want the private pool to be created.
3. Machine type: Select the Compute Engine machine type you want to use for your private pool.
4. Available disk size: Enter a disk size for your private pool. Specify a value greater than or equal to 100 and less than or equal to 4000. If not provided, Cloud Build uses a disk size of 100.
  
  Under Network type, select one of the following options:
  1. Default network: Select this option if your instance is accessible via the public internet. When the Default network option is selected, your private pool uses the service producer network. For more information, see Set up environment to use private pools in a VPC network.
  2. Private network: Select this option if your instance is hosted on a private network.
    1. Project: Select your Google Cloud project ID.
    2. Network: Select your network from the drop-down menu. If you have not created a network, see Create and manage VPC networks to learn how to create a network.
    3. IP range: Enter the internal IP range that the Cloud Build producer network can use to allocate to VMs maintaining a connection with private repositories.
      
      You can specify the range using the Classless Inter-Domain Routing (CIDR) routing notation in the format STARTING_IP_ADDRESS/SUBNET_PREFIX_SIZE. For example, 192.0.2.0/24 has a prefix length of 24. The first 24 bits of the IP range are used as the subnet mask (192.0.2.0) while the possible hosts addresses range from 192.0.2.0 to 192.0.2.255.
      
      The value of your prefix length must not exceed /29. If no value is specified for the range, a default value of /24 is automatically assigned. If no value is specified for the prefix length, IP addresses are automatically assigned within the peered VPC network. If no value is specified for the IP address, the IP address is automatically assigned a range within the peered VPC network.
      
      Note: You can only specify an IP range if you've specified a Network. If you've specified a Network, the IP range is optional.
5. Assign external IPs: This option is selected by default to allow private pools to access the public internet. Uncheck this box to restrict access to your private network.
Click Create to create your private pool.

gcloud

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

Passing the private pool config file to the gcloud command:

Create the private pool config file in the YAML or the JSON format.

Run the following gcloud command, where PRIVATEPOOL_ID is a unique identifier for your private pool, PRIVATEPOOL_CONFIG_FILE is the name of your private pool config file, and REGION is the region where you want to create your private pool:

gcloud builds worker-pools create PRIVATEPOOL_ID --config-from-file PRIVATEPOOL_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 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

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

PRIVATEPOOL_ID: a unique identifier for your private pool. This value should be 1-63 characters, and valid characters are [a-zA-Z0-9_-]+.
PRIVATEPOOL_PROJECT_ID: the ID of the Google 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 Google 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.
PRIVATEPOOL_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 4000. 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.
PRIVATEPOOL_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 Private 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

Create your private pool config file named workerpool.json.
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/PRIVATEPOOL_PROJECT_ID/locations/REGION/workerPools/?workerPoolId=PRIVATEPOOL_ID -d @workerpool.json
```
Replace the placeholder values in the above command with the following:
- PRIVATEPOOL_PROJECT_ID: the ID of the Google Cloud project where you want to create your private pool.
- PRIVATEPOOL_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 private 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 disk size and machine type of an existing private pool. To update a private pool:

Console

Open the Worker pool page in the Google Cloud console:

Open the Cloud Build worker pool page
Select the project in which you created the private pool.
Click on the private pool name.
In the Edit private pool side panel, update the machine type and/or the disk size.
Click Save.

gcloud

By updating the private pool config file:

Update the field you wish to change in your private pool config file.
Run the following command, where PRIVATEPOOL_ID is the unique identifier for your private pool, REGION is the region where your private pool is located, and PRIVATEPOOL_CONFIG_FILE is the name of your private pool config file:
```
gcloud builds worker-pools update PRIVATEPOOL_ID \
    --region=REGION \
    --config-from-file=PRIVATEPOOL_CONFIG_FILE
```

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

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

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

PRIVATEPOOL_ID: the ID of your existing private pool. You cannot update this value; you must specify an existing private pool ID.
REGION: the region where you created your private pool.
PRIVATEPOOL_DISK_SIZE: the updated disk size.
PRIVATEPOOL_MACHINE_TYPE is the updated machine type.

API

In your private pool config file, update the disk size and/or machine type.
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/PRIVATEPOOL_PROJECT_ID/locations/REGION/workerPools/PRIVATEPOOL_ID \
    -d @workerpool.json
```
Replace the placeholder values in the above command with the following:
- PRIVATEPOOL_ID: the ID of your private pool.
- PRIVATEPOOL_PROJECT_ID: the ID of the Google Cloud project that contains your private pool.
- REGION: the region where you created your private 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

Open the Worker pool page in the Google Cloud console:

Open the Cloud Build worker pool page
Select the project in which you created the private pool
Click on the private 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=PRIVATEPOOL_PROJECT_ID

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

You should see an output similar to the following:

NAME                                                                  CREATE_TIME                STATUS
projects/[PRIVATEPOOL_PROJECT_ID]/locations/us-central1/workerPools/[PRIVATEPOOL_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 private pool:

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

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

PRIVATEPOOL_ID: the ID of your private pool.
REGION: the region where you created your private pool.
PRIVATEPOOL_PROJECT_ID: the ID of the Google 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 PRIVATEPOOL_PROJECT_ID is the ID of the Google Cloud project that contains the private pool:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        https://cloudbuild.googleapis.com/v1/projects/PRIVATEPOOL_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/PRIVATEPOOL_PROJECT_ID/locations/REGION/workerPools/PRIVATEPOOL_ID

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

PRIVATEPOOL_ID: the ID of your private pool.
PRIVATEPOOL_PROJECT_ID: the ID of the Google Cloud project that contains your private pool.
REGION: the region where you created your private pool.

Deleting a private 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

Open the Worker pool page in the Google Cloud console:

Open the Cloud Build worker pool page
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 PRIVATEPOOL_ID \
     --region=REGION \
     --project=PRIVATEPOOL_PROJECT_ID

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

PRIVATEPOOL_ID: the ID of your private pool.
PRIVATEPOOL_PROJECT_ID: the ID of the Google Cloud project that contains your private pool.
REGION: the region where you created 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/[PRIVATEPOOL_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/PRIVATEPOOL_PROJECT_ID/locations/REGION/workerPools/PRIVATEPOOL_ID

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

PRIVATEPOOL_ID: the ID of your private pool.
PRIVATEPOOL_PROJECT_ID: the ID of the Google Cloud project that contains your private pool.
REGION: the region where you created your private pool.

What's next

Learn how to run builds in private pools.
Learn how to use VPC Service Controls with private pools.