This page describes how to use Identity and Access Management (IAM) to manage access to Vertex AI resources. To manage access to Vertex AI Workbench instances, see Vertex AI Workbench instances access control.
Overview
Vertex AI uses IAM to manage access to resources. When you plan access control for your resources, consider the following:
You can manage access at the project level or resource level. Project-level access applies to all of the resources in that project. Access to a specific resource only applies to that resource. See Project-level versus resource-level access.
You grant access by assigning IAM roles to principals. Predefined roles are available to make it easier to set up access, but custom roles are recommended because you create them, so you can limit their access to only the permissions that are required. See IAM roles.
IAM roles
There are different types of IAM roles that can be used in Vertex AI:
Custom roles let you choose a specific set of permissions, create your own role with those permissions, and grant the role to users in your organization.
Predefined roles let you grant a set of related permissions to your Vertex AI resources at the project level.
Basic roles (Owner, Editor, and Viewer) provide access control to your Vertex AI resources at the project level, and are common to all Google Cloud services.
To add, update, or remove these roles in your Vertex AI project, see the documentation on granting, changing, and revoking access.
Custom roles
Custom roles let you choose a specific set of permissions, create your own role with those permissions, and grant the role to users in your organization. For more information, see Understanding IAM custom roles.
Use custom roles to grant least-privilege permissions
Predefined roles often contain more permissions than you need. You can create custom roles to grant your principals only the specific permissions that are required.
For example, you can create a custom role with the
aiplatform.endpoints.predict permission, and then assign the role to
a service account on an endpoint. This grants the service account the
ability to call the endpoint for predictions, but not the ability of
controlling the endpoint.
Predefined roles for Vertex AI
| Role | Permissions |
|---|---|
Vertex AI Administrator( Grants full access to all resources in Vertex AI |
|
Colab Enterprise Admin( Admin role of using colab enterprise. |
|
Colab Enterprise User( User role of using colab enterprise. |
|
Vertex AI Feature Store EntityType owner( Provides full access to all permissions for a particular entity type resource. Lowest-level resources where you can grant this role:
|
|
Vertex AI Platform Express Admin Beta( Grants admin access to Vertex AI Express |
|
Vertex AI Platform Express User Beta( Grants user access to Vertex AI Express |
|
Vertex AI Feature Store Admin( Grants full access to all resources in Vertex AI Feature Store Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Data Viewer( This role provides permissions to read Feature data. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Data Writer( This role provides permissions to read and write Feature data. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Instance Creator( Administrator of Featurestore resources, but not the child resources under Featurestores. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Resource Viewer( Viewer of all resources in Vertex AI Feature Store but cannot make changes. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store User Beta( Deprecated. Use featurestoreAdmin instead. |
|
Vertex AI Migration Service User( Grants access to use migration service in Vertex AI |
|
Notebook Executor User Beta( Grants users full access to schedules and notebook execution jobs. |
|
Notebook Runtime Admin( Grants full access to all runtime templates and runtimes in Notebook Service. |
|
Notebook Runtime User( Grants users permissions to create runtime resources using a runtime template and manage the runtime resources they created. |
|
Vertex AI Tensorboard Web App User Beta( Grants access to the Vertex AI TensorBoard web app. |
|
Vertex AI User( Grants access to use all resource in Vertex AI |
|
Vertex AI Viewer( Grants access to view all resource in Vertex AI |
|
Basic roles
The older Google Cloud basic roles are common to all Google Cloud services. These roles are Owner, Editor, and Viewer.
Project-level versus resource-level access
You can manage access at the project level or resource level. You might also have the ability to manage access at a folder or organization level.
For most Vertex AI resources, access can only be controlled by the project, folder, and organization. Access to individual resources can be granted only for specific resource types, for example, an endpoint or a featurestore.
Users share control of all resources they can access. For example, if a user registers a model, all other authorized users in the project can access, change, and delete the model.
To grant access to resources at the project level, assign one or more roles to a principal (user, group, or service account).
For Vertex AI resources that let you grant access at the resource level, you set an IAM policy on that resource. The policy defines which roles are assigned to which principals.
Setting a policy at the resource level doesn't affect project-level policies. A resource inherits all policies from its ancestry. You can use these two levels of granularity to customize permissions. For example, you can grant users read permissions at the project level so that they can read all resources in the project, and then you can grant users write permissions per resource (at the resource level).
Not all Vertex AI predefined roles and resources support resource-level policies. To identify which roles can be used on which resources, see the Predefined roles table.
Supported resources
Vertex AI supports Vertex AI Feature Store featurestore and entity type resources. For more information, see Control access to Vertex AI Feature Store resources.
After granting or revoking access to a resource, those changes take time to propagate. For more information, see Access change propagation.
Resources, service accounts, and service agents
Vertex AI services often manage long-running resources that perform actions, such as running a training job that reads training data, or serving a machine learning (ML) model that reads model weight. Such standalone resources have their own resource identity when performing actions. This identity is distinct from the identity of the principal that created the resource. Permissions granted to the resource identity define which data and other resources that the resource identity can access, not the permissions of the principal that created the resource.
By default, Vertex AI resources use service accounts managed by Vertex AI as a resource identity. These service accounts are called Vertex AI service agents, and they are attached to the project where the resource is created. Users with specific Vertex AI permissions can create resources that use Vertex AI service agents. For some services, you can specify a service account to attach to the resource. The resource uses this service account to access other resources and services. To learn more about service accounts, see service accounts.
Vertex AI uses different service agents depending on the APIs being called. Each service agent has specific IAM permissions on the project to which they are tied. These permissions are used by the resource identity to perform actions, and the permissions can include read-only access to all Cloud Storage resources and BigQuery data in the project.
Service accounts
A service account is a special account used by an application or a virtual machine (VM) instance, not a person. You can create and assign permissions to service accounts to provide specific permissions to a resource or application.
For information about using a service account to customize the permissions available to a custom training container or a container that serves online predictions for a custom-trained model, read Use a custom service account.
Service accounts are identified by an email address.
Service agents
Service agents are automatically provided; they enable a service to access resources on your behalf.
When a service agent is created, the service agent is granted a predefined role for your project. The following table lists Vertex AI service agents, their email addresses, and their respective roles:
| Name | Used for | Email address | Role |
|---|---|---|---|
| Vertex AI Service Agent | Vertex AI capabilities | service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com |
roles/aiplatform.serviceAgent |
| Vertex AI Custom Code Service Agent |
Custom training code Ray on Vertex AI application code |
service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com |
roles/aiplatform.customCodeServiceAgent |
| Vertex AI Extension Service Agent | Vertex Extensions | service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com |
roles/aiplatform.extensionServiceAgent |
| Cloud AI Platform Notebooks Service Account | Vertex AI Workbench capabilities | service-PROJECT_NUMBER@gcp-sa-notebooks.iam.gserviceaccount.com |
roles/notebooks.serviceAgent |
The Vertex AI Custom Code Service Agent is created only if you run custom training code to train a custom-trained model.
Service agent roles and permissions
See the following roles and permissions that are granted to Vertex AI service agents.
| Role | Permissions |
|---|---|
Vertex AI Service Agent( Gives Vertex AI the permissions it needs to function. |
|
Vertex AI Custom Code Service Agent( Gives Vertex AI Custom Code the proper permissions. |
|
AI Platform Notebooks Service Agent( Provide access for notebooks service agent to manage notebook instances in user projects |
|
Grant Vertex AI service agents access to other resources
Sometimes you need to grant additional roles to a Vertex AI service agent. For example, if you need Vertex AI to access a Cloud Storage bucket in a different project, you'll need to grant one or more additional roles to the service agent.
Role addition requirements for BigQuery
The following table describes the required additional roles needed to be added to the Vertex AI Service Agent for BigQuery tables or view in a different project or backed by an external data source.
The term home project refers to the project where the Vertex AI dataset or model is located. The term different project refers to any other project.
| Table type | Table project | Data source project | Role addition required |
|---|---|---|---|
| Native BigQuery table | Home project | N/A | None. |
| Native BigQuery table | Different project | N/A | BigQuery Data Viewer for different project. Learn more. |
| BigQuery view | Home project | N/A | None. |
| BigQuery view | Different project | N/A | BigQuery Data Viewer for different project. Learn more. |
| External BigQuery data source backed by Bigtable | Home project | Home project | Bigtable Reader for home project. Learn more. |
| External BigQuery data source backed by Bigtable | Home project | Different project | Bigtable Reader for different project. Learn more. |
| External BigQuery data source backed by Bigtable | Different project | Different project | BigQuery Reader and Bigtable Reader for different project. Learn more. |
| External BigQuery data source backed by Cloud Storage | Home project | Home project | None. |
| External BigQuery data source backed by Cloud Storage | Home project | Different project | Storage Object Viewer for different project. Learn more. |
| External BigQuery data source backed by Cloud Storage | Different project | Different project | Storage Object Viewer and BigQuery Data Viewer for different project. Learn more. |
| External BigQuery data source backed by Google Sheets | Home project | N/A | Share your Sheets file with the Vertex AI service account. Learn more. |
| External BigQuery data source backed by Google Sheets | Different project | N/A | BigQuery Reader for different project and share your Sheets file with the Vertex AI service account. |
Role addition requirements for Cloud Storage
If you are accessing data in a Cloud Storage bucket in a different
project, you must give the Storage > Storage Object Viewer role to
Vertex AI in that project. Learn more.
If you are using a Cloud Storage bucket to receive data from your local
computer for an import operation, and the bucket is in a different project than
Google Cloud project, you must give the Storage > Storage Object Creator
role to Vertex AI in that project. Learn more.
Grant access to Vertex AI to resources in your home project
To grant additional roles to a service agent for Vertex AI in your home project:
Go to the IAM page of the Google Cloud console for your home project.
Select the Include Google-provided role grants checkbox.
Determine the service agent you want to grant the permissions to and click the pencil icon.
You can filter for Principal:@gcp-sa-aiplatform-cc.iam.gserviceaccount.com to find the Vertex AI service agents.
Grant the required roles to the service account and save your changes.
Grant access to Vertex AI to resources in a different project
When you use data sources or destinations in a different project, you must give the Vertex AI service account permissions in that project. The Vertex AI service account is created after you start the first asynchronous job (for example, creating an endpoint). You can also explicitly create the Vertex AI service account by using gcloud CLI following these instructions. This gcloud command will create both the default service account and the custom code service account, though only the default service account will be returned in the response.
To add permissions to Vertex AI in a different project:
Go to the IAM page of the Google Cloud console for your home project (the project where you are using Vertex AI).
Select the Include Google-provided role grants checkbox.
Determine the service agent you want to grant the permissions to and copy its email address (listed under Principal).
You can filter for Principal:@gcp-sa-aiplatform-cc.iam.gserviceaccount.com to find the Vertex AI service agents.
Change projects to the project where you need to grant the permissions.
Click Add, and enter the email address in New principals.
Add all required roles and click Save.
Provide access to Google Sheets
If you use an external BigQuery data source backed by Google Sheets, you must share your sheet with the Vertex AI service account. The Vertex AI service account is created after you start the first asynchronous job (for example, creating an endpoint). You can also explicitly create the Vertex AI service account by using gcloud CLI by following this instruction.
To authorize Vertex AI to access your Sheets file:
Go to the IAM page of the Google Cloud console.
Look for the service account with the name
Vertex AI Service Agentand copy its email address (listed under Principal).Open your Sheets file and share it with that address.
What's next
- Learn more about IAM.
- Learn about specific IAM permissions and the operations they support.
- To learn about recommended ways to set up a project for a team, see Set up a project for a team.
- Get an overview of Vertex AI.