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 anEndpoint
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:
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.
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.
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.
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:
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:
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 CLI 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.
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.
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:
If you are creating a
CustomJob
, specify the service account's email address inCustomJob.jobSpec.serviceAccount
.Learn more about creating a
CustomJob
.If you are creating a
HyperparameterTuningJob
, specify the service account's email address inHyperparameterTuningJob.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 inTrainingPipeline.trainingTaskInputs.serviceAccount
.If you are creating a custom
TrainingPipeline
with hyperparameter tuning, specify the service account's email address inTrainingPipeline.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.
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.