Specify the VM OS image for a job

This page describes how to specify the operating system (OS) image for the virtual machine (VM) instances that a job runs on. If you also want to customize other properties of the job's boot disks, see Create and run a job that uses custom boot disks instead.

To learn more about VM OS images and which VM OS images you can use, see VM OS environment overview.

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

Create and run a job that uses a specific VM OS image

Specify the VM OS image when you are creating a job by selecting one of the following methods:

Use a Compute Engine instance template that specifies a VM OS image. If you want to use a VM instance template while creating this job, you must specify the VM OS image in the VM instance template. For instructions, see Define job resources using a VM instance template.
Use the VM OS image field. As the following instructions explain, you can specify the VM OS image in the image field by using the gcloud CLI or Batch API.

gcloud

Create a JSON file that specifies your job's configuration details. To specify the VM OS image for the job, include the image field.

For example, to create a basic script job that uses a specific VM OS image, create a JSON file with the following contents:
```
{
    "taskGroups": [
        {
            "taskSpec": {
                "runnables": [
                    {
                        "script": {
                            "text": "echo Hello world from task ${BATCH_TASK_INDEX}."
                        }
                    }
                ]
            },
            "taskCount": 3,
            "parallelism": 1
        }
    ],
    "allocationPolicy": {
      "instances": [
        {
          "policy": {
            "bootDisk": {
              "image": "VM_OS_IMAGE_URI"
            }
          }
        }
      ]
    },
    "logsPolicy": {
    "destination": "CLOUD_LOGGING"
  }
}
```
Replace VM_OS_IMAGE_URI with a relative resource name of the VM OS image. Use one of the following options:
- Specify a Batch OS prefix. To use the latest image of a specific Batch OS, use the following format:
```
BATCH_OS_PREFIX
```
  Replace BATCH_OS_PREFIX with one of the Batch VM OS image prefixes—for example, batch-debian is the prefix for the Batch Debian OS.
- Specify an image family. To use the latest image from a specific image family, use the following format:
```
projects/IMAGE_PROJECT_ID/global/images/family/IMAGE_FAMILY
```
  Replace the following:
  - IMAGE_PROJECT_ID: the project ID of the project that contains the image. For example, for all Batch images, specify batch-custom-image.
  - IMAGE_FAMILY: the image family, which includes one or more specific images and represents the type and major version of the OS. For example, to see all the VM OS image families from Batch, view a list of VM OS images.
- Specify an image version. To use a specific version of a VM OS image, use the following format:
```
projects/IMAGE_PROJECT_ID/global/images/IMAGE_NAME
```
  Replace the following:
  - IMAGE_PROJECT_ID: the project ID of the project that contains the image. For example, for all Batch images, specify batch-custom-image.
  - IMAGE_NAME: the image name, which represents a specific version of a VM OS image. For example, to see all the VM OS image versions from Batch, view a list of VM OS images.
To create the job, run the following gcloud batch jobs submit command:
```
gcloud batch jobs submit JOB_NAME \
    --location LOCATION \
    --config JSON_CONFIGURATION_FILE
```
Replace the following:
- JOB_NAME: the name for this job.
- LOCATION: the location for this job.
- JSON_CONFIGURATION_FILE: the path to the JSON file with the job's configuration details.

API

To create a job using the Batch API, use the jobs.create method and specify your job's configuration details. To specify the VM OS image for the job, include the image field. For example, to create a basic script job that uses a specific VM OS image, make the following POST request:

POST https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs?job_id=JOB_NAME

{
    "taskGroups": [
        {
            "taskSpec": {
                "runnables": [
                    {
                        "script": {
                            "text": "echo Hello world from task ${BATCH_TASK_INDEX}."
                        }
                    }
                ]
            },
            "taskCount": 3,
            "parallelism": 1
        }
    ],
    "allocationPolicy": {
      "instances": [
        {
          "policy": {
            "bootDisk": {
              "image": "VM_OS_IMAGE_URI"
            }
          }
        }
      ]
    },
    "logsPolicy": {
    "destination": "CLOUD_LOGGING"
  }
}

Replace the following:

PROJECT_ID: the project ID of your project.
LOCATION: the location for this job.
JOB_NAME: the name for this job.
VM_OS_IMAGE_URI: a relative resource name of the VM OS image. Use one of the following options:
- Specify a Batch OS prefix. To use the latest image of a specific Batch OS, use the following format:
```
BATCH_OS_PREFIX
```
Replace BATCH_OS_PREFIX with one of the Batch VM OS image prefixes—for example, batch-debian is the prefix for the Batch Debian OS.
- Specify an image family. To use the latest image from a specific image family, use the following format:
```
projects/IMAGE_PROJECT_ID/global/images/family/IMAGE_FAMILY
```
  Replace the following:
  - IMAGE_PROJECT_ID: the project ID of the project that contains the image. For example, for all Batch images, specify batch-custom-image.
  - IMAGE_FAMILY: the image family, which includes one or more specific images and represents the type and major version of the OS. For example, to see all the VM OS image families from Batch, view a list of VM OS images.
- Specify an image version. To use a specific version of a VM OS image, use the following format:
```
projects/IMAGE_PROJECT_ID/global/images/IMAGE_NAME
```
  Replace the following:
  - IMAGE_PROJECT_ID: the project ID of the project that contains the image. For example, for all Batch images, specify batch-custom-image.
  - IMAGE_NAME: the image name, which represents a specific version of a VM OS image. For example, to see all the VM OS image versions from Batch, view a list of VM OS images.

What's next

If you have issues creating or running a job, see Troubleshooting.
Learn more about VM OS images.
Learn more about creating a job.
Learn how to view jobs and tasks.