Build process overview

When you deploy your function's source code to Cloud Run 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 an image registry. Cloud Run functions accesses this image when it needs to run the container to execute your function. If your function still uses Container Registry, you should switch to Artifact Registry as soon as possible.

Caution: Container Registry is deprecated and scheduled for shutdown. Organizations that haven't used Container Registry prior to January 8, 2024 have new gcr.io repositories hosted on Artifact Registry by default. Effective May 15, 2024, Google Cloud projects without previous usage of Container Registry will only support hosting and managing images for the gcr.io domain in Artifact Registry.

Container Registry is scheduled for shutdown on March 18, 2025. For details on the deprecation, see Container Registry deprecation.

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 images, both of which are stored in Artifact Registry.

• Cloud Storage is used directly in your project and the source code directory for your functions is stored in a bucket within your project. Note the following:

  • If you're using default encryption, this bucket is named gcf-sources-PROJECT_NUMBER-REGION.
  • If you're protecting your data with CMEK, the bucket is named gcf-sources-PROJECT_NUMBER-REGION-CMEK_KEY_HASH.
  • The bucket has no retention period.

Note: If you accidentally delete a Cloud Run function, you can restore it using the source files from the gcf-sources bucket by downloading the zip file and redeploying it. Note that the gcf-sources bucket retains only the last two versions of the source code. When cleaning up, deleting the function and disabling the Cloud Run functions API won't automatically delete the gcf-sources bucket. To fully remove all Cloud Run functions-related resources, you must manually delete the gcf-sources bucket.

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 follow the prompts to enable the UI.

• 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: review the pricing document for further details.

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

  • For Artifact Registry pricing, see the Pricing page.

  • For Container Registry (deprecated) pricing, see the Pricing page.

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

Note: If you are using gcp.resourceLocations in your organization policy constraints, you should include the appropriate multi-region location. For example, if you are deploying in any of the us regions, you should include us-locations. This allows Cloud Build to access the Artifact Registry storage bucket.

View 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 Google Cloud console to reach the logs, which are available through Cloud Logging.

gcloud

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:
   https://console.cloud.google.com/logs/viewer?project=&advancedFilter=resource.type%
   3Dbuild%0Aresource.labels.build_id%3D38d5b662-2315-45dd-8aa2-
   380d50d4f5e8%0AlogName%3Dprojects%2F%
   2Flogs%2Fcloudbuild
   Deploying function (may take a while - up to 2 minutes)...done.
   

Google Cloud console

1. From the Cloud Run functions Overview window, click the name of the function you're investigating.
2. Click the Details tab.
3. In the General Information pane, click the Container build log link to open the Logs explorer pane.
4. Click any row to view the details of that build log entry. If it's an error entry associated with a file, these details include the name, line and column of the file.

Image registry

Cloud Run functions uses Artifact Registry to store the images built from your function source code. Images are stored in a repository named REGION-docker.pkg.dev/PROJECT_ID/gcf-artifacts located in the same project where your function is created.

To specify a self-managed Artifact Registry repository, run the following command:

gcloud

gcloud functions deploy FUNCTION \
  --docker-registry=artifact-registry \
  --docker-repository=REPOSITORY \
  [FLAGS...]

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.

Preview — Cloud Run functions cross project repository

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

When specifying a Artifact Registry repository located in a different project or region you may need to consider additional configurations:

IAM configurations:

• Ensure that the build service account has authorized access to read and write to the REPOSITORY.

Network configurations:

• Ensure that the target REPOSITORY is reachable from the current project configuration.

VPC Service Controls configurations:

• Ensure that the build service account can reach the target REPOSITORY within the VPC-SC perimeter.

Data residency constraints:

• Note that specifying a REPOSITORY in a different region from where your function is located will lead to data transfer across regions.

Google Cloud console

1. Go to the Cloud Run functions page in the Google Cloud console:
   Go to the Cloud Run functions page

2. Click the name of the function for which you want to use Artifact Registry.

3. Click Edit.

4. Click Runtime, build... to expand the advanced configuration options.

5. Click Security and Image Repo from the menu bar to open the security tab.

6. Under Image repository, select one of the following, depending on which type of Artifact Registry you are using:

   • Customer managed Artifact Registry. Use this option if you set up your own Docker repository.
   • Google managed Artifact Registry. Use this option if you want to use a Google-managed Docker repository instead of setting up your own.

7. For Customer managed Artifact Registry, use the Artifact registry drop-down to select the Artifact Registry repository you want, or follow the prompts and create a new one.

8. Click Next.

9. Click Deploy.

Switch to Artifact Registry

Functions can publish images to Artifact Registry by changing the repository settings:

gcloud

gcloud beta functions deploy FUNCTION \
  --docker-registry=artifact-registry \
  [FLAGS...]

Google Cloud console

1. Go to the Cloud Run functions page in the Google Cloud console:
   Go to the Cloud Run functions page

2. Click the name of the function for which you want to use Artifact Registry.

3. Click Edit.

4. Click Runtime, build... to expand the advanced configuration options.

5. Click Security and Image Repo from the menu bar to open the security tab.

6. Under Image repository, select one of the following, depending on which type of Artifact Registry you are using:

   • Customer managed Artifact Registry. Use this option if you set up your own Docker repository.
   • Google managed Artifact Registry. Use this option if you want to use a Google-managed Docker repository instead of setting up your own.

7. For Customer managed Artifact Registry, use the Artifact registry drop-down to select the Artifact Registry repository you want, or follow the prompts and create a new one.

8. Click Next.

9. Click Deploy.

For detailed pricing information, see Cloud Run functions Pricing.

Secure 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 Run functions Service Agent Service Account ([e-mail]) 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 \
       --member serviceAccount:[e-mail]
       --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

gcloud functions deploy FUNCTION_NAME \
  --runtime RUNTIME \
  --build-worker-pool PRIVATE_POOL_NAME
  [FLAGS...]

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 \
  --clear-build-worker-pool
  [FLAGS...]

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

Google Cloud console

1. From the Cloud Run functions overview page, select Create function.

2. In the Runtime, build... section, click the Build tab and enter the full resource name of your private pool in the Build worker pools text box.

For more information, see Run builds in a private pool.

Secure your build with a custom service account

Cloud Run functions takes your source code and sends it to Cloud Build to be containerized. The containerized function is stored in Artifact Registry and deployed to Cloud Run as a service. By default, Cloud Build assigns a service account to act as the principal when performing your build. As of July 2024, new projects in an organization will use the Compute Engine default Service Account to act as the principal running a build. For details, see Cloud Build default service account change. For security reasons, the Compute Engine default Service Account has insufficient permissions to perform the build.

For Google Cloud projects created before July 2024, Cloud Build uses the legacy Cloud Build service account. This service account was designed to help users execute a broad range of use cases that may be too permissive for your project's needs. If you want to move your existing projects away from this service account, you can take the following steps to further secure your functions build environment:

1. Prevent the legacy Cloud Build service account from being used for the build.
2. Prevent the default Compute service account from being used for the build.
3. Configure a new service account with appropriately scoped permissions to be used for the build.
4. Use the configured service account for the build.

Prevent the legacy Cloud Build service account from being used for build

Warning: This will temporarily break all deployments until you assign a new service account.

You can verify that your project is using the legacy Cloud Build service account by inspecting the details of your function's build. The default build service account has the following format:

[e-mail].

You can forcibly disable use of this service account by setting the org policy constraint cloudbuild.useBuildServiceAccount to Not Enforced. Alternatively, removing all of its role grants will limit its ability to access Google Cloud resources.

Prevent the default compute service account from being used for build

Warning: This will temporarily break all deployments until you assign a new service account.

The default compute service account has the format [e-mail]. You can disable it from being the default used for the build by setting the org policy cloudbuild.useComputeServiceAccount to Not Enforced. Alternatively, disabling this service account prevents it from being used to access Google Cloud resources.

Provide a service account for building functions

As part of a function's configuration, a build service account can be specified when deploying the function. When the legacy Cloud Build service account and the default compute service account are prevented from being used for build, a build service account must be specified in order to deploy a function.

See Custom Service Account for Cloud Build for configuring and using a build service account for your function.