Using a custom service account

Beta

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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:

• Create a model version that uses a custom container.
• Create a model version that uses a custom prediction routine.

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:

[e-mail]

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

gcloud

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:

serviceAccount:GOOGLE_MANAGED_SERVICE_ACCOUNT

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

Note: If you have granted the Cloud ML Service Agent role (roles/ml.serviceAgent) to additional members of your project, you might see multiple lines of output. GOOGLE_MANAGED_SERVICE_ACCOUNT is the email address that matches the format described previously in this section.

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.

   Note: Even if you plan to serve predictions with a custom container, there is no need to grant your custom service account Artifact Registry permissions. AI Platform Prediction does not use your custom service account to pull container images. It only uses the custom service account to run your prediction-serving code.

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 \
     CUSTOM_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.

   Note: This command grants your project's AI Platform 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 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:

• VERSION: A name for the model version.
• CUSTOM_SERVICE_ACCOUNT: The email address of the user-managed service account that you set up in a previous section of this guide.
• ...: Additional options for the model version.

Note: To specify the serviceAccount field, you (the user deploying the model version) must have the iam.serviceAccounts.actAs permission for the service account. If you are an owner or editor of the Google Cloud project that you are working in, you already have this permission. Otherwise, ask a project administrator to give you this permission by granting you the Service Account User role (roles/iam.serviceAccountUser) for the custom service account.

What's next

• Learn how to create a model version that uses a custom container

• Learn how to create a model version that uses a custom prediction routine.

• Learn more about service accounts.