Using a custom service account

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

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 customize the permissions of Vertex AI's service agents.

However, customizing the permissions of service agents might not provide the fine-grained access control that you want. 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.

Understanding 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 AI Platform Custom Code Service Agent by default.

Learn more about the AI Platform 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.

Configuring 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.

  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 AI Platform Service Agent. This email address has the following format:

    service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com
    

    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 the user-managed service account is in a different project than your Vertex AI resources, configure the user-managed service account so you can attach it to your Vertex AI resources.

  5. 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 AI Platform 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 AI Platform 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.

Specifying 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.

Attaching 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:

  • 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 beta ai endpoints deploy-model command, use the --service-account flag to specify your service account's email address.

For example:

gcloud beta 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.

Accessing 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). Many Google Cloud client libraries authenticate with ADC by default. You don't need to configure any environment variables; Vertex AI automatically configures ADC to authenticate as the custom service account.

However, when you use a Google Cloud client library in your code, Vertex AI might not always connect to the correct Google Cloud project by default. If you encounter permission errors, connecting to the wrong project might be the problem.

This problem occurs because Vertex AI does not run your code directly in your Google Cloud project. Instead, Vertex AI runs your code in one of several separate projects managed by Google. Vertex AI uses these projects exclusively for operations related to your project. Therefore, don't try to infer a project ID from the environment in your training or prediction code; specify project IDs explicitly.

For example, consider running a CustomJob in a Google Cloud project with ID PROJECT_ID. If you want to use the Python Client for Google BigQuery to access a BigQuery table in the same project, then do not try to infer the project in your training code:

Implicit project selection

from google.cloud import bigquery

client = bigquery.Client()

Instead use code that explicitly selects a project:

Explicit project selection

from google.cloud import bigquery

client = bigquery.Client(project=PROJECT_ID)

What's next