Running builds in a private pool

This document explains how to run builds in private pools. If you're new to private pools, read the Private pools overview.

Before you begin

  • Make sure you've created a private pool using the steps in Creating and managing private pools.

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

  • You can either use the same Cloud project to create your private pool and your Cloud Build builds or use different projects. If your builds are in a different project from your private pool, set the default project in the gcloud tool to the project where your builds originate:

    gcloud config set project BUILD_ORIGIN_PROJECT_ID
    

IAM permissions

  • To run builds via the gcloud tool or the Cloud Build API, grant the WorkerPool User role in the private pool project to the user or service account that requests the build.

  • To run automated builds using triggers:

    • If the project in which you're starting the build is the same as the project in which your private pool exists, you don't need to grant any permissions.
    • If the project in which you're starting the build is different from the project in which your private pool exists, grant the WorkerPool User role to the Cloud Build service account in the project where your builds are created.

For instructions on granting IAM roles, see IAM roles and permissions.

Running builds

You can submit builds from the same Cloud project where you created the private pool or from a different Cloud project. You can specify the private pool either in your build config file or direcly in the gcloud command:

Specifying the private pool in the build config file:

  1. In your Cloud Build config file, add a pool option and specify the full resource name of the worker pool to run the build:

    YAML

    steps:
    - name: 'bash'
      args: ['echo', 'I am running in a private pool!']
    options:
      pool:
        name: 'projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID'
    

    JSON

    {
      "steps": [
      {
        "name": "bash",
        "args": [
          "echo",
          "I am running in a private pool!"
        ]
      }
      ],
      "options": {
        "pool" : {
          "name" : "projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID"
        }
      }
    }
    

    Replace the placeholder values in the config file above with the following:

    • WORKERPOOL_PROJECT_ID: the Cloud project where your private pool is located.
    • REGION: the region where you created your private pool.
    • WORKERPOOL_ID: the unique workerpool ID that you specified when creating the private pool.
  2. Use the build config file created above to run your build via gcloud or API or using triggers.

Specifying the private pool in the gcloud command:

You can specify the private pool in the gcloud command instead of in the build config file. For example, consider you have the following build config file:

YAML

  steps:
  - name: 'bash'
    args: ['echo', 'I am running in a private pool!']

JSON

  {
    "steps": [
    {
      "name": "bash",
      "args": [
        "echo",
        "I am running in a private pool!"
      ]
    }
    ],
  }

The following command builds using the build config file and specifies the worker pool in the command:

gcloud builds submit --config=CONFIG_FILE
  --worker-pool=projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID

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

  • CONFIG_FILE: path to your build config file.
  • WORKERPOOL_ID: the unique workerpool ID that you specified when creating the private pool.
  • WORKERPOOL_PROJECT_ID: the Cloud project where your private pool is located.
  • REGION: the region where you created your private pool.

What's next?