google.cloud.gcp_colab_schedule module – Manages a Colab.Schedule resource

Note

This module is part of the google.cloud collection (version 1.15.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install google.cloud. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: google.cloud.gcp_colab_schedule.

Synopsis

  • ‘Colab Enterprise Notebook Execution Schedules.’

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 3.8

  • requests >= 2.18.4

  • google-auth >= 2.25.1

Parameters

Parameter

Comments

access_token

string

The access token used to authenticate.

allow_queueing

boolean

Whether new scheduled runs can be queued when max_concurrent_runs limit is reached.

If set to true, new runs will be queued instead of skipped.

Default to false.

Choices:

  • false

  • true

auth_kind

string / required

The type of credential used.

Choices:

  • "accesstoken"

  • "application"

  • "machineaccount"

  • "serviceaccount"

create_notebook_execution_job_request

dictionary

Request for google_colab_notebook_execution.

This property is immutable, to change it, you must delete and recreate the resource.

notebook_execution_job

dictionary / required

The NotebookExecutionJob to create.

create_time

string

Timestamp when this NotebookExecutionJob was created.

custom_environment_spec

dictionary

Compute configuration to use for an execution job.

machine_spec

dictionary

Specification of a single machine.

accelerator_count

integer

The number of accelerators to attach to the machine.

For accelerator optimized machine types (https://cloud.google.com/compute/docs/accelerator-optimized-machines), One may set the accelerator_count from 1 to N for machine with N GPUs.

If accelerator_count is less than or equal to N / 2, Vertex will co-schedule the replicas of the model into the same VM to save cost.

For example, if the machine type is a3-highgpu-8g, which has 8 H100 GPUs, one can set accelerator_count to 1 to 8.

If accelerator_count is 1, 2, 3, or 4, Vertex will co-schedule 8, 4, 2, or 2 replicas of the model into the same VM to save cost.

When co-scheduling, CPU, memory and storage on the VM will be distributed to replicas on the VM.

For example, one can expect a co-scheduled replica requesting 2 GPUs out of a 8-GPU VM will receive 25% of the CPU, memory and storage of the VM.

Note that the feature is not compatible with multihost_gpu_node_count.

When multihost_gpu_node_count is set, the co-scheduling will not be enabled.

accelerator_type

string

Possible values: NVIDIA_TESLA_K80 NVIDIA_TESLA_P100 NVIDIA_TESLA_V100 NVIDIA_TESLA_P4 NVIDIA_TESLA_T4 NVIDIA_TESLA_A100 NVIDIA_A100_80GB NVIDIA_L4 NVIDIA_H100_80GB NVIDIA_H100_MEGA_80GB NVIDIA_H200_141GB NVIDIA_B200 NVIDIA_GB200 NVIDIA_RTX_PRO_6000 TPU_V2 TPU_V3 TPU_V4_POD TPU_V5_LITEPOD.

gpu_partition_size

string

The Nvidia GPU partition size.

When specified, the requested accelerators will be partitioned into smaller GPU partitions.

For example, if the request is for 8 units of NVIDIA A100 GPUs, and gpu_partition_size=”1g.10gb”, the service will create 8 * 7 = 56 partitioned MIG instances.

The partition size must be a value supported by the requested accelerator.

Refer to [Nvidia GPU Partitioning](https://cloud.google.com/kubernetes-engine/docs/how-to/gpus-multi#multi-instance_gpu_partitions) for the available partition sizes.

If set, the accelerator_count should be set to 1.

This property is immutable, to change it, you must delete and recreate the resource.

machine_type

string

The type of the machine.

See the [list of machine types supported for prediction](https://cloud.google.com/vertex-ai/docs/predictions/configure-compute#machine-types) See the [list of machine types supported for custom training](https://cloud.google.com/vertex-ai/docs/training/configure-compute#machine-types).

For DeployedModel this field is optional, and the default value is `n1-standard-2`.

For BatchPredictionJob or as part of WorkerPoolSpec this field is required.

This property is immutable, to change it, you must delete and recreate the resource.

reservation_affinity

dictionary

A ReservationAffinity can be used to configure a Vertex AI resource (e.g., a DeployedModel) to draw its Compute Engine resources from a Shared Reservation, or exclusively from on-demand capacity.

key

string

Corresponds to the label key of a reservation resource.

To target a SPECIFIC_RESERVATION by name, use `compute.googleapis.com/reservation-name` as the key and specify the name of your reservation as its value.

reservation_affinity_type

string / required

Specifies the reservation affinity type.

Possible values: NO_RESERVATION ANY_RESERVATION SPECIFIC_RESERVATION SPECIFIC_THEN_ANY_RESERVATION SPECIFIC_THEN_NO_RESERVATION.

use_reservation_pool

boolean

When set to true, resources will be drawn from go/cloud-ai-gcp-pool.

Choices:

  • false

  • true

values

list / elements=string

Corresponds to the label values of a reservation resource.

This must be the full resource name of the reservation or reservation block.

tpu_topology

string

The topology of the TPUs.

Corresponds to the TPU topologies available from GKE.

(Example: tpu_topology: “2x2x1”).

This property is immutable, to change it, you must delete and recreate the resource.

network_spec

dictionary

Network spec.

enable_internet_access

boolean

Whether to enable public internet access.

Default false.

Choices:

  • false

  • true

network

string

The full name of the Google Compute Engine [network](https://cloud.google.com//compute/docs/networks-and-firewalls#networks).

subnetwork

string

The name of the subnet that this instance is in.

Format: `projects/{project_id_or_number}/regions/{region}/subnetworks/{subnetwork_id}`.

persistent_disk_spec

dictionary

Represents the spec of persistent disk options.

disk_size_gb

string

Size in GB of the disk (default is 100GB).

disk_type

string

Type of the disk (default is “pd-standard”).

Valid values: “pd-ssd” (Persistent Disk Solid State Drive) “pd-standard” (Persistent Disk Hard Disk Drive) “pd-balanced” (Balanced Persistent Disk) “pd-extreme” (Extreme Persistent Disk).

dataform_repository_source

dictionary

The Dataform Repository containing the input notebook.

commit_sha

string

The commit SHA to read repository with.

If unset, the file will be read at HEAD.

dataform_repository_resource_name

string / required

The resource name of the Dataform Repository.

Format: `projects/{project_id}/locations/{location}/repositories/{repository_id}`.

display_name

string / required

The display name of the Notebook Execution.

encryption_spec

dictionary

Represents a customer-managed encryption key specification that can be applied to a Vertex AI resource.

kms_key_name

string / required

Resource name of the Cloud KMS key used to protect the resource.

The Cloud KMS key must be in the same region as the resource.

It must have the format `projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}`.

execution_timeout

string

Max running time of the execution job in seconds (default 86400s / 24 hrs).

A duration in seconds with up to nine fractional digits, ending with “s”.

Example: “3.5s”.

execution_user

string

The user email to run the execution as.

gcs_notebook_source

dictionary

The Cloud Storage uri for the input notebook.

generation

string

The version of the Cloud Storage object to read.

If unset, the current version of the object is read.

See https://cloud.google.com/storage/docs/metadata#generation-number.

uri

string / required

The Cloud Storage uri pointing to the ipynb file.

Format: gs://bucket/notebook_file.ipynb.

gcs_output_uri

string / required

The Cloud Storage location to upload the result to.

Format:`gs://bucket-name`.

job_state

string

Possible values: JOB_STATE_QUEUED JOB_STATE_PENDING JOB_STATE_RUNNING JOB_STATE_SUCCEEDED JOB_STATE_FAILED JOB_STATE_CANCELLING JOB_STATE_CANCELLED JOB_STATE_PAUSED JOB_STATE_EXPIRED JOB_STATE_UPDATING JOB_STATE_PARTIALLY_SUCCEEDED.

kernel_name

string

The name of the kernel to use during notebook execution.

If unset, the default kernel is used.

labels

dictionary

The labels with user-defined metadata to organize NotebookExecutionJobs.

name

string

The resource name of this NotebookExecutionJob.

Format: `projects/{project_id}/locations/{location}/notebookExecutionJobs/{job_id}`.

notebook_runtime_template_resource_name

string

The NotebookRuntimeTemplate to source compute configuration from.

schedule_resource_name

string

The Schedule resource name if this job is triggered by one.

Format: `projects/{project_id}/locations/{location}/schedules/{schedule_id}`.

service_account

string

The service account to run the execution as.

update_time

string

Timestamp when this NotebookExecutionJob was most recently updated.

workbench_runtime

dictionary

Configuration for a Workbench Instances-based environment.

notebook_execution_job_id

string

User specified ID for the NotebookExecutionJob.

parent

string

The resource name of the Location to create the NotebookExecutionJob.

Format: `projects/{project}/locations/{location}`.

create_pipeline_job_request

dictionary

Request message for PipelineService.CreatePipelineJob.

parent

string

The resource name of the Location to create the PipelineJob in.

Format: `projects/{project}/locations/{location}`.

pipeline_job

dictionary / required

An instance of a machine learning PipelineJob.

create_time

string

Pipeline creation time.

display_name

string

The display name of the Pipeline.

The name can be up to 128 characters long and can consist of any UTF-8 characters.

encryption_spec

dictionary

Represents a customer-managed encryption key specification that can be applied to a Vertex AI resource.

kms_key_name

string / required

Resource name of the Cloud KMS key used to protect the resource.

The Cloud KMS key must be in the same region as the resource.

It must have the format `projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}`.

end_time

string

Pipeline end time.

labels

dictionary

The labels with user-defined metadata to organize PipelineJob.

Label keys and values can be no longer than 64 characters (Unicode codepoints), can only contain lowercase letters, numeric characters, underscores and dashes.

International characters are allowed.

See https://goo.gl/xmQnxf for more information and examples of labels.

Note there is some reserved label key for Vertex AI Pipelines.

- `vertex-ai-pipelines-run-billing-id`, user set value will get overrided.

name

string

The resource name of the PipelineJob.

network

string

The full name of the Compute Engine [network](/compute/docs/networks-and-firewalls#networks) to which the Pipeline Job’s workload should be peered.

For example, `projects/12345/global/networks/myVPC`.

[Format](/compute/docs/reference/rest/v1/networks/insert) is of the form `projects/{project}/global/networks/{network}`.

Where {project} is a project number, as in `12345`, and {network} is a network name.

Private services access must already be configured for the network.

Pipeline job will apply the network configuration to the Google Cloud resources being launched, if applied, such as Vertex AI Training or Dataflow job.

If left unspecified, the workload is not peered with any network.

pipeline_spec

string

A compiled definition of a pipeline, represented as a `JSON` object.

Defines the structure of the pipeline, including its components, tasks, and parameters.

This specification is generated by compiling a pipeline function defined in `Python` using the `Kubeflow Pipelines SDK`.

preflight_validations

boolean

Whether to do component level validations before job creation.

Choices:

  • false

  • true

psc_interface_config

dictionary

Configuration for PSC-I.

dns_peering_configs

list / elements=dictionary

DNS peering configurations.

When specified, Vertex AI will attempt to configure DNS peering zones in the tenant project VPC to resolve the specified domains using the target network’s Cloud DNS.

The user must grant the dns.peer role to the Vertex AI Service Agent on the target project.

domain

string / required

The DNS name suffix of the zone being peered to, e.g., “my-internal-domain.corp.”.

Must end with a dot.

target_network

string / required

The VPC network name in the target_project where the DNS zone specified by ‘domain’ is visible.

target_project

string / required

The project ID hosting the Cloud DNS managed zone that contains the ‘domain’.

The Vertex AI Service Agent requires the dns.peer role on this project.

network_attachment

string

The name of the Compute Engine [network attachment](https://cloud.google.com/vpc/docs/about-network-attachments) to attach to the resource within the region and user project.

To specify this field, you must have already [created a network attachment] (https://cloud.google.com/vpc/docs/create-manage-network-attachments#create-network-attachments).

This field is only used for resources using PSC-I.

reserved_ip_ranges

list / elements=string

A list of names for the reserved ip ranges under the VPC network that can be used for this Pipeline Job’s workload.

If set, we will deploy the Pipeline Job’s workload within the provided ip ranges.

Otherwise, the job will be deployed to any ip ranges under the provided VPC network.

Example: [‘vertex-ai-ip-range’].

runtime_config

dictionary

The runtime config of a PipelineJob.

failure_policy

string

Possible values: PIPELINE_FAILURE_POLICY_FAIL_SLOW PIPELINE_FAILURE_POLICY_FAIL_FAST.

gcs_output_directory

string / required

A path in a Cloud Storage bucket, which will be treated as the root output directory of the pipeline.

It is used by the system to generate the paths of output artifacts.

The artifact paths are generated with a sub-path pattern `{job_id}/{task_id}/{output_key}` under the specified output directory.

The service account specified in this pipeline must have the `storage.objects.get` and `storage.objects.create` permissions for this bucket.

parameter_values

dictionary

The runtime parameters of the PipelineJob.

The parameters will be passed into PipelineJob.pipeline_spec to replace the placeholders at runtime.

This field is used by pipelines built using `PipelineJob.pipeline_spec.schema_version` 2.1.0, such as pipelines built using Kubeflow Pipelines SDK 1.9 or higher and the v2 DSL.

schedule_name

string

The schedule resource name.

Only returned if the Pipeline is created by Schedule API.

service_account

string

The service account that the pipeline workload runs as.

If not specified, the Compute Engine default service account in the project will be used.

See https://cloud.google.com/compute/docs/access/service-accounts#default_service_account Users starting the pipeline must have the `iam.serviceAccounts.actAs` permission on this service account.

start_time

string

Pipeline start time.

state

string

Possible values: PIPELINE_STATE_QUEUED PIPELINE_STATE_PENDING PIPELINE_STATE_RUNNING PIPELINE_STATE_SUCCEEDED PIPELINE_STATE_FAILED PIPELINE_STATE_CANCELLING PIPELINE_STATE_CANCELLED PIPELINE_STATE_PAUSED.

template_metadata

dictionary

Pipeline template metadata if PipelineJob.template_uri is from supported template registry.

Currently, the only supported registry is Artifact Registry.

version

string

The version_name in artifact registry.

Will always be presented in output if the PipelineJob.template_uri is from supported template registry.

Format is “sha256:abcdef123456…”.

template_uri

string

A template uri from where the PipelineJob.pipeline_spec, if empty, will be downloaded.

Currently, only uri from Vertex Template Registry & Gallery is supported.

Reference to https://cloud.google.com/vertex-ai/docs/pipelines/create-pipeline-template.

update_time

string

Timestamp when this PipelineJob was most recently updated.

pipeline_job_id

string

The ID to use for the PipelineJob, which will become the final component of the PipelineJob name.

If not provided, an ID will be automatically generated.

This value should be less than 128 characters, and valid characters are `/a-z-/`.

cron

string / required

Cron schedule (https://en.wikipedia.org/wiki/Cron) to launch scheduled runs.

desired_state

string

Desired state of the Colab Schedule.

Set this field to `ACTIVE` to start/resume the schedule, and `PAUSED` to pause the schedule.

Choices:

  • "ACTIVE" ← (default)

  • "PAUSED"

display_name

string / required

The display name of the Schedule.

end_time

string

Timestamp after which no new runs can be scheduled.

If specified, the schedule will be completed when either end_time is reached or when scheduled_run_count >= max_run_count.

Must be in the RFC 3339 (https://www.ietf.org/rfc/rfc3339.txt) format.

env_type

string

Specifies which Ansible environment you’re running this module within.

This should not be set unless you know what you’re doing.

This only alters the User Agent string for any API requests.

location

string / required

The location for the resource: https://cloud.google.com/colab/docs/locations.

max_concurrent_active_run_count

string

Specifies the maximum number of active runs that can be executed concurrently for this Schedule.

This limits the number of runs that can be in a non-terminal state at the same time.

Currently, this field is only supported for requests of type CreatePipelineJobRequest.

max_concurrent_run_count

string / required

Maximum number of runs that can be started concurrently for this Schedule.

This is the limit for starting the scheduled requests and not the execution of the notebook execution jobs created by the requests.

max_run_count

string

Maximum run count of the schedule.

If specified, The schedule will be completed when either startedRunCount >= maxRunCount or when endTime is reached.

If not specified, new runs will keep getting scheduled until this Schedule is paused or deleted.

Already scheduled runs will be allowed to complete.

Unset if not specified.

project

string

The Google Cloud Platform project to use.

scopes

list / elements=string

Array of scopes to be used.

service_account_contents

jsonarg

The contents of a Service Account JSON file,

either in a dictionary or as a JSON string that represents it.

service_account_email

string

An optional service account email address if machineaccount is

selected and the user does not wish to use the default email.

service_account_file

path

The path of a Service Account JSON file if serviceaccount

is selected as type.

start_time

string

The timestamp after which the first run can be scheduled.

Defaults to the schedule creation time.

Must be in the RFC 3339 (https://www.ietf.org/rfc/rfc3339.txt) format.

state

string

Whether the resource should exist.

Choices:

  • "present" ← (default)

  • "absent"

Notes

Note

Examples

- name: Create Basic Schedule
  google.cloud.gcp_colab_schedule:
    display_name: my-schedule
    state: present
    location: us-central1
    max_concurrent_run_count: 2
    cron: "TZ=America/Los_Angeles * * * * *"
    create_notebook_execution_job_request:
      notebook_execution_job:
        display_name: my-notebook-execution
        gcs_notebook_source:
          uri: gs://my-bucket/input/my-notebook.json
        notebook_runtime_template_resource_name: projects/my-project/locations/us-central1/notebookRuntimeTemplates/my-runtime-template
        gcs_output_uri: gs://my-bucket/output/

################################################################################

- name: Create Paused Schedule
  google.cloud.gcp_colab_schedule:
    display_name: my-schedule
    state: present
    location: us-central1
    desired_state: PAUSED
    max_concurrent_run_count: 2
    cron: "TZ=America/Los_Angeles * * * * *"
    create_notebook_execution_job_request:
      notebook_execution_job:
        display_name: my-notebook-execution
        gcs_notebook_source:
          uri: gs://my-bucket/input/my-notebook.json
        notebook_runtime_template_resource_name: projects/my-project/locations/us-central1/notebookRuntimeTemplates/my-runtime-template
        gcs_output_uri: gs://my-bucket/output/

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

catchUp

boolean

Whether to backfill missed runs when the schedule is resumed from PAUSED state.

If set to true, all missed runs will be scheduled.

New runs will be scheduled after the backfill is complete.

Default to false.

Returned: success

changed

boolean

Whether the resource was changed.

Returned: always

createTime

string

Timestamp when this Schedule was created.

Returned: success

lastPauseTime

string

Timestamp when this Schedule was last paused.

Unset if never paused.

Returned: success

lastResumeTime

string

Timestamp when this Schedule was last resumed.

Unset if never resumed from pause.

Returned: success

lastScheduledRunResponse

dictionary

Status of a scheduled run.

Returned: success

runResponse

string

The response of the scheduled run.

Returned: success

scheduledRunTime

string

The scheduled run time based on the user-specified schedule.

Returned: success

name

string

The resource name of the Schedule.

Returned: success

nextRunTime

string

Timestamp when this Schedule should schedule the next run.

Having a next_run_time in the past means the runs are being started behind schedule.

Returned: success

startedRunCount

string

The number of runs started by this schedule.

Returned: success

state

string

Output only.

The state of the schedule.

Returned: success

updateTime

string

Timestamp when this Schedule was updated.

Returned: success

Authors

  • Google Inc. (@googlecloudplatform)