Using a custom service account

You can configure AI Platform Prediction to use a service account of your choice when it runs custom code to serve predictions. Specifically, you can specify a custom service account when you do one of the following:

Using a custom service account lets you customize what Google Cloud resources your custom serving code can access without granting overly broad permissions to the service account that your AI Platform Prediction uses by default.

The guide focuses on AI Platform Prediction resources' permissions to access other Google Cloud resources. To learn about the permissions that you need to access AI Platform Prediction resources themselves, read Access control.

Understanding the service agent

By default, AI Platform Prediction uses a service agent to serve online predictions from model versions that don't use custom containers. This service agent is identified by an email address with the following format:

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

Find the corresponding service account for your project in the Google Cloud console or by using the Google Cloud CLI:

Google Cloud console

Go to the IAM page in the Google Cloud console, select Include Google-provided role grants, and find the principal that matches the email address format described previously in this section. The service account also has the name Google Cloud ML Engine Service Agent.

Go to the IAM page


Run the following command in a Shell environment where you have initialized the gcloud CLI:

gcloud projects get-iam-policy PROJECT_ID \
  --flatten="bindings[].members" \
  --format="table(bindings.members)" \
  --filter="bindings.role:roles/ml.serviceAgent" \
  | grep serviceAccount:

Replace PROJECT_ID with the ID of your Google Cloud project.

This command outputs the following:


GOOGLE_MANAGED_SERVICE_ACCOUNT is the email address of your project's AI Platform service agent.

This service agent has permissions that are appropriate for most model versions. For example, it can read from Cloud Storage buckets in the same Google Cloud project.

If you need your custom prediction routines to run with additional permissions, you can assign additional Identity and Access Management (IAM) roles to this service account. For example, you can give it access to Cloud Storage buckets in other Google Cloud projects.

Service account used by default in custom containers

If your model version uses a custom container, then by default the container does not run using the AI Platform service agent; instead, it runs using a service account managed by AI Platform Prediction. This service account has permission to read model artifacts that AI Platform Prediction makes available at a URI stored in the AIP_STORAGE_URI environment variable.

You cannot customize the permissions of this service account used by default in custom containers. If you want to customize permissions available to your custom container, read the following sections to use a custom service account with your model version.

Using a custom service account

If you want to grant or limit Google Cloud permissions for a specific model version, use a custom service account in place of the service agent.

To do this, first set up a custom service account. Then specify the custom service account when you create a model version.

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 to provide your prediction-serving code with any permissions that it needs when it runs.

  3. If the user-managed service account is in a different project than your model versions, configure the user-managed service account so you can attach it to your model versions.

  1. Grant your 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 CLI to run the following command:

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

    In this command, replace the following placeholders:

    • GOOGLE_MANAGED_SERVICE_ACCOUNT: The email address of your project's Google Cloud ML Engine Service Agent. Learn how to find this email address in a previous section of this guide.

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

Specify the custom service account for your model version

To give your prediction-serving code access to a custom service account, specify the serviceAccount field when you create a model version. Recall that the model version must either use a custom container or a custom prediction routine.

If you use the gcloud CLI to create a model version, you can use the --service-account flag with the gcloud beta component. For example:

gcloud beta ai-platform versions create VERSION \
  --service-account CUSTOM_SERVICE_ACCOUNT \

Replace the following:

What's next