If you are creating a new function, see the Console Quickstart on Cloud Run. The content on this page only applies to existing legacy functions created with the Cloud Functions v2 API.

Custom Service Account for Cloud Build

Cloud Run functions leverages Cloud Build when building and deploying your Cloud Run function. By default, Cloud Run functions uses the default Cloud Build service account as the principal when performing your build. Starting in July 2024, Cloud Build has changed the default behavior for how Cloud Build uses service accounts in new projects. This change is detailed in Cloud Build Service Account Change. As a result of this change, new projects deploying functions for the first time may be using a default Cloud Build service account with insufficient permissions for building a function. If you are impacted by this change you can do one of the following:

Review the Cloud Build guidance on changes to the default service account and opt out of these changes.
Add the Cloud Build Account role (roles/cloudbuild.builds.builder) to the default Compute Engine service account.
Create a custom Cloud Build service account for function deployments.

This document describes how to pass in a user-created service account, to be used by Cloud Build, when deploying your function.

You can deploy functions with custom service accounts using the Google Cloud CLI, Google Cloud console, or the Cloud Run functions API.

Here are some scenarios where you may want to provide a different service account to be used when Cloud Build builds your function:

You want more control of which service accounts to add to your VPC-SC perimeter.
You want Cloud Build to run with different permissions than what the default service account has without having to revoke each permission individually.
You want to set granular Cloud Build permissions specifically for your functions, not share a Cloud Build service account that is optimized for other purposes.
Your organization disabled the usage of the default service account.

Enable APIs

This feature requires the IAM API to be enabled.

Use the Google Cloud CLI to enable the APIs needed to deploy a Cloud Run function, or use Google Cloud console:

gcloud services enable iam.googleapis.com

Configure Service Account

This document describes how to create a new service account and grant the required permissions. If you want to use an existing service account, you need the email address of the service account you plan to use. See configuring user-specified service accounts for details.

You can view your existing service accounts as follows, or use Google Cloud console:

gcloud iam service-accounts list

Create Service Account

Use the Google Cloud CLI to create your service account or use Google Cloud console:

gcloud iam service-accounts create SA_EMAIL

Replace SA_EMAIL with the email address of your service account.

Grant Permissions

The service account you use will need the following roles:

roles/logging.logWriter— Required to store build logs in Cloud Logging.
roles/artifactregistry.writer— Required to store build images in Artifact Registry. For the default behavior, the service account needs access to repositories named "gcf-artifacts" and "cloud-run-source-deploy". Access to the repositories can be set on the repository's IAM policy. You can alternatively provide your own artifact repository through dockerRepository field.
roles/storage.objectViewer— Required to retrieve the function source from the Cloud Storage bucket, and to store build images in Container Registry. For the default behavior, the service account needs access to buckets named "run-sources-*", "gcf-v2-sources-*" and "gcf-v2-uploads-*". This can be accomplished by adding an IAM condition to the role grant such as: (resource.type == "storage.googleapis.com/Object" && (resource.name.startsWith("gcf-v2-sources-") || resource.name.startsWith("gcf-v2-uploads-") || resource.name.startsWith("run-sources-")))

Grant the following roles using the Google Cloud CLI, or use Google Cloud console.

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SA_EMAIL \
    --role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SA_EMAIL \
--role=roles/artifactregistry.writer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SA_EMAIL \
--role=roles/storage.objectViewer

Replace the following:

PROJECT_ID: Your Google Cloud project ID.
SA_EMAIL: The email address of your service account.

VPC Service Controls considerations

If you have a VPC Service Controls perimeter protecting both your project and the Cloud Run functions API, and if you're using the Compute Engine default service account as the Cloud Build Service Account role for Cloud Run functions, you must create the following ingress rules:

Allow Compute Engine default service account ingress to all methods on both Cloud Storage and Cloud Logging APIs.
Allow the service account service-[PROJECT_NUMBER]@gcf-admin-robot.iam.gserviceaccount.com ingress to all methods on both Cloud Storage and Cloud Logging APIs.

Deploy a function with a custom service account

You can use the Google Cloud CLI to deploy a function that uses a custom service account for Cloud Build:

The --build-service-account flag specifies an IAM service account whose credentials will be used for the build step. If a custom service account is not provided, the function uses the project's default service account for Cloud Build.
You can optionally use a private pool, which you specify using the --build-worker-pool flag.


gcloud functions deploy FUNCTION_NAME \
   --gen2 \
   --region=REGION \
   --project=PROJECT_ID \
   --runtime=RUNTIME \
   --entry-point=CODE_ENTRYPOINT \
   --build-service-account=projects/PROJECT_ID/serviceAccounts/SA_EMAIL \
   --memory=256Mi \
   --trigger-http \
   --source=.

Replace the following:

FUNCTION_NAME: The name under which you deployed your function.
REGION: The name of the Google Cloud region where you want to deploy your function (for example, us-west1).
PROJECT_ID: Your Google Cloud project ID.
RUNTIME: The runtime ID of a supported runtime version to run your function, for example, nodejs18.
CODE_ENTRYPOINT: The entry point to your function in your source code. This is the code that will be executed when your function runs.
SA_EMAIL: The email address of your service account.