Overview of the OS environment for a job's VMs

This document explains concepts for the operating system (OS) environment—the boot disks and OS image—for the Compute Engine virtual machine (VM) instances that run Batch jobs.

A job is executed by running the instructions on the boot disk of each of its VMs. Each boot disk contains a bootloader, file system, and OS. You can optionally configure the VM OS environment for a job by doing one of the following:

  • To configure only the software on the boot disks, specify the job's VM OS image.
  • To configure any properties of the boot disk—including the VM OS image, disk size, and/or disk type—customize the job's boot disks.

The following sections describe when to configure the OS environment, the default OS environment, VM OS image options, and boot disk options.

When to configure the OS environment

Review this section to determine whether to configure the VM OS image and/or boot disks when you create a job or use the default configuration.

Configure the VM OS image for a job in the following cases:

  • If the trusted images (compute.trustedImageProjects) policy constraint prevents you from creating a job with the default VM OS image.

    For more information about the trusted images policy constraint, see Control access to the VM OS images for Batch.

  • If you prefer not to or cannot use the default VM OS image for your job. For example, if the runnables that you've defined for a job require an application that is not supported by the default image, you might be able to specify a different public VM OS image. Alternatively, if you want to preinstall an application that is required for your job to help reduce runtime, you might want to create and specify a custom image.

Configure the boot disk for a job in the following cases:

  • If you prefer not to or cannot use the default boot disk for your job. For example, if the runnables or VM OS image that you've defined for a job require additional storage space on the boot disk, then you might need to customize the boot disk for a job to increase its size.

If you are still unsure if your job requires you to configure the VM OS image and/or boot disks, you can review the following section to understand the default configuration. Additionally, you might also just try to create and run the job with the default configuration. If the job fails with the default configuration, you can try to determine if the issue was caused by the VM OS image or boot disk by troubleshooting.

Otherwise, if you don't need and don't want to configure the VM OS image and/or boot disk for a job, leave these properties undefined to use the default configuration.

Default OS environment

Review this section to understand the default configuration for a job's VM OS image and boot disks. For example, you might use the default configuration as a reference when determining how you want to configure the OS environment for a job.

When you create a job and don't define the VM OS image, the job defaults to using one of the following VM OS images:

  • If the job only has container runnables, the job uses the latest version of the Batch Container-Optimized OS (COS) image.
  • Otherwise, the job uses the latest version of the Batch Debian image.

When you create a job and don't define the other properties of the boot disks, the job defaults to using the following options:

  • persistent disk type: the default persistent disk type for boot disks is pd-balanced.

  • size: the default size for each VM's boot disk is determined by the following formula for \({defaultBootDiskSize}\). Additionally, the default size is rounded to be at least 30 GB and at most 10,000 GB.

    \[{defaultBootDiskSize}={reservedSize}+({taskSize}*{parallelTasksPerVm})\]

    This formula has the following values:

    • \({reservedSize}\): the reserved size in GB for required software for the VM, such as the VM OS image. For the default boot disk size, Batch reserves 10 GB.

    • \({taskSize}\): the boot disk size for each task in GB, which is is determined by converting the units of the boot disk size per task (bootDiskMib) field.

    • \({parallelTasksPerVM}\): the maximum number of tasks that can run on a VM simultaneously. For more information, see the formula for \({parallelTasksPerVM}\).

  • interface: the interface is automatically selected as either NVMe or SCSI depending on the machine type of your job's VMs. You can optionally specify a machine type when you define the type of resources for a job to use. For the default interface of each machine type, see Choosing an interface in the Compute Engine documentation.

VM OS image options

The following sections describe the VM OS image options for Batch, including all the types of VM OS images that Batch jobs can support and the restrictions for the supported VM OS images. When you specify the VM OS image for a job, you can specify an image name or image family for any of the supported VM OS images that are allowed by the restrictions.

Supported VM OS images

Batch jobs can support the following types of VM OS images:

  • Public images: images that are provided and maintained by Google, open source communities, and third-party vendors. Specifically, Batch jobs can use public images from Batch or Compute Engine.

    • Batch images: images that are provided and maintained by Batch based on Compute Engine OSes, stored in the batch-custom-image image project, and are recommended for Batch jobs.

      Batch images are available in the following OSes. When you view image families and image names from Batch, the OS is indicated by the corresponding prefix.

      To see the specific image names and families from Batch that you can specify for a job, follow the steps to view VM OS images from Batch.

    • Compute Engine images: public images available on Compute Engine, which are described on the Operating system details page in the Compute Engine documentation.

      Batch only supports generally available (GA) Compute Engine images from the following OSes:

  • Custom images: images that you create, own, and control access to by using Compute Engine. Learn more about custom images in the Compute Engine documentation.

Restrictions for VM OS images

The supported VM OS images that a job can specify are subject to the following restrictions:

  • Batch images that are marked as deprecated might not be supported. The minimum supported lifetime for Batch images is the earliest of the following dates:

    • 60 days after the image's starting date. The starting date of a Batch image is indicated in the image name—for example, the batch-cos-stable-official-20230719-00-p00 image is from July 19, 2023 (20230719).
    • The date that the base Compute Engine OS version is deprecated. The date that each Compute Engine OS version is deprecated is listed on the Operating system details page in the Compute Engine documentation.

  • Certain job configurations require external access for the image. Specifically, when a job does not have external access and does not allow access through Cloud NAT or Private Google Access, only the following images are supported:

    • For jobs that use GPU(s) and only container runnable(s), only the default image (the latest Batch Container-Optimized OS image) is supported.
    • Otherwise, jobs only support Batch images.

  • If the trusted images policy constraint is enabled, you cannot use any VM OS images that the trusted image policy does not allow.

    An administrator for your project, folder, or organization can optionally configure the trusted images policy constraint to restrict the VM OS images that can be used to create boot disks. For example, the trusted images policy constraint can be used to require users to create VMs that contain approved software that meets your policy or security requirements. For more information, see Control access to VM OS images for Batch.

  • The VM OS image for your job must have the drivers for the interface of its boot disks and any persistent disk storage volumes installed. Most public images automatically install both NVMe and SCSI drivers, including all Batch images.

    You cannot configure the interface of persistent disks, so the VM OS image requires the drivers for the default interface.

  • If a job specifies any VM OS image that is neither a Batch image nor a custom image based on a Batch image, Batch installs required packages on the job's VMs after they start. These required packages can vary for different job configurations and change over time, and they are required for Batch to run the job.

Boot disk options

This section describes the options for the type and size of boot disks for Batch. When you customize the boot disks for a job, you can specify the VM OS image, type, and/or size. For information about specifying the VM OS image, see VM OS image options in this document instead.

For boot disk type, Batch supports all the persistent disk types in the Compute Engine documentation.

For boot disk size, Batch supports all sizes and increments for persistent disks in the Compute Engine documentation that meet the following requirements:

  • For Batch jobs, the minimum boot disk size is 30 GB.

  • For a Batch job to run properly, the boot disk size must be big enough to allocate the job's VM OS image and the tasks that run on each VM. For example, see the formula for the default boot disk size in this document.

What's next