As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Types for Google Cloud Batch v1 API

class google.cloud.batch_v1.types.AllocationPolicy(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

A Job’s resource allocation policy describes when, where, and how compute resources should be allocated for the Job.

location

Location where compute resources should be allocated for the Job.

Type

google.cloud.batch_v1.types.AllocationPolicy.LocationPolicy

instances

Describe instances that can be created by this AllocationPolicy. Only instances[0] is supported now.

Type

MutableSequence[google.cloud.batch_v1.types.AllocationPolicy.InstancePolicyOrTemplate]

service_account

Defines the service account for Batch-created VMs. If omitted, the default Compute Engine service account is used. Must match the service account specified in any used instance template configured in the Batch job.

Includes the following fields:

  • email: The service account’s email address. If not set, the default Compute Engine service account is used.

  • scopes: Additional OAuth scopes to grant the service account, beyond the default cloud-platform scope. (list of strings)

Type

google.cloud.batch_v1.types.ServiceAccount

labels

Labels applied to all VM instances and other resources created by AllocationPolicy. Labels could be user provided or system generated. You can assign up to 64 labels. Google Compute Engine label restrictions apply. Label names that start with “goog-” or “google-” are reserved.

Type

MutableMapping[str, str]

network

The network policy.

If you define an instance template in the InstancePolicyOrTemplate field, Batch will use the network settings in the instance template instead of this field.

Type

google.cloud.batch_v1.types.AllocationPolicy.NetworkPolicy

placement

The placement policy.

Type

google.cloud.batch_v1.types.AllocationPolicy.PlacementPolicy

tags

Optional. Tags applied to the VM instances.

The tags identify valid sources or targets for network firewalls. Each tag must be 1-63 characters long, and comply with RFC1035.

Type

MutableSequence[str]

class Accelerator(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Accelerator describes Compute Engine accelerators to be attached to the VM.

type_

The accelerator type. For example, “nvidia-tesla-t4”. See gcloud compute accelerator-types list.

Type

str

count

The number of accelerators of this type.

Type

int

install_gpu_drivers

Deprecated: please use instances[0].install_gpu_drivers instead.

Type

bool

driver_version

Optional. The NVIDIA GPU driver version that should be installed for this type.

You can define the specific driver version such as “470.103.01”, following the driver version requirements in https://cloud.google.com/compute/docs/gpus/install-drivers-gpu#minimum-driver. Batch will install the specific accelerator driver if qualified.

Type

str

class AttachedDisk(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

A new or an existing persistent disk (PD) or a local ssd attached to a VM instance.

This message has oneof fields (mutually exclusive fields). For each oneof, at most one member field can be set at the same time. Setting any member of the oneof automatically clears all other members.

new_disk

This field is a member of oneof attached.

Type

google.cloud.batch_v1.types.AllocationPolicy.Disk

existing_disk

Name of an existing PD.

This field is a member of oneof attached.

Type

str

device_name

Device name that the guest operating system will see. It is used by Runnable.volumes field to mount disks. So please specify the device_name if you want Batch to help mount the disk, and it should match the device_name field in volumes.

Type

str

class Disk(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

A new persistent disk or a local ssd. A VM can only have one local SSD setting but multiple local SSD partitions. See https://cloud.google.com/compute/docs/disks#pdspecs and https://cloud.google.com/compute/docs/disks#localssds.

This message has oneof fields (mutually exclusive fields). For each oneof, at most one member field can be set at the same time. Setting any member of the oneof automatically clears all other members.

image

URL for a VM image to use as the data source for this disk. For example, the following are all valid URLs:

  • Specify the image by its family name: projects/{project}/global/images/family/{image_family}

  • Specify the image version: projects/{project}/global/images/{image_version}

You can also use Batch customized image in short names. The following image values are supported for a boot disk:

  • batch-debian: use Batch Debian images.

  • batch-cos: use Batch Container-Optimized images.

  • batch-hpc-rocky: use Batch HPC Rocky Linux images.

This field is a member of oneof data_source.

Type

str

snapshot

Name of a snapshot used as the data source. Snapshot is not supported as boot disk now.

This field is a member of oneof data_source.

Type

str

type_

Disk type as shown in gcloud compute disk-types list. For example, local SSD uses type “local-ssd”. Persistent disks and boot disks use “pd-balanced”, “pd-extreme”, “pd-ssd” or “pd-standard”. If not specified, “pd-standard” will be used as the default type for non-boot disks, “pd-balanced” will be used as the default type for boot disks.

Type

str

size_gb

Disk size in GB.

Non-Boot Disk: If the type specifies a persistent disk, this field is ignored if data_source is set as image or snapshot. If the type specifies a local SSD, this field should be a multiple of 375 GB, otherwise, the final size will be the next greater multiple of 375 GB.

Boot Disk: Batch will calculate the boot disk size based on source image and task requirements if you do not speicify the size. If both this field and the boot_disk_mib field in task spec’s compute_resource are defined, Batch will only honor this field. Also, this field should be no smaller than the source disk’s size when the data_source is set as snapshot or image. For example, if you set an image as the data_source field and the image’s default disk size 30 GB, you can only use this field to make the disk larger or equal to 30 GB.

Type

int

disk_interface

Local SSDs are available through both “SCSI” and “NVMe” interfaces. If not indicated, “NVMe” will be the default one for local ssds. This field is ignored for persistent disks as the interface is chosen automatically. See https://cloud.google.com/compute/docs/disks/persistent-disks#choose_an_interface.

Type

str

class InstancePolicy(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

InstancePolicy describes an instance type and resources attached to each VM created by this InstancePolicy.

machine_type

The Compute Engine machine type.

Type

str

min_cpu_platform

The minimum CPU platform. See https://cloud.google.com/compute/docs/instances/specify-min-cpu-platform.

Type

str

provisioning_model

The provisioning model.

Type

google.cloud.batch_v1.types.AllocationPolicy.ProvisioningModel

accelerators

The accelerators attached to each VM instance.

Type

MutableSequence[google.cloud.batch_v1.types.AllocationPolicy.Accelerator]

boot_disk

Boot disk to be created and attached to each VM by this InstancePolicy. Boot disk will be deleted when the VM is deleted. Batch API now only supports booting from image.

Type

google.cloud.batch_v1.types.AllocationPolicy.Disk

disks

Non-boot disks to be attached for each VM created by this InstancePolicy. New disks will be deleted when the VM is deleted. A non-boot disk is a disk that can be of a device with a file system or a raw storage drive that is not ready for data storage and accessing.

Type

MutableSequence[google.cloud.batch_v1.types.AllocationPolicy.AttachedDisk]

reservation

Optional. If specified, VMs will consume only the specified reservation. If not specified (default), VMs will consume any applicable reservation.

Type

str

class InstancePolicyOrTemplate(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

InstancePolicyOrTemplate lets you define the type of resources to use for this job either with an InstancePolicy or an instance template. If undefined, Batch picks the type of VM to use and doesn’t include optional VM resources such as GPUs and extra disks.

This message has oneof fields (mutually exclusive fields). For each oneof, at most one member field can be set at the same time. Setting any member of the oneof automatically clears all other members.

policy

InstancePolicy.

This field is a member of oneof policy_template.

Type

google.cloud.batch_v1.types.AllocationPolicy.InstancePolicy

instance_template

Name of an instance template used to create VMs. Named the field as ‘instance_template’ instead of ‘template’ to avoid C++ keyword conflict.

Batch only supports global instance templates. You can specify the global instance template as a full or partial URL.

This field is a member of oneof policy_template.

Type

str

install_gpu_drivers

Set this field true if you want Batch to help fetch drivers from a third party location and install them for GPUs specified in policy.accelerators or instance_template on your behalf. Default is false.

For Container-Optimized Image cases, Batch will install the accelerator driver following milestones of https://cloud.google.com/container-optimized-os/docs/release-notes. For non Container-Optimized Image cases, following https://github.com/GoogleCloudPlatform/compute-gpu-installation/blob/main/linux/install_gpu_driver.py.

Type

bool

install_ops_agent

Optional. Set this field true if you want Batch to install Ops Agent on your behalf. Default is false.

Type

bool

block_project_ssh_keys

Optional. Set this field to true if you want Batch to block project-level SSH keys from accessing this job’s VMs. Alternatively, you can configure the job to specify a VM instance template that blocks project-level SSH keys. In either case, Batch blocks project-level SSH keys while creating the VMs for this job.

Batch allows project-level SSH keys for a job’s VMs only if all the following are true:

  • This field is undefined or set to false.

  • The job’s VM instance template (if any) doesn’t block project-level SSH keys.

Notably, you can override this behavior by manually updating a VM to block or allow project-level SSH keys. For more information about blocking project-level SSH keys, see the Compute Engine documentation: https://cloud.google.com/compute/docs/connect/restrict-ssh-keys#block-keys

Type

bool

class LabelsEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

class LocationPolicy(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

allowed_locations

A list of allowed location names represented by internal URLs.

Each location can be a region or a zone. Only one region or multiple zones in one region is supported now. For example, [“regions/us-central1”] allow VMs in any zones in region us-central1. [“zones/us-central1-a”, “zones/us-central1-c”] only allow VMs in zones us-central1-a and us-central1-c.

Mixing locations from different regions would cause errors. For example, [“regions/us-central1”, “zones/us-central1-a”, “zones/us-central1-b”, “zones/us-west1-a”] contains locations from two distinct regions: us-central1 and us-west1. This combination will trigger an error.

Type

MutableSequence[str]

class NetworkInterface(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

A network interface.

network

The URL of an existing network resource. You can specify the network as a full or partial URL.

For example, the following are all valid URLs:

Type

str

subnetwork

The URL of an existing subnetwork resource in the network. You can specify the subnetwork as a full or partial URL.

For example, the following are all valid URLs:

Type

str

no_external_ip_address

Default is false (with an external IP address). Required if no external public IP address is attached to the VM. If no external public IP address, additional configuration is required to allow the VM to access Google Services. See https://cloud.google.com/vpc/docs/configure-private-google-access and https://cloud.google.com/nat/docs/gce-example#create-nat for more information.

Type

bool

class NetworkPolicy(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

NetworkPolicy describes VM instance network configurations.

network_interfaces

Network configurations.

Type

MutableSequence[google.cloud.batch_v1.types.AllocationPolicy.NetworkInterface]

class PlacementPolicy(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

PlacementPolicy describes a group placement policy for the VMs controlled by this AllocationPolicy.

collocation

UNSPECIFIED vs. COLLOCATED (default UNSPECIFIED). Use COLLOCATED when you want VMs to be located close to each other for low network latency between the VMs. No placement policy will be generated when collocation is UNSPECIFIED.

Type

str

max_distance

When specified, causes the job to fail if more than max_distance logical switches are required between VMs. Batch uses the most compact possible placement of VMs even when max_distance is not specified. An explicit max_distance makes that level of compactness a strict requirement. Not yet implemented

Type

int

class ProvisioningModel(value)[source]

Bases: proto.enums.Enum

Compute Engine VM instance provisioning model.

Values:
PROVISIONING_MODEL_UNSPECIFIED (0):

Unspecified.

STANDARD (1):

Standard VM.

SPOT (2):

SPOT VM.

PREEMPTIBLE (3):

Preemptible VM (PVM).

Above SPOT VM is the preferable model for preemptible VM instances: the old preemptible VM model (indicated by this field) is the older model, and has been migrated to use the SPOT model as the underlying technology. This old model will still be supported.

class google.cloud.batch_v1.types.ComputeResource(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Compute resource requirements.

ComputeResource defines the amount of resources required for each task. Make sure your tasks have enough resources to successfully run. If you also define the types of resources for a job to use with the InstancePolicyOrTemplate field, make sure both fields are compatible with each other.

cpu_milli

The milliCPU count.

cpuMilli defines the amount of CPU resources per task in milliCPU units. For example, 1000 corresponds to 1 vCPU per task. If undefined, the default value is 2000.

If you also define the VM’s machine type using the machineType in InstancePolicy field or inside the instanceTemplate in the InstancePolicyOrTemplate field, make sure the CPU resources for both fields are compatible with each other and with how many tasks you want to allow to run on the same VM at the same time.

For example, if you specify the n2-standard-2 machine type, which has 2 vCPUs each, you are recommended to set cpuMilli no more than 2000, or you are recommended to run two tasks on the same VM if you set cpuMilli to 1000 or less.

Type

int

memory_mib

Memory in MiB.

memoryMib defines the amount of memory per task in MiB units. If undefined, the default value is 2000. If you also define the VM’s machine type using the machineType in InstancePolicy field or inside the instanceTemplate in the InstancePolicyOrTemplate field, make sure the memory resources for both fields are compatible with each other and with how many tasks you want to allow to run on the same VM at the same time.

For example, if you specify the n2-standard-2 machine type, which has 8 GiB each, you are recommended to set memoryMib to no more than 8192, or you are recommended to run two tasks on the same VM if you set memoryMib to 4096 or less.

Type

int

boot_disk_mib

Extra boot disk size in MiB for each task.

Type

int

class google.cloud.batch_v1.types.CreateJobRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

CreateJob Request.

parent

Required. The parent resource name where the Job will be created. Pattern: “projects/{project}/locations/{location}”.

Type

str

job_id

ID used to uniquely identify the Job within its parent scope. This field should contain at most 63 characters and must start with lowercase characters. Only lowercase characters, numbers and ‘-’ are accepted. The ‘-’ character cannot be the first or the last one. A system generated ID will be used if the field is not set.

The job.name field in the request will be ignored and the created resource name of the Job will be “{parent}/jobs/{job_id}”.

Type

str

job

Required. The Job to create.

Type

google.cloud.batch_v1.types.Job

request_id

Optional. An optional request ID to identify requests. Specify a unique request ID so that if you must retry your request, the server will know to ignore the request if it has already been completed. The server will guarantee that for at least 60 minutes since the first request.

For example, consider a situation where you make an initial request and the request times out. If you make the request again with the same request ID, the server can check if original operation with the same request ID was received, and if so, will ignore the second request. This prevents clients from accidentally creating duplicate commitments.

The request ID must be a valid UUID with the exception that zero UUID is not supported (00000000-0000-0000-0000-000000000000).

Type

str

class google.cloud.batch_v1.types.DeleteJobRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

DeleteJob Request.

name

Job name.

Type

str

reason

Optional. Reason for this deletion.

Type

str

request_id

Optional. An optional request ID to identify requests. Specify a unique request ID so that if you must retry your request, the server will know to ignore the request if it has already been completed. The server will guarantee that for at least 60 minutes after the first request.

For example, consider a situation where you make an initial request and the request times out. If you make the request again with the same request ID, the server can check if original operation with the same request ID was received, and if so, will ignore the second request. This prevents clients from accidentally creating duplicate commitments.

The request ID must be a valid UUID with the exception that zero UUID is not supported (00000000-0000-0000-0000-000000000000).

Type

str

class google.cloud.batch_v1.types.Environment(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

An Environment describes a collection of environment variables to set when executing Tasks.

variables

A map of environment variable names to values.

Type

MutableMapping[str, str]

secret_variables

A map of environment variable names to Secret Manager secret names. The VM will access the named secrets to set the value of each environment variable.

Type

MutableMapping[str, str]

encrypted_variables

An encrypted JSON dictionary where the key/value pairs correspond to environment variable names and their values.

Type

google.cloud.batch_v1.types.Environment.KMSEnvMap

class KMSEnvMap(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

key_name

The name of the KMS key that will be used to decrypt the cipher text.

Type

str

cipher_text

The value of the cipherText response from the encrypt method.

Type

str

class SecretVariablesEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

class VariablesEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

class google.cloud.batch_v1.types.GCS(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Represents a Google Cloud Storage volume.

remote_path

Remote path, either a bucket name or a subdirectory of a bucket, e.g.: bucket_name, bucket_name/subdirectory/

Type

str

class google.cloud.batch_v1.types.GetJobRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

GetJob Request.

name

Required. Job name.

Type

str

class google.cloud.batch_v1.types.GetTaskRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Request for a single Task by name.

name

Required. Task name.

Type

str

class google.cloud.batch_v1.types.Job(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

The Cloud Batch Job description.

name

Output only. Job name. For example: “projects/123456/locations/us-central1/jobs/job01”.

Type

str

uid

Output only. A system generated unique ID for the Job.

Type

str

priority

Priority of the Job. The valid value range is [0, 100). Default value is 0. Higher value indicates higher priority. A job with higher priority value is more likely to run earlier if all other requirements are satisfied.

Type

int

task_groups

Required. TaskGroups in the Job. Only one TaskGroup is supported now.

Type

MutableSequence[google.cloud.batch_v1.types.TaskGroup]

allocation_policy

Compute resource allocation for all TaskGroups in the Job.

Type

google.cloud.batch_v1.types.AllocationPolicy

labels

Labels for the Job. Labels could be user provided or system generated. For example, “labels”: { “department”: “finance”, “environment”: “test” } You can assign up to 64 labels. Google Compute Engine label restrictions apply. Label names that start with “goog-” or “google-” are reserved.

Type

MutableMapping[str, str]

status

Output only. Job status. It is read only for users.

Type

google.cloud.batch_v1.types.JobStatus

create_time

Output only. When the Job was created.

Type

google.protobuf.timestamp_pb2.Timestamp

update_time

Output only. The last time the Job was updated.

Type

google.protobuf.timestamp_pb2.Timestamp

logs_policy

Log preservation policy for the Job.

Type

google.cloud.batch_v1.types.LogsPolicy

notifications

Notification configurations.

Type

MutableSequence[google.cloud.batch_v1.types.JobNotification]

class LabelsEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

class google.cloud.batch_v1.types.JobNotification(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Notification configurations.

pubsub_topic

The Pub/Sub topic where notifications for the job, like state changes, will be published. If undefined, no Pub/Sub notifications are sent for this job.

Specify the topic using the following format: projects/{project}/topics/{topic}. Notably, if you want to specify a Pub/Sub topic that is in a different project than the job, your administrator must grant your project’s Batch service agent permission to publish to that topic.

For more information about configuring Pub/Sub notifications for a job, see https://cloud.google.com/batch/docs/enable-notifications.

Type

str

message

The attribute requirements of messages to be sent to this Pub/Sub topic. Without this field, no message will be sent.

Type

google.cloud.batch_v1.types.JobNotification.Message

class Message(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Message details. Describe the conditions under which messages will be sent. If no attribute is defined, no message will be sent by default. One message should specify either the job or the task level attributes, but not both. For example, job level: JOB_STATE_CHANGED and/or a specified new_job_state; task level: TASK_STATE_CHANGED and/or a specified new_task_state.

type_

The message type.

Type

google.cloud.batch_v1.types.JobNotification.Type

new_job_state

The new job state.

Type

google.cloud.batch_v1.types.JobStatus.State

new_task_state

The new task state.

Type

google.cloud.batch_v1.types.TaskStatus.State

class Type(value)[source]

Bases: proto.enums.Enum

The message type.

Values:
TYPE_UNSPECIFIED (0):

Unspecified.

JOB_STATE_CHANGED (1):

Notify users that the job state has changed.

TASK_STATE_CHANGED (2):

Notify users that the task state has changed.

class google.cloud.batch_v1.types.JobStatus(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Job status.

state

Job state

Type

google.cloud.batch_v1.types.JobStatus.State

status_events

Job status events

Type

MutableSequence[google.cloud.batch_v1.types.StatusEvent]

task_groups

Aggregated task status for each TaskGroup in the Job. The map key is TaskGroup ID.

Type

MutableMapping[str, google.cloud.batch_v1.types.JobStatus.TaskGroupStatus]

run_duration

The duration of time that the Job spent in status RUNNING.

Type

google.protobuf.duration_pb2.Duration

class InstanceStatus(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

VM instance status.

machine_type

The Compute Engine machine type.

Type

str

provisioning_model

The VM instance provisioning model.

Type

google.cloud.batch_v1.types.AllocationPolicy.ProvisioningModel

task_pack

The max number of tasks can be assigned to this instance type.

Type

int

boot_disk

The VM boot disk.

Type

google.cloud.batch_v1.types.AllocationPolicy.Disk

class State(value)[source]

Bases: proto.enums.Enum

Valid Job states.

Values:
STATE_UNSPECIFIED (0):

Job state unspecified.

QUEUED (1):

Job is admitted (validated and persisted) and waiting for resources.

SCHEDULED (2):

Job is scheduled to run as soon as resource allocation is ready. The resource allocation may happen at a later time but with a high chance to succeed.

RUNNING (3):

Resource allocation has been successful. At least one Task in the Job is RUNNING.

SUCCEEDED (4):

All Tasks in the Job have finished successfully.

FAILED (5):

At least one Task in the Job has failed.

DELETION_IN_PROGRESS (6):

The Job will be deleted, but has not been deleted yet. Typically this is because resources used by the Job are still being cleaned up.

class TaskGroupStatus(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Aggregated task status for a TaskGroup.

counts

Count of task in each state in the TaskGroup. The map key is task state name.

Type

MutableMapping[str, int]

instances

Status of instances allocated for the TaskGroup.

Type

MutableSequence[google.cloud.batch_v1.types.JobStatus.InstanceStatus]

class CountsEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

class TaskGroupsEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

class google.cloud.batch_v1.types.LifecyclePolicy(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

LifecyclePolicy describes how to deal with task failures based on different conditions.

action

Action to execute when ActionCondition is true. When RETRY_TASK is specified, we will retry failed tasks if we notice any exit code match and fail tasks if no match is found. Likewise, when FAIL_TASK is specified, we will fail tasks if we notice any exit code match and retry tasks if no match is found.

Type

google.cloud.batch_v1.types.LifecyclePolicy.Action

action_condition

Conditions that decide why a task failure is dealt with a specific action.

Type

google.cloud.batch_v1.types.LifecyclePolicy.ActionCondition

class Action(value)[source]

Bases: proto.enums.Enum

Action on task failures based on different conditions.

Values:
ACTION_UNSPECIFIED (0):

Action unspecified.

RETRY_TASK (1):

Action that tasks in the group will be scheduled to re-execute.

FAIL_TASK (2):

Action that tasks in the group will be stopped immediately.

class ActionCondition(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Conditions for actions to deal with task failures.

exit_codes

Exit codes of a task execution. If there are more than 1 exit codes, when task executes with any of the exit code in the list, the condition is met and the action will be executed.

Type

MutableSequence[int]

class google.cloud.batch_v1.types.ListJobsRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

ListJob Request.

parent

Parent path.

Type

str

filter

List filter.

Type

str

order_by

Optional. Sort results. Supported are “name”, “name desc”, “create_time”, and “create_time desc”.

Type

str

page_size

Page size.

Type

int

page_token

Page token.

Type

str

class google.cloud.batch_v1.types.ListJobsResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

ListJob Response.

jobs

Jobs.

Type

MutableSequence[google.cloud.batch_v1.types.Job]

next_page_token

Next page token.

Type

str

unreachable

Locations that could not be reached.

Type

MutableSequence[str]

class google.cloud.batch_v1.types.ListTasksRequest(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

ListTasks Request.

parent

Required. Name of a TaskGroup from which Tasks are being requested. Pattern: “projects/{project}/locations/{location}/jobs/{job}/taskGroups/{task_group}”.

Type

str

filter

Task filter, null filter matches all Tasks. Filter string should be of the format State=TaskStatus.State e.g. State=RUNNING

Type

str

page_size

Page size.

Type

int

page_token

Page token.

Type

str

class google.cloud.batch_v1.types.ListTasksResponse(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

ListTasks Response.

tasks

Tasks.

Type

MutableSequence[google.cloud.batch_v1.types.Task]

next_page_token

Next page token.

Type

str

unreachable

Locations that could not be reached.

Type

MutableSequence[str]

class google.cloud.batch_v1.types.LogsPolicy(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

LogsPolicy describes how outputs from a Job’s Tasks (stdout/stderr) will be preserved.

destination

Where logs should be saved.

Type

google.cloud.batch_v1.types.LogsPolicy.Destination

logs_path

The path to which logs are saved when the destination = PATH. This can be a local file path on the VM, or under the mount point of a Persistent Disk or Filestore, or a Cloud Storage path.

Type

str

cloud_logging_option

Optional. Additional settings for Cloud Logging. It will only take effect when the destination of LogsPolicy is set to CLOUD_LOGGING.

Type

google.cloud.batch_v1.types.LogsPolicy.CloudLoggingOption

class CloudLoggingOption(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

CloudLoggingOption contains additional settings for Cloud Logging logs generated by Batch job.

use_generic_task_monitored_resource

Optional. Set this flag to true to change the monitored resource type for Cloud Logging logs generated by this Batch job from the `batch.googleapis.com/Job <https://cloud.google.com/monitoring/api/resources#tag_batch.googleapis.com/Job>`__ type to the formerly used `generic_task <https://cloud.google.com/monitoring/api/resources#tag_generic_task>`__ type.

Type

bool

class Destination(value)[source]

Bases: proto.enums.Enum

The destination (if any) for logs.

Values:
DESTINATION_UNSPECIFIED (0):

Logs are not preserved.

CLOUD_LOGGING (1):

Logs are streamed to Cloud Logging.

PATH (2):

Logs are saved to a file path.

class google.cloud.batch_v1.types.NFS(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Represents an NFS volume.

server

The IP address of the NFS.

Type

str

remote_path

Remote source path exported from the NFS, e.g., “/share”.

Type

str

class google.cloud.batch_v1.types.OperationMetadata(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Represents the metadata of the long-running operation.

create_time

Output only. The time the operation was created.

Type

google.protobuf.timestamp_pb2.Timestamp

end_time

Output only. The time the operation finished running.

Type

google.protobuf.timestamp_pb2.Timestamp

target

Output only. Server-defined resource path for the target of the operation.

Type

str

verb

Output only. Name of the verb executed by the operation.

Type

str

status_message

Output only. Human-readable status of the operation, if any.

Type

str

requested_cancellation

Output only. Identifies whether the user has requested cancellation of the operation. Operations that have successfully been cancelled have [Operation.error][] value with a [google.rpc.Status.code][google.rpc.Status.code] of 1, corresponding to Code.CANCELLED.

Type

bool

api_version

Output only. API version used to start the operation.

Type

str

class google.cloud.batch_v1.types.Runnable(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Runnable describes instructions for executing a specific script or container as part of a Task.

This message has oneof fields (mutually exclusive fields). For each oneof, at most one member field can be set at the same time. Setting any member of the oneof automatically clears all other members.

container

Container runnable.

This field is a member of oneof executable.

Type

google.cloud.batch_v1.types.Runnable.Container

script

Script runnable.

This field is a member of oneof executable.

Type

google.cloud.batch_v1.types.Runnable.Script

barrier

Barrier runnable.

This field is a member of oneof executable.

Type

google.cloud.batch_v1.types.Runnable.Barrier

display_name

Optional. DisplayName is an optional field that can be provided by the caller. If provided, it will be used in logs and other outputs to identify the script, making it easier for users to understand the logs. If not provided the index of the runnable will be used for outputs.

Type

str

ignore_exit_status

Normally, a runnable that returns a non-zero exit status fails and causes the task to fail. However, you can set this field to true to allow the task to continue executing its other runnables even if this runnable fails.

Type

bool

background

Normally, a runnable that doesn’t exit causes its task to fail. However, you can set this field to true to configure a background runnable. Background runnables are allowed continue running in the background while the task executes subsequent runnables. For example, background runnables are useful for providing services to other runnables or providing debugging-support tools like SSH servers.

Specifically, background runnables are killed automatically (if they have not already exited) a short time after all foreground runnables have completed. Even though this is likely to result in a non-zero exit status for the background runnable, these automatic kills are not treated as task failures.

Type

bool

always_run

By default, after a Runnable fails, no further Runnable are executed. This flag indicates that this Runnable must be run even if the Task has already failed. This is useful for Runnables that copy output files off of the VM or for debugging.

The always_run flag does not override the Task’s overall max_run_duration. If the max_run_duration has expired then no further Runnables will execute, not even always_run Runnables.

Type

bool

environment

Environment variables for this Runnable (overrides variables set for the whole Task or TaskGroup).

Type

google.cloud.batch_v1.types.Environment

timeout

Timeout for this Runnable.

Type

google.protobuf.duration_pb2.Duration

labels

Labels for this Runnable.

Type

MutableMapping[str, str]

class Barrier(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

A barrier runnable automatically blocks the execution of subsequent runnables until all the tasks in the task group reach the barrier.

name

Barriers are identified by their index in runnable list. Names are not required, but if present should be an identifier.

Type

str

class Container(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Container runnable.

image_uri

Required. The URI to pull the container image from.

Type

str

commands

Required for some container images. Overrides the CMD specified in the container. If there is an ENTRYPOINT (either in the container image or with the entrypoint field below) then these commands are appended as arguments to the ENTRYPOINT.

Type

MutableSequence[str]

entrypoint

Required for some container images. Overrides the ENTRYPOINT specified in the container.

Type

str

volumes

Volumes to mount (bind mount) from the host machine files or directories into the container, formatted to match --volume option for the docker run command—for example, /foo:/bar or /foo:/bar:ro.

If the TaskSpec.Volumes field is specified but this field is not, Batch will mount each volume from the host machine to the container with the same mount path by default. In this case, the default mount option for containers will be read-only (ro) for existing persistent disks and read-write (rw) for other volume types, regardless of the original mount options specified in TaskSpec.Volumes. If you need different mount settings, you can explicitly configure them in this field.

Type

MutableSequence[str]

options

Required for some container images. Arbitrary additional options to include in the docker run command when running this container—for example, --network host. For the --volume option, use the volumes field for the container.

Type

str

block_external_network

If set to true, external network access to and from container will be blocked, containers that are with block_external_network as true can still communicate with each other, network cannot be specified in the container.options field.

Type

bool

username

Required if the container image is from a private Docker registry. The username to login to the Docker registry that contains the image.

You can either specify the username directly by using plain text or specify an encrypted username by using a Secret Manager secret: projects/*/secrets/*/versions/*. However, using a secret is recommended for enhanced security.

Caution: If you specify the username using plain text, you risk the username being exposed to any users who can view the job or its logs. To avoid this risk, specify a secret that contains the username instead.

Learn more about Secret Manager and using Secret Manager with Batch.

Type

str

password

Required if the container image is from a private Docker registry. The password to login to the Docker registry that contains the image.

For security, it is strongly recommended to specify an encrypted password by using a Secret Manager secret: projects/*/secrets/*/versions/*.

Warning: If you specify the password using plain text, you risk the password being exposed to any users who can view the job or its logs. To avoid this risk, specify a secret that contains the password instead.

Learn more about Secret Manager and using Secret Manager with Batch.

Type

str

enable_image_streaming

Optional. If set to true, this container runnable uses Image streaming.

Use Image streaming to allow the runnable to initialize without waiting for the entire container image to download, which can significantly reduce startup time for large container images.

When enableImageStreaming is set to true, the container runtime is containerd instead of Docker. Additionally, this container runnable only supports the following container subfields: imageUri, commands[], entrypoint, and volumes[]; any other container subfields are ignored.

For more information about the requirements and limitations for using Image streaming with Batch, see the `image-streaming sample on GitHub <https://github.com/GoogleCloudPlatform/batch-samples/tree/main/api-samples/image-streaming>`__.

Type

bool

class LabelsEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

class Script(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Script runnable.

This message has oneof fields (mutually exclusive fields). For each oneof, at most one member field can be set at the same time. Setting any member of the oneof automatically clears all other members.

path

The path to a script file that is accessible from the host VM(s).

Unless the script file supports the default #!/bin/sh shell interpreter, you must specify an interpreter by including a [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix) as the first line of the file. For example, to execute the script using bash, include #!/bin/bash as the first line of the file. Alternatively, to execute the script using Python3, include #!/usr/bin/env python3 as the first line of the file.

This field is a member of oneof command.

Type

str

text

The text for a script.

Unless the script text supports the default #!/bin/sh shell interpreter, you must specify an interpreter by including a [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix) at the beginning of the text. For example, to execute the script using bash, include #!/bin/bash\n at the beginning of the text. Alternatively, to execute the script using Python3, include #!/usr/bin/env python3\n at the beginning of the text.

This field is a member of oneof command.

Type

str

class google.cloud.batch_v1.types.ServiceAccount(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Carries information about a Google Cloud service account.

email

Email address of the service account.

Type

str

scopes

List of scopes to be enabled for this service account.

Type

MutableSequence[str]

class google.cloud.batch_v1.types.StatusEvent(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Status event.

type_

Type of the event.

Type

str

description

Description of the event.

Type

str

event_time

The time this event occurred.

Type

google.protobuf.timestamp_pb2.Timestamp

task_execution

Task Execution. This field is only defined for task-level status events where the task fails.

Type

google.cloud.batch_v1.types.TaskExecution

task_state

Task State. This field is only defined for task-level status events.

Type

google.cloud.batch_v1.types.TaskStatus.State

class google.cloud.batch_v1.types.Task(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

A Cloud Batch task.

name

Task name. The name is generated from the parent TaskGroup name and ‘id’ field. For example:

“projects/123456/locations/us-west1/jobs/job01/taskGroups/group01/tasks/task01”.

Type

str

status

Task Status.

Type

google.cloud.batch_v1.types.TaskStatus

class google.cloud.batch_v1.types.TaskExecution(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

This Task Execution field includes detail information for task execution procedures, based on StatusEvent types.

exit_code

The exit code of a finished task.

If the task succeeded, the exit code will be 0. If the task failed but not due to the following reasons, the exit code will be 50000.

Otherwise, it can be from different sources:

Type

int

class google.cloud.batch_v1.types.TaskGroup(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

A TaskGroup defines one or more Tasks that all share the same TaskSpec.

name

Output only. TaskGroup name. The system generates this field based on parent Job name. For example:

“projects/123456/locations/us-west1/jobs/job01/taskGroups/group01”.

Type

str

task_spec

Required. Tasks in the group share the same task spec.

Type

google.cloud.batch_v1.types.TaskSpec

task_count

Number of Tasks in the TaskGroup. Default is 1.

Type

int

parallelism

Max number of tasks that can run in parallel. Default to min(task_count, parallel tasks per job limit). See: Job Limits. Field parallelism must be 1 if the scheduling_policy is IN_ORDER.

Type

int

scheduling_policy

Scheduling policy for Tasks in the TaskGroup. The default value is AS_SOON_AS_POSSIBLE.

Type

google.cloud.batch_v1.types.TaskGroup.SchedulingPolicy

task_environments

An array of environment variable mappings, which are passed to Tasks with matching indices. If task_environments is used then task_count should not be specified in the request (and will be ignored). Task count will be the length of task_environments.

Tasks get a BATCH_TASK_INDEX and BATCH_TASK_COUNT environment variable, in addition to any environment variables set in task_environments, specifying the number of Tasks in the Task’s parent TaskGroup, and the specific Task’s index in the TaskGroup (0 through BATCH_TASK_COUNT - 1).

Type

MutableSequence[google.cloud.batch_v1.types.Environment]

task_count_per_node

Max number of tasks that can be run on a VM at the same time. If not specified, the system will decide a value based on available compute resources on a VM and task requirements.

Type

int

require_hosts_file

When true, Batch will populate a file with a list of all VMs assigned to the TaskGroup and set the BATCH_HOSTS_FILE environment variable to the path of that file. Defaults to false. The host file supports up to 1000 VMs.

Type

bool

permissive_ssh

When true, Batch will configure SSH to allow passwordless login between VMs running the Batch tasks in the same TaskGroup.

Type

bool

run_as_non_root

Optional. If not set or set to false, Batch uses the root user to execute runnables. If set to true, Batch runs the runnables using a non-root user. Currently, the non-root user Batch used is generated by OS Login. For more information, see About OS Login.

Type

bool

class SchedulingPolicy(value)[source]

Bases: proto.enums.Enum

How Tasks in the TaskGroup should be scheduled relative to each other.

Values:
SCHEDULING_POLICY_UNSPECIFIED (0):

Unspecified.

AS_SOON_AS_POSSIBLE (1):

Run Tasks as soon as resources are available.

Tasks might be executed in parallel depending on parallelism and task_count values.

IN_ORDER (2):

Run Tasks sequentially with increased task index.

class google.cloud.batch_v1.types.TaskSpec(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Spec of a task

runnables

Required. The sequence of one or more runnables (executable scripts, executable containers, and/or barriers) for each task in this task group to run. Each task runs this list of runnables in order. For a task to succeed, all of its script and container runnables each must meet at least one of the following conditions:

  • The runnable exited with a zero status.

  • The runnable didn’t finish, but you enabled its background subfield.

  • The runnable exited with a non-zero status, but you enabled its ignore_exit_status subfield.

Type

MutableSequence[google.cloud.batch_v1.types.Runnable]

compute_resource

ComputeResource requirements.

Type

google.cloud.batch_v1.types.ComputeResource

max_run_duration

Maximum duration the task should run before being automatically retried (if enabled) or automatically failed. Format the value of this field as a time limit in seconds followed by s—for example, 3600s for 1 hour. The field accepts any value between 0 and the maximum listed for the Duration field type at https://protobuf.dev/reference/protobuf/google.protobuf/#duration; however, the actual maximum run time for a job will be limited to the maximum run time for a job listed at https://cloud.google.com/batch/quotas#max-job-duration.

Type

google.protobuf.duration_pb2.Duration

max_retry_count

Maximum number of retries on failures. The default, 0, which means never retry. The valid value range is [0, 10].

Type

int

lifecycle_policies

Lifecycle management schema when any task in a task group is failed. Currently we only support one lifecycle policy. When the lifecycle policy condition is met, the action in the policy will execute. If task execution result does not meet with the defined lifecycle policy, we consider it as the default policy. Default policy means if the exit code is 0, exit task. If task ends with non-zero exit code, retry the task with max_retry_count.

Type

MutableSequence[google.cloud.batch_v1.types.LifecyclePolicy]

environments

Deprecated: please use environment(non-plural) instead.

Type

MutableMapping[str, str]

volumes

Volumes to mount before running Tasks using this TaskSpec.

Type

MutableSequence[google.cloud.batch_v1.types.Volume]

environment

Environment variables to set before running the Task.

Type

google.cloud.batch_v1.types.Environment

class EnvironmentsEntry(mapping=None, *, ignore_unknown_fields=False, **kwargs)

Bases: proto.message.Message

class google.cloud.batch_v1.types.TaskStatus(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Status of a task.

state

Task state.

Type

google.cloud.batch_v1.types.TaskStatus.State

status_events

Detailed info about why the state is reached.

Type

MutableSequence[google.cloud.batch_v1.types.StatusEvent]

class State(value)[source]

Bases: proto.enums.Enum

Task states.

Values:
STATE_UNSPECIFIED (0):

Unknown state.

PENDING (1):

The Task is created and waiting for resources.

ASSIGNED (2):

The Task is assigned to at least one VM.

RUNNING (3):

The Task is running.

FAILED (4):

The Task has failed.

SUCCEEDED (5):

The Task has succeeded.

UNEXECUTED (6):

The Task has not been executed when the Job finishes.

class google.cloud.batch_v1.types.Volume(mapping=None, *, ignore_unknown_fields=False, **kwargs)[source]

Bases: proto.message.Message

Volume describes a volume and parameters for it to be mounted to a VM.

This message has oneof fields (mutually exclusive fields). For each oneof, at most one member field can be set at the same time. Setting any member of the oneof automatically clears all other members.

nfs

A Network File System (NFS) volume. For example, a Filestore file share.

This field is a member of oneof source.

Type

google.cloud.batch_v1.types.NFS

gcs

A Google Cloud Storage (GCS) volume.

This field is a member of oneof source.

Type

google.cloud.batch_v1.types.GCS

device_name

Device name of an attached disk volume, which should align with a device_name specified by job.allocation_policy.instances[0].policy.disks[i].device_name or defined by the given instance template in job.allocation_policy.instances[0].instance_template.

This field is a member of oneof source.

Type

str

mount_path

The mount path for the volume, e.g. /mnt/disks/share.

Type

str

mount_options

Mount options vary based on the type of storage volume:

Type

MutableSequence[str]