Building Cloud Functions Images


When you deploy your function's source code to Cloud Functions, that source is stored in a Cloud Storage bucket. Cloud Build then automatically builds your code into a container image and pushes that image to a image registry (either Container Registry or Artifact Registry). Cloud Functions accesses this image when it needs to run the container to execute your function.

The process of building the image is entirely automatic and requires no direct input from you. All the resources used in the build process execute in your own user project.

Executing the build process within your project means that:

  • You have direct access to all build logs.

  • There is no preset build-time quota, although Cloud Build does have its own default concurrency quota.

  • You can view the current container image and the previously deployed container image, both of which are stored in either Container Registry or Artifact Registry.

  • Because Cloud Storage is used directly in your project, the source code directory for your functions is visible, in a bucket named gcf-sources-<PROJECT_NUMBER>-<REGION>.

Characteristics of the build process

The build process has the following characteristics:

  • The Cloud Build API must be enabled for your project.

    To enable the API manually click the above link, select your project from the dropdown menu, and click Continue.

  • Because the entire build process takes place within the context of your project, the project is subject to the pricing of the included resources:

    • For Cloud Build pricing, see the Pricing page. This process uses the default instance size of Cloud Build, as these instances are pre-warmed and are available more quickly. Cloud Build does provide a free tier: please review the pricing document for further details.

    • For Cloud Storage pricing, see the Pricing page. Cloud Storage does provide a free tier: please review the pricing document for further details.

    • For Container Registry pricing, see the Pricing page.

    • For Artifact Registry pricing, see the Pricing page.

  • Because the build process is subject to billing, your project must have a Cloud Billing Account attached to it.

Accessing your build image logs

A key benefit of having the build image process in your user project is access to build logs. You can use either the gcloud CLI or the Cloud Console to reach the logs, which are available through Cloud Logging.


  1. Deploy your function using the gcloud functions deploy command.

  2. The URL of the logs is shown as part of the response in your terminal window. For example:

    Deploying function (may take a while - up to 2 minutes)...⠹
    **For Cloud Build Stackdriver Logs**, visit:
    Deploying function (may take a while - up to 2 minutes)...done.

Cloud Console

  1. From the Functions screen, click the Name of the function in which you are interested. The Function Details page opens.

  2. Scroll down until you see the Container build section. If your build had no errors, you see a link you can follow to display the Build log. If your build had errors, as you see below, the Container build section shows them inline; click Learn more to display the Build log directly.

    Screenshot that shows the output for the Container build section

  3. The Log viewer screen opens. Click the entry in which you are interested.

  4. The complete build log entry opens, showing the file affected, a description of the error - in this case a missing bracket in the pom.xml, and the line and column of the error.

    Screenshot that shows build log entry

Image registry options

Cloud Functions stores the image built from your function's source code using Container Registry by default. You can choose to use Artifact Registry instead, by passing the Artifact Registry repository via docker-repository field. For example, upon enabling the Artifact Registry API, you can use the following command to create or update (depending on flags) an Artifact Registry-based function:

gcloud beta functions deploy FUNCTION \

Replace the following:

  • FUNCTION: The name of the function.
  • REPOSITORY: The fully qualified Artifact Registry repository name, in the following format: projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY.

For detailed pricing information, see Cloud Functions Pricing.

Securing your build with private pools

To allow your functions to use dependencies (for example, npm packages), Cloud Build has by default unlimited internet access during the build process. If you have set up a VPC Service Controls (VPC SC) perimeter and wish to limit the build's access only to dependencies stored inside the perimeter, you can use the Cloud Build private worker pools feature.

In general, follow these steps to set up your private pool:

  1. Create your private worker pool. See Creating and managing private pools.
  2. Configure your VPC Service Controls perimeter. See Using VPC Service Controls.

  3. If your private worker pool is in a different project than your function, you need to grant the Cloud Functions Service Agent Service Account ( the cloudbuild.workerPoolUser role so that the Cloud Build service can access the worker pool.

    gcloud projects add-iam-policy-binding PRIVATE_POOL_PROJECT_ID \
        --role roles/cloudbuild.workerPoolUser

    where FUNCTION_PROJECT_NUMBER is the number of the project where the function runs and PRIVATE_POOL_PROJECT_ID is the id of the project in which the worker pool is located. See Running builds in a private pool for more information.

  4. Deploy your function to build using a private pool:


    gcloud functions deploy FUNCTION_NAME \
       --runtime RUNTIME \
       --build-worker-pool PRIVATE_POOL_NAME

    where FUNCTION_NAME is the name of the function, RUNTIME is the runtime you are using, and PRIVATE_POOL_NAME is the name of your pool.

    To stop using a given private pool and instead use the default Cloud Build pool, use the --clear-build-worker-pool flag when re-deploying.

    gcloud functions deploy FUNCTION_NAME \
       --runtime RUNTIME \

    where FUNCTION_NAME is the name of the function and RUNTIME is the runtime you are using.

    Cloud Console

    From the Create function page, in the Runtime, build and connections settings section, select the Build tab and enter the PRIVATE_POOL_NAME in the Build worker pools Selected environment text box, where PRIVATE_POOL_NAME is the name of your pool.

    Cloud Console screen shot