Private pool configuration file schema

A private pool configuration file (private pool config file) contains instructions for Cloud Build to create a private pool based on your specifications. A private pool config file contains information such as the disk size and machine type you want to use for your private pool. The private pool config file is required when you create and manage private pools using the gcloud tool or the Cloud Build API.

Structure of a private pool config file

You can write the private pool config file using the YAML or the JSON syntax. To create and manage private pools using curl, write the private pool config file in the JSON format. To create and manage private pools using the gcloud tool, write the private pool config file in the YAML or the JSON format.

A private pool config file has the following structure:

privatePoolV1Config:
  networkConfig:
    egressOption: NO_PUBLIC_EGRESS
    peeredNetwork: 'PEERED_NETWORK'
    peeredNetworkIpRange: 'PEERED_NETWORK_IP_RANGE'
  workerConfig:
    diskSizeGb: 'PRIVATE_POOL_DISK_SIZE'
    machineType: PRIVATE_POOL_MACHINE_TYPE

{
  "privatePoolV1Config": {
    "networkConfig": {
      "egressOption": "NO_PUBLIC_EGRESS",
      "peeredNetwork": "PEERED_NETWORK",
      "peeredNetworkIpRange": "PEERED_NETWORK_IP_RANGE"
    },
    "workerConfig": {
      "diskSizeGb": "PRIVATE_POOL_DISK_SIZE",
      "machineType": "PRIVATE_POOL_MACHINE_TYPE"
    }
  }
}

The fields in the private pool config file are explained as follows:

networkConfig

This is an optional field. Specify networkConfig only if you're peering your VPC network with the service producer network.

egressOption

This is an optional field. Set the value of this field to NO_PUBLIC_EGRESS if you're creating your private pool within a VPC Service Controls perimeter. If you don't include this field in the private pool config file, public egress is enabled. For information on setting up VPC Service Controls for private pools, see Using VPC Service Controls.

peeredNetwork

This is a required field if your private pool config file contains the networkConfig field. Set the value of this field to the network resource URL of the VPC network that is peered to the service producer network. The network resource URL 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 producer network by default.

peeredNetworkIpRange

This is an optional field. Set the value of this field to specify the internal IP range that VMs can be assigned to within the peered network's allocated range. If the specified IP range can't be allocated within the range of the private connection, for example due to size limitations or an invalid starting IP, then the private pool can't be created.

peeredNetworkIpRange is specified using Classless Inter-Domain Routing (CIDR) notation in the format 'STARTING_IP/SUBNET_PREFIX_SIZE'. If this field is used, then SUBNET_PREFIX_SIZE must be specified. SUBNET_PREFIX_SIZE determines the size of the IP range. It must begin with a slash (/) and have a value less than or equal to 29.The STARTING_IP portion is optional, and specifies the starting address of the range. If the STARTING_IP is not specified, then a starting address is automatically assigned from within the private connection range. If no value is specified for peeredNetworkIpRange, a default value of /24 will be used which automatically assigns a starting IP with a range of 256 IPs.

The value of SUBNET_PREFIX_SIZE must not exceed 29. A larger number specifies a larger subnet prefix, which would leave fewer possible IPs and result in a smaller IP range. Since an IP address is 32 bits, a prefix size of /24 allows 256 possible IPs in the range (eight bits) whereas a prefix size of /29 leaves eight possible IPs (three bits). The maximum number of builder VMs is limited to the number of usable IPs in the range (the total possible number of IPs in the range minus two).

See the following for examples of the peeredNetworkIpRange field:

• 192.168.0.0/24 specifies an IP range starting at 192.168.0.0 with a subnet prefix size of 24 (256 IPs, with 254 usable IPs).
• /29 specifies a range with an automatically determined starting IP and a subnet prefix size of 29 (eight IPs, with six usable IPs).

workerConfig

This is a required field. It contains configuration options for your private pool.

diskSizeGb

This is an optional field. Use this field to specify a disk size for your private pool instance in GB. Specify a value greater than or equal to 100 and less than or equal to 4000. If you don't include this field in your private pool config file, or if you specify 0 as the value of this field, Cloud Build uses the default value of 100.

machineType

This is an optional field. Use this field to specify the Compute Engine machine type for your private pool instance. If you don't specify a value, then Cloud Build uses the default value of e2-medium. Otherwise, specify one of the following machine types:

The following table shows the availability of machine types by region:

enableNestedVirtualization

This is an optional field. If your private pool uses a VM with a C3 machine type, then you can enable nested virtualization to run other VM instances inside your private pool's VM. For more information, see About nested virtualization.

What's next

• Learn how to run builds in private pools.
• Learn how to create and manage private pools.