This document explains how to specify a Batch job's service account, which influences the resources and applications that a job's VMs can access. If you do not specify a custom service account, jobs default to using the Compute Engine default service account, which is automatically attached to all VMs in a project by default. Therefore, using a custom service account provides greater control in managing a job's permissions and is a recommended best practice for limiting privilege.
Before you begin
- If you haven't used Batch before, review Get started with Batch and enable Batch by completing the prerequisites for projects and users.
-
To get the permissions that you need to create a job, ask your administrator to grant you the following IAM roles:
-
Batch Job Editor (
roles/batch.jobsEditor
) on the project -
Service Account User (
roles/iam.serviceAccountUser
) on the job's service account, which by default is the default Compute Engine service account -
View service accounts:
View Service Accounts (
roles/iam.serviceAccountViewer
) on the project
For more information about granting roles, see Manage access.
You might also be able to get the required permissions through custom roles or other predefined roles.
-
Batch Job Editor (
Create a job that uses a custom service account
Before creating a job that uses a custom service account, make sure that the service account you plan to use has the permissions required to create Batch jobs for your project. For more information, see Enable Batch for a project.
To create a job that uses a custom service account, select one of the following methods:
- Specify the custom service account in your job's definition, as shown in this section.
- Use a Compute Engine instance template and specify the custom service account both in your instance template and in your job's definition.
This section provides an example for how to create a job that uses a custom service account. You can create a job that uses a custom service account using the gcloud CLI or Batch API.
gcloud
To create a job that uses a custom service account using the
gcloud CLI, use the gcloud batch jobs submit
command
and specify the custom service account in the job's configuration file.
For example, to create a script job that uses a custom service account:
Create a JSON file in the current directory named
hello-world-service-account.json
with the following contents:{ "taskGroups": [ { "taskSpec": { "runnables": [ { "script": { "text": "echo Hello World! This is task $BATCH_TASK_INDEX." } } ] } } ], "allocationPolicy": { "serviceAccount": { "email": "SERVICE_ACCOUNT_EMAIL" } } }
where
SERVICE_ACCOUNT_EMAIL
is the email address of your service account. If theserviceAccount
field is not specified, the value is set to the default Compute Engine service account.Run the following command:
gcloud batch jobs submit example-service-account-job \ --location us-central1 \ --config hello-world-service-account.json
API
To create a job that uses a custom service account using the
Batch API, use the
jobs.create
method
and specify your custom service account in the allocationPolicy
field.
For example, to create a script job that uses a custom service account, make the following request:
POST https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/jobs?job_id=example-service-account-job
{
"taskGroups": [
{
"taskSpec": {
"runnables": [
{
"script": {
"text": "echo Hello World! This is task $BATCH_TASK_INDEX."
}
}
]
}
}
],
"allocationPolicy": {
"serviceAccount": {
"email": "SERVICE_ACCOUNT_EMAIL"
}
}
}
Replace the following:
PROJECT_ID
: the project ID of your project.SERVICE_ACCOUNT_EMAIL
: the email address of your service account. If theserviceAccount
field is not specified, the value is set to the default Compute Engine service account.
What's next
- If you have issues creating or running a job, see Troubleshooting.
- View jobs and tasks.
- Learn about more job creation options.