Set permissions for generative AI functions that call Vertex AI models

This document shows you how to set up permissions for running generative AI queries. Generative AI queries contain AI.* functions that call foundation models in Vertex AI; for example, AI.GENERATE.

There are two ways to set up permissions to run queries that use AI.* functions:

• Run the query using your end-user credentials
• Create a connection to run the query using a service account

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

1. Enable the BigQuery API, BigQuery Connection API, and Vertex AI API APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

   For new projects, the BigQuery API is automatically enabled.

2. Optional: Enable billing for the project. If you don't want to enable billing or provide a credit card, the steps in this document still work. BigQuery provides you a sandbox to perform the steps. For more information, see Enable the BigQuery sandbox.
   Note: If your project has a billing account and you want to use the BigQuery sandbox, then disable billing for your project.

Required roles

To get the permissions that you need to run a query job that calls a Vertex AI model, ask your administrator to grant you the following IAM roles on the project:

• Run query jobs: BigQuery Job User (roles/bigquery.jobUser)
• Create a connection: BigQuery Connection Admin (roles/bigquery.connectionAdmin)
• Access a remote model in Vertex AI: Vertex AI User (roles/aiplatform.user)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Run generative AI queries with end-user credentials

For user-initiated queries, the CONNECTION argument is optional. When a user initiates a query, BigQuery ML uses the credentials of the user who submitted the query to run it.

If your query job is expected to run for 48 hours or longer, you should use the CONNECTION argument to run the query using a service account.

Required roles

To run a generative AI query that uses AI.* functions to call a Vertex AI model, the user or group must be granted the following roles.

To get the permissions that you need to run a query job that calls a Vertex AI model, ask your administrator to grant you the following IAM roles on the project:

• Run query jobs: BigQuery Job User (roles/bigquery.jobUser)
• Access a remote model in Vertex AI: Vertex AI User (roles/aiplatform.user)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Note that additional permissions are required to grant roles to a user. For more information, see Required roles on the Manage access to projects, folders, and organizations page.

If the user running the query doesn't have the required permissions, you may see an error similar to the following: The user does not have permission to access resources used by <var>FUNCTION_NAME</var>.

Grant the required roles to the user or group

You can use the Google Cloud console to grant the required roles for a principal. The principal is the user or group that runs the query that uses AI.* functions to call a Vertex AI foundation model.

1. In the Google Cloud console, go to the IAM page.

   Go to IAM

2. Select your project.

3. To modify roles for a principal who already has roles on the project:

   1. Find the row that contains the principal, and then click Edit principal.

   2. In the Assign roles section, click Add another role.

   3. For Select another role, click the drop-down arrow.

   4. Search for or browse to the Vertex AI User role and select it.

   5. Click Add another role.

   6. In the Assign roles section, for Select another role, click the drop-down arrow.

   7. Search for or browse to the BigQuery Job User role and select it.

   8. Click Save.

      

4. To grant roles to a principal who doesn't have any roles on the project:

   1. Go to the IAM & Admin page.

      Go to IAM & Admin

   2. Click Grant access.

      The Add principals dialog opens.

   3. In the New principals field, enter the principal identifier— for example, [e-mail] or //iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail].

   4. In the Assign roles section, for Select a role, click the drop-down arrow.

   5. Search for the Vertex AI User role and select it.

   6. Click Add another role.

   7. In the Assign roles section, for Select a role, click the drop-down arrow.

   8. Search for or browse to the BigQuery Job User role and select it.

   9. Click Save.

      

For information on other methods of granting project-level roles to a principal, see Grant or revoke multiple IAM roles programmatically.

Run generative AI queries with a Cloud Resource Connection

To run generative AI queries using a connection, create the connection, and then grant access to the service account created by the connection.

Create a connection

You can set up a Cloud Resource Connection to run all generative AI queries that contain AI.* functions. When you create a connection, you grant permissions to run queries to a service account. Creating a connection is required for background jobs such as vector search indexing and is recommended for jobs that run longer than 48 hours.

Note: Continuous queries don't require you to specify a connection in the SQL query. For more information, see Create continuous queries.

Select one of the following options:

Console

1. Go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, click Add data:

   

   The Add data dialog opens.

3. In the Filter By pane, in the Data Source Type section, select Business Applications.

   Alternatively, in the Search for data sources field, you can enter Vertex AI.

4. In the Featured data sources section, click Vertex AI.

5. Click the Vertex AI Models: BigQuery Federation solution card.

6. In the Connection type list, select Vertex AI remote models, remote functions, BigLake and Spanner (Cloud Resource).

7. In the Connection ID field, enter a name for your connection.

8. Click Create connection.

9. Click Go to connection.

10. In the Connection info pane, copy the service account ID for use in a later step.

bq

1. In a command-line environment, create a connection:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   The --project_id parameter overrides the default project.

   Replace the following:

   • REGION: your connection region
   • PROJECT_ID: your Google Cloud project ID
   • CONNECTION_ID: an ID for your connection

   When you create a connection resource, BigQuery creates a unique system service account and associates it with the connection.

   Troubleshooting: If you get the following connection error, update the Google Cloud SDK:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Retrieve and copy the service account ID for use in a later step:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   The output is similar to the following:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

Use the google_bigquery_connection resource.

Note: To create BigQuery objects using Terraform, you must enable the Cloud Resource Manager API.

To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following example creates a Cloud resource connection named my_cloud_resource_connection in the US region:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

1. Launch Cloud Shell.

2. Set the default Google Cloud project where you want to apply your Terraform configurations.

   You only need to run this command once per project, and you can run it in any directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (also called a root module).

1. In Cloud Shell, create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf. In this tutorial, the file is referred to as main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. If you are following a tutorial, you can copy the sample code in each section or step.

   Copy the sample code into the newly created main.tf.

   Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

3. Review and modify the sample parameters to apply to your environment.
4. Save your changes.
5. Initialize Terraform. You only need to do this once per directory.

   terraform init

   Optionally, to use the latest Google provider version, include the -upgrade option:

   terraform init -upgrade

Apply the changes

1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:

   terraform plan

   Make corrections to the configuration as necessary.

2. Apply the Terraform configuration by running the following command and entering yes at the prompt:

   terraform apply

   Wait until Terraform displays the "Apply complete!" message.

3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.

Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

For more information, see Create and set up a Cloud resource connection.

Grant access to the service account

To run queries that use generative AI.* functions that call Vertex AI models, you must grant appropriate permissions to the service account that was created when you created your connection. To run functions that call a Vertex AI foundation model, the Vertex AI User role (roles/aiplatform.user) is required.

Select one of the following options:

Console

1. Go to the IAM & Admin page.

   Go to IAM & Admin

2. Click Grant access.

   The Add principals dialog opens.

3. In the New principals field, enter the service account ID that you copied earlier.

4. In the Assign roles section, click Add roles.

5. Search for the Vertex AI User role, select it, and then click Apply.

6. Click Save.

gcloud

Use the gcloud projects add-iam-policy-binding command:

gcloud projects add-iam-policy-binding gs://PROJECT_ID \
--member="serviceAccount:$(bq show --format=prettyjson --connection $PROJECT_ID.$REGION.$CONNECTION_NAME | jq -r .cloudResource.serviceAccountId)"
--role=roles/aiplatform.user

Replace the following:

• PROJECT_ID: the name of your project.
• REGION: the location where the connection was created.
• CONNECTION_NAME: The name of the connection you created.

Terraform

Use the google_bigquery_connection resource.

Note: To create BigQuery objects using Terraform, you must enable the Cloud Resource Manager API.

To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following example grants IAM role access to the service account of the Cloud resource connection:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

## This grants IAM role access to the service account of the connection created in the previous step.
resource "google_project_iam_member" "connectionPermissionGrant" {
  project = data.google_project.default.project_id
  role    = "roles/storage.objectViewer"
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

1. Launch Cloud Shell.

2. Set the default Google Cloud project where you want to apply your Terraform configurations.

   You only need to run this command once per project, and you can run it in any directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (also called a root module).

1. In Cloud Shell, create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf. In this tutorial, the file is referred to as main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. If you are following a tutorial, you can copy the sample code in each section or step.

   Copy the sample code into the newly created main.tf.

   Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

3. Review and modify the sample parameters to apply to your environment.
4. Save your changes.
5. Initialize Terraform. You only need to do this once per directory.

   terraform init

   Optionally, to use the latest Google provider version, include the -upgrade option:

   terraform init -upgrade

Apply the changes

1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:

   terraform plan

   Make corrections to the configuration as necessary.

2. Apply the Terraform configuration by running the following command and entering yes at the prompt:

   terraform apply

   Wait until Terraform displays the "Apply complete!" message.

3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.

Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.