Use a custom service account

This guide describes how to configure Vertex AI to use a custom service account in the following scenarios:

• When you perform custom training, you can configure Vertex AI to use a custom service account in the training container, whether it is a pre-built container or a custom container.

• When you deploy a custom-trained Model resource to an Endpoint resource to serve online predictions, you can configure Vertex AI to use a custom service account in the container that serves predictions, whether it is a pre-built container or a custom container.

When to use a custom service account

When Vertex AI runs, it generally acts with the permissions of one of several service accounts that Google creates and manages for your Google Cloud project. To grant Vertex AI increased access to other Google Cloud services in certain contexts, you can add specific roles to Vertex AI's service agents.

However, customizing the permissions of service agents might not provide the fine-grained access control that you want. Some common use cases include:

• Allowing fewer permissions to Vertex AI jobs and models. The default Vertex AI service agent has access to BigQuery and Cloud Storage.
• Allowing different jobs access to different resources. You might want to allow many users to launch jobs in a single project, but grant each user's jobs access only to a certain BigQuery table or Cloud Storage bucket.

For example, you might want to individually customize every custom training job that you run to have access to different Google Cloud resources outside of your project.

Moreover, customizing the permissions of service agents does not change the permissions available to a container that serves predictions from a custom-trained Model.

To customize access each time you perform custom training or to customize the permissions of a custom-trained Model's prediction container, you must use a custom service account.

Default access

This section describes the default access available to custom training containers and the prediction containers of custom-trained Model resources. When you use a custom service account, you override this access for a specific CustomJob, HyperparameterTuningJob, TrainingPipeline, or DeployedModel resource.

Training containers

When you create a CustomJob, HyperparameterTuningJob, or a custom TrainingPipeline, the training container runs using your Google Cloud project's Vertex AI Custom Code Service Agent by default.

Learn more about the Vertex AI Custom Code Service Agent, including how to give it access to additional Google Cloud resources.

Prediction containers

When you deploy a custom-trained Model to an Endpoint, the prediction container runs using a service account managed by Vertex AI. This service account is different from the Vertex AI service agents.

The service account that the prediction container uses by default has permission to read model artifacts that Vertex AI makes available at a URI stored in the AIP_STORAGE_URI environment variable. Do not rely on the service account to have any other permissions. You cannot customize the service account's permissions.

Configure a custom service account

The following sections describe how to set up a custom service account to use with Vertex AI and how to configure a CustomJob, HyperparameterTuningJob, TrainingPipeline, or DeployedModel to use the service account.

Set up a custom service account

To set up a custom service account, do the following:

1. Create a user-managed service account. The user-managed service account must be in the same project as your Vertex AI resources.

2. Grant your new service account IAM roles that provide access to the Google Cloud services and resources that you want Vertex AI to be able to use during custom training or prediction.

3. In the project where you are using Vertex AI, find the email address of the project's Vertex AI Service Agent. This email address has the following format:

   [e-mail]
   

   PROJECT_NUMBER is replaced by the project number for your Google Cloud project.

   You can find the service account listed on the IAM page in the Google Cloud Console:

   Go to the IAM page

4. If you plan to use the custom service account for training only, skip this step. If you plan to use the custom service account for a prediction container, then grant an additional role:

   In the project where you are using Vertex AI, grant the project's Vertex AI Service Agent the Service Account Admin role (roles/iam.serviceAccountAdmin) for your new custom service account. To do so, use the gcloud tool to run the following command:

   gcloud iam service-accounts add-iam-policy-binding \
     --role=roles/iam.serviceAccountAdmin \
     --member=serviceAccount:AI_PLATFORM_SERVICE_AGENT \
     CUSTOM_SERVICE_ACCOUNT
   

   In this command, replace the following placeholders:

   • AI_PLATFORM_SERVICE_AGENT: The email address of your project's Vertex AI Service Agent, which you found in a previous step of this section.

   • CUSTOM_SERVICE_ACCOUNT: The email address of the new user-managed service account that you created in the first step of this section.

   Note: This command grants your project's Vertex AI Service Agent the Service Account Admin role only for your custom service account resource, not for the whole project. Learn more about granting permissions at the resource level versus the project level.

Specify a custom service account for Vertex AI resources

The process of configuring Vertex AI to use a specific service account for a resource is called attaching the service account to the resource. The following sections describe how to attach the service account that you created in the previous section to several Vertex AI resources.

Note: To attach the service account, you must have the iam.serviceAccounts.actAs permission for the service account. If you successfully completed the previous section of this guide, then you likely already have this permission. If you don't have the permission, ask a project administrator to give you access by granting you the Service Account User role (roles/iam.serviceAccountUser) for the custom service account.

Attach a service account to a custom training resource

To configure Vertex AI to use your new service account during custom training, specify the service account's email address in the serviceAccount field of a CustomJobSpec message when you start custom training. Depending on which type of custom training resource you are creating, the placement of this field in your API request differs:

Note: You cannot specify a service account for custom training when you use the Cloud Console to perform custom training.

• If you are creating a CustomJob, specify the service account's email address in CustomJob.jobSpec.serviceAccount.

  Learn more about creating a CustomJob.

• If you are creating a HyperparameterTuningJob, specify the service account's email address in HyperparameterTuningJob.trialJobSpec.serviceAccount.

  Learn more about creating a HyperparameterTuningJob.

• If you are creating a custom TrainingPipeline without hyperparameter tuning, specify the service account's email address in TrainingPipeline.trainingTaskInputs.serviceAccount.

• If you are creating a custom TrainingPipeline with hyperparameter tuning, specify the service account's email address in TrainingPipeline.trainingTaskInputs.trialJobSpec.serviceAccount.

Attach a service account to a container that serves online predictions

To configure a custom-trained Model's prediction container to use your new service account, specify the service account's email address when you deploy the Model to an Endpoint:

Console

Follow Deploying a model using the Cloud Console. When you specify model settings, select the service account in the Service account drop-down list.

gcloud

Follow Deploying a model using the Vertex AI API. When you run the gcloud ai endpoints deploy-model command, use the --service-account flag to specify your service account's email address.

For example:

gcloud ai endpoints deploy-model ENDPOINT_ID \
--region=LOCATION \
--model=MODEL_ID \
--display-name=DEPLOYED_MODEL_NAME \
--machine-type=MACHINE_TYPE \
--min-replica-count=MIN_REPLICA_COUNT \
--max-replica-count=MAX_REPLICA_COUNT \
--traffic-split=0=100 \
--service-account=CUSTOM_SERVICE_ACCOUNT

Replace CUSTOM_SERVICE_ACCOUNT with the service account's email address.

API

Follow Deploying a model using the Vertex AI API. When you send the projects.locations.endpoints.deployModel request, set the deployedModel.serviceAccount field to the service account's email address.

Access Google Cloud services in your code

If you configure Vertex AI to use a custom service account by following the instructions in preceding sections, then your training container or your prediction container can access any Google Cloud services and resources that the service account has access to.

To access Google Cloud services, write your training code or your prediction-serving code to use Application Default Credentials (ADC) and explicitly specify the project ID or project number of the resource you want to access. Learn more about writing your code to access other Google Cloud services.

What's next

• Learn more about Access control for Vertex AI.
• Learn about specific IAM permissions and the operations they support.