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 prebuilt 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 prebuilt container or a custom container.

• When you create a Ray on Vertex AI cluster, you can set a custom service account for all nodes in the cluster.

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 can't customize the permissions of the service account.

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. Note that you can't configure a custom service account to pull images from Artifact Registry. Vertex AI uses the default service account to pull images.

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 can be in the same project as your Vertex AI resources or in a different project.

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. Optional: If the user-managed service account is in a different project than your training jobs, configure the user-managed service account so you can attach it to your training jobs.

4. Optional: If you also plan to use the user-managed service account for predictions, then you must grant the Service Account Admin role (roles/iam.serviceAccountAdmin) to the Vertex AI Service Agent of the project where you're using Vertex AI:

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

   Replace the following:

   • AI_PLATFORM_SERVICE_AGENT: The email address of your project's Vertex AI Service Agent, which has the following format:

     [e-mail]

     To find the Vertex AI Service Agent, go to the IAM page in the Google Cloud console.

     Go to IAM

   • 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 can't specify a service account for custom training when you use the Google 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 Google 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.

Before using any of the command data below, make the following replacements:

• ENDPOINT_ID: The ID for the endpoint.
• LOCATION_ID: The region where you are using Vertex AI.
• MODEL_ID: The ID for the model to be deployed.
• DEPLOYED_MODEL_NAME: A name for the DeployedModel. You can use the display name of the Model for the DeployedModel as well.
• MACHINE_TYPE: Optional. The machine resources used for each node of this deployment. Its default setting is n1-standard-2. Learn more about machine types.
• MIN_REPLICA_COUNT: The minimum number of nodes for this deployment. The node count can be increased or decreased as required by the prediction load, up to the maximum number of nodes and never fewer than this number of nodes.
• MAX_REPLICA_COUNT: The maximum number of nodes for this deployment. The node count can be increased or decreased as required by the prediction load, up to this number of nodes and never fewer than the minimum number of nodes.
• CUSTOM_SERVICE_ACCOUNT: The service account's email address. For example: SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

Execute the gcloud ai endpoints deploy-model command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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

 

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.