Schedule a notebook run

This page shows you how to schedule a notebook run in Colab Enterprise.

Overview

You can schedule a notebook to run immediately one time, or on a recurring schedule.

When you schedule the notebook run, you select a runtime template. Colab Enterprise uses this runtime template to create the runtime that runs your notebook.

The runtime needs specific permissions to run the notebook's code and access Google Cloud services and APIs.

If your runtime template configuration has end-user credentials enabled, then the runtime uses the permissions associated with your user credentials.
If end-user credentials aren't enabled, you must specify a service account when you schedule the notebook run. Colab Enterprise uses this service account's credentials to run your notebook.

For more information, see Required roles for running the notebook .

After Colab Enterprise completes the notebook run, the results are stored in a shareable Cloud Storage bucket.

Limitations

Colab Enterprise runtimes use Compute Engine quota. See the Compute Engine Allocation quotas page .

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project .

Enable the Vertex AI, Dataform, and Compute Engine APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project .

Enable the Vertex AI, Dataform, and Compute Engine APIs.

Enable the APIs

Required roles for scheduling the notebook run

To get the permissions that you need to schedule a notebook run in Colab Enterprise, ask your administrator to grant you the following IAM roles on the project:

Colab Enterprise User ( roles/aiplatform.colabEnterpriseUser )
Storage Admin ( roles/storage.admin )

For more information about granting roles, see Manage access to projects, folders, and organizations .

You might also be able to get the required permissions through custom roles or other predefined roles .

One or more of the required roles includes the dataform.repositories.list permission. Users who are granted the dataform.repositories.list permission or the Code Creator ( roles/dataform.codeCreator ) role in a project can list the names of code assets in that project by using the Dataform API or the Dataform command-line interface (CLI). Non-administrators using BigQuery Studio can only see code assets that they created or that were shared with them.

Required roles for running the notebook

The principal that runs the notebook needs specific permissions. The principal is either your user account or a service account that you specify, as described in the overview .

To get the permissions that you need to run a notebook in Colab Enterprise, ask your administrator to grant you the following IAM roles:

Code Viewer ( roles/dataform.codeViewer ) on the notebook
Logs Writer ( roles/logging.logWriter ) on the project
Monitoring Metric Writer ( roles/monitoring.metricWriter ) on the project
Storage Legacy Bucket Writer ( roles/storage.legacyBucketWriter ) on the notebook
Storage Legacy Object Reader ( roles/storage.legacyObjectReader ) on the output bucket

For more information about granting roles, see Manage access to projects, folders, and organizations .

These predefined roles contain the permissions required to run a notebook in Colab Enterprise. To see the exact permissions that are required, expand the Required permissionssection:

Required permissions

The following permissions are required to run a notebook in Colab Enterprise:

dataform.locations.list on the notebook
dataform.repositories.computeAccessTokenStatus on the notebook
dataform.repositories.fetchHistory on the notebook
dataform.repositories.fetchRemoteBranches on the notebook
dataform.repositories.get on the notebook
dataform.repositories.getIamPolicy on the notebook
dataform.repositories.list on the notebook
dataform.repositories.queryDirectoryContents on the notebook
dataform.repositories.readFile on the notebook
logging.logEntries.create on the project
logging.logEntries.route on the project
monitoring.metricDescriptors.create on the project
monitoring.metricDescriptors.get on the project
monitoring.metricDescriptors.list on the project
monitoring.monitoredResourceDescriptors.get on the project
monitoring.monitoredResourceDescriptors.list on the project
monitoring.timeSeries.create on the project
resourcemanager.projects.get on the project
resourcemanager.projects.list on the project
storage.buckets.get on the notebook
storage.managedFolders.create on the notebook
storage.managedFolders.delete on the notebook
storage.managedFolders.get on the notebook
storage.managedFolders.list on the notebook
storage.multipartUploads.abort on the notebook
storage.multipartUploads.create on the notebook
storage.multipartUploads.list on the notebook
storage.multipartUploads.listParts on the notebook
storage.objects.create on the notebook
storage.objects.delete on the notebook
storage.objects.get on the notebook
storage.objects.list on the notebook
storage.objects.restore on the notebook
storage.objects.setRetention on the notebook

You might also be able to get these permissions with custom roles or other predefined roles .

Run a notebook once

To run a notebook one time, you can use the Google Cloud console, the Google Cloud CLI, the Vertex AI Python client library, or Terraform.

Console

In the Google Cloud console, go to the Colab Enterprise My notebookspage.

Go to My notebooks
In the Regionmenu, select the region that contains your notebook.
Next to a notebook, click the Notebook actions menu and select Schedule .
In the Schedule namefield, enter a name for your schedule.
Click the Runtime templatelist, and select a runtime template. The runtime template determines the specifications of the runtime that runs your notebook.
Under Run schedule, select One-offto run your notebook as soon as you submit the notebook run.
Next to the Cloud Storage output locationfield, click Browseto open the Select folderdialog.
Select a Cloud Storage bucket. Or, to create a bucket, click Create new bucketand complete the dialog.
If you selected a runtime template without end-user credentials enabled, the dialog includes a Service accountfield. In the Service accountfield, enter a service account's email address.
Click Submit.

The notebook run starts immediately.

gcloud

Before using any of the command data below, make the following replacements:

DISPLAY_NAME : the display name for your notebook run.
NOTEBOOK_RUNTIME_TEMPLATE : the notebook runtime template that specifies your runtime's compute configuration.
NOTEBOOK_URI : the Cloud Storage URI of the notebook to run.
OUTPUT_URI : the Cloud Storage location where you want to store results.
USER_EMAIL : the user account email address that specifies the notebook run's access to Google Cloud resources.
PROJECT_ID : your project ID.
REGION : the region where your notebook will run.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud  
colab  
executions  
create  
--display-name = 
 " DISPLAY_NAME 
" 
  
 \ 
  
--notebook-runtime-template = 
 NOTEBOOK_RUNTIME_TEMPLATE 
  
 \ 
  
--gcs-notebook-uri = 
 NOTEBOOK_URI 
  
 \ 
  
--gcs-output-uri = 
 OUTPUT_URI 
  
 \ 
  
--user-email = 
 USER_EMAIL 
  
 \ 
  
--project = 
 PROJECT_ID 
  
 \ 
  
--region = 
 REGION

Windows (PowerShell)

gcloud  
colab  
executions  
create  
--display-name = 
 " DISPLAY_NAME 
" 
  
 ` 
  
--notebook-runtime-template = 
 NOTEBOOK_RUNTIME_TEMPLATE 
  
 ` 
  
--gcs-notebook-uri = 
 NOTEBOOK_URI 
  
 ` 
  
--gcs-output-uri = 
 OUTPUT_URI 
  
 ` 
  
--user-email = 
 USER_EMAIL 
  
 ` 
  
--project = 
 PROJECT_ID 
  
 ` 
  
--region = 
 REGION

Windows (cmd.exe)

gcloud  
colab  
executions  
create  
--display-name = 
 " DISPLAY_NAME 
" 
  
^  
--notebook-runtime-template = 
 NOTEBOOK_RUNTIME_TEMPLATE 
  
^  
--gcs-notebook-uri = 
 NOTEBOOK_URI 
  
^  
--gcs-output-uri = 
 OUTPUT_URI 
  
^  
--user-email = 
 USER_EMAIL 
  
^  
--project = 
 PROJECT_ID 
  
^  
--region = 
 REGION

For more information about managing Colab Enterprise notebook runs from the command line, see the gcloud CLI documentation .

Python

Before trying this sample, install the Vertex AI SDK for Python . The Vertex AI Python client library is installed when you install the Vertex AI SDK for Python. For more information, see the Vertex AI SDK for Python API reference documentation .

To run the following code sample, you'll need the Dataform repository ID of your notebook. To get the repository ID of your notebook, you can use Dataform's list_repositories method.

 from 
  
 google.cloud 
  
 import 
 aiplatform_v1 
 PROJECT_ID 
 = 
 "my-project" 
 LOCATION 
 = 
 "us-central1" 
 REPOSITORY_ID 
 = 
 "b223577f-a3fb-482c-a22c-0658c6602598" 
 TEMPLATE_ID 
 = 
 "6524523989455339520" 
 API_ENDPOINT 
 = 
 f 
 " 
 { 
 LOCATION 
 } 
 -aiplatform.googleapis.com" 
 PARENT 
 = 
 f 
 "projects/ 
 { 
 PROJECT_ID 
 } 
 /locations/ 
 { 
 LOCATION 
 } 
 " 
 notebook_service_client 
 = 
 aiplatform_v1 
 . 
  NotebookServiceClient 
 
 ( 
 client_options 
 = 
 { 
 "api_endpoint" 
 : 
 API_ENDPOINT 
 , 
 }) 
 operation 
 = 
 notebook_service_client 
 . 
  create_notebook_execution_job 
 
 ( 
 parent 
 = 
 PARENT 
 , 
 notebook_execution_job 
 = 
 { 
 "display_name" 
 : 
 "my-execution-job" 
 , 
 # Specify a NotebookRuntimeTemplate to source compute configuration from 
 "notebook_runtime_template_resource_name" 
 : 
 f 
 "projects/ 
 { 
 PROJECT_ID 
 } 
 /locations/ 
 { 
 LOCATION 
 } 
 /notebookRuntimeTemplates/ 
 { 
 TEMPLATE_ID 
 } 
 " 
 , 
 # Specify a Colab Enterprise notebook to run 
 "dataform_repository_source" 
 : 
 { 
 "dataform_repository_resource_name" 
 : 
 f 
 "projects/ 
 { 
 PROJECT_ID 
 } 
 /locations/ 
 { 
 LOCATION 
 } 
 /repositories/ 
 { 
 REPOSITORY_ID 
 } 
 " 
 , 
 }, 
 # Specify a Cloud Storage bucket to store output artifacts 
 "gcs_output_uri" 
 : 
 "gs://my-bucket/" 
 , 
 # Specify the identity that runs the notebook 
 "execution_user" 
 : 
 " 
 {EMAIL} 
 " 
 , 
 # Run as the service account instead 
 # "service_account": "my-service-account", 
 }) 
 print 
 ( 
 "Waiting for operation to complete..." 
 ) 
 result 
 = 
 operation 
 . 
 result 
 ()

Terraform

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands . For more information, see the Terraform provider reference documentation .

The following sample uses the google_colab_notebook_execution Terraform resource to run a Colab Enterprise notebook.

  resource 
  
 "google_colab_runtime_template" 
  
 "my_runtime_template" 
  
 { 
  
 provider 
  
 = 
  
 google-beta 
  
 name 
  
 = 
  
 "{{index $.Vars "runtime_template_name"}}" 
  
 display_name 
  
 = 
  
 "Runtime template" 
  
 location 
  
 = 
  
 "us-central1" 
  
 machine_spec 
  
 { 
  
 machine_type 
  
 = 
  
 "e2-standard-4" 
  
 } 
  
 network_spec 
  
 { 
  
 enable_internet_access 
  
 = 
  
 true 
  
 } 
 } 
 resource 
  
 "google_storage_bucket" 
  
 "output_bucket" 
  
 { 
  
 provider 
  
 = 
  
 google-beta 
  
 name 
  
 = 
  
 "{{index $.Vars "bucket"}}" 
  
 location 
  
 = 
  
 "US" 
  
 force_destroy 
  
 = 
  
 true 
  
 uniform_bucket_level_access 
  
 = 
  
 true 
 } 
 resource 
  
 "google_storage_bucket_object" 
  
 "notebook" 
  
 { 
  
 provider 
  
 = 
  
 google-beta 
  
 name 
  
 = 
  
 "hello_world.ipynb" 
  
 bucket 
  
 = 
  
 google_storage_bucket.output_bucket.name 
  
 content 
  
 = 
  
<< EOF 
  
 { 
  
 "cells" 
 : 
  
 [ 
  
 { 
  
 "cell_type" 
 : 
  
 "code" 
 , 
  
 "execution_count" 
 : 
  
 null 
 , 
  
 "metadata" 
 : 
  
 {}, 
  
 "outputs" 
 : 
  
 [], 
  
 "source" 
 : 
  
 [ 
  
 "print(\"Hello, World!\")" 
  
 ] 
  
 } 
  
 ], 
  
 "metadata" 
 : 
  
 { 
  
 "kernelspec" 
 : 
  
 { 
  
 "display_name" 
 : 
  
 "Python 3" 
 , 
  
 "language" 
 : 
  
 "python" 
 , 
  
 "name" 
 : 
  
 "python3" 
  
 }, 
  
 "language_info" 
 : 
  
 { 
  
 "codemirror_mode" 
 : 
  
 { 
  
 "name" 
 : 
  
 "ipython" 
 , 
  
 "version" 
 : 
  
 3 
  
 }, 
  
 "file_extension" 
 : 
  
 ".py" 
 , 
  
 "mimetype" 
 : 
  
 "text/x-python" 
 , 
  
 "name" 
 : 
  
 "python" 
 , 
  
 "nbconvert_exporter" 
 : 
  
 "python" 
 , 
  
 "pygments_lexer" 
 : 
  
 "ipython3" 
 , 
  
 "version" 
 : 
  
 "3.8.5" 
  
 } 
  
 }, 
  
 "nbformat" 
 : 
  
 4 
 , 
  
 "nbformat_minor" 
 : 
  
 4 
  
 } 
  
 EOF 
 } 
 resource 
  
 "google_colab_notebook_execution" "{{$.PrimaryResourceId}}" 
  
 { 
  
 provider 
  
 = 
  
 google-beta 
  
 notebook_execution_job_id 
  
 = 
  
 "{{index $.Vars "notebook_execution_job_id"}}" 
  
 display_name 
  
 = 
  
 "Notebook execution full" 
  
 location 
  
 = 
  
 "us-central1" 
  
 execution_timeout 
  
 = 
  
 "86400s" 
  
 gcs_notebook_source 
  
 { 
  
 uri 
  
 = 
  
 "gs://${google_storage_bucket_object.notebook.bucket}/${google_storage_bucket_object.notebook.name}" 
  
 generation 
  
 = 
  
 google_storage_bucket_object.notebook.generation 
  
 } 
  
 service_account 
  
 = 
  
 "{{index $.TestEnvVars "service_account"}}" 
  
 gcs_output_uri 
  
 = 
  
 "gs://${google_storage_bucket.output_bucket.name}" 
  
 notebook_runtime_template_resource_name 
  
 = 
  
 "projects/${google_colab_runtime_template.my_runtime_template.project}/locations/${google_colab_runtime_template.my_runtime_template.location}/notebookRuntimeTemplates/${google_colab_runtime_template.my_runtime_template.name}" 
  
 depends_on 
  
 = 
  
 [ 
  
 google_storage_bucket_object.notebook 
 , 
  
 google_storage_bucket.output_bucket 
 , 
  
 google_colab_runtime_template.my_runtime_template 
 , 
  
 ] 
 }

You can view results from completed notebook runs on the Executionspage .

Schedule a notebook run

To schedule a notebook run, you can use the Google Cloud console, the gcloud CLI, the Vertex AI Python client library, or Terraform.

Console

In the Google Cloud console, go to the Colab Enterprise My notebookspage.

Go to My notebooks
In the Regionmenu, select the region that contains your notebook.
Next to a notebook, click the Notebook actions menu and select Schedule .
In the Schedule namefield, enter a name for your schedule.
Click the Runtime templatelist, and select a runtime template. The runtime template determines the specifications of the runtime that runs your notebook.
Under Run schedule, select Recurringto schedule the notebook run for a specific interval of time.
Complete the scheduling dialog.
Next to the Cloud Storage output locationfield, click Browseto open the Select folderdialog.
Select a Cloud Storage bucket. Or, to create a bucket, click Create new bucketand complete the dialog.
If you selected a runtime template without end-user credentials enabled, the dialog includes a Service accountfield. In the Service accountfield, enter a service account's email address.
Click Submit.

Scheduled notebook runs start automatically on the schedule that you set.

gcloud

Before using any of the command data below, make the following replacements:

DISPLAY_NAME : the display name of your schedule.
CRON_SCHEDULE : the schedule that you set, in unix-cron format . For example, 00 19 * * MON means weekly on Monday, at 1900 hours Greenwich Mean Time (GMT).
NOTEBOOK_RUN_NAME : the display name for notebook runs generated by this schedule.
NOTEBOOK_RUNTIME_TEMPLATE : the notebook runtime template that specifies your runtime's compute configuration.
NOTEBOOK_URI : the Cloud Storage URI of the notebook to run.
OUTPUT_URI : the Cloud Storage location where you want to store results.
USER_EMAIL : the user account email address that specifies the notebook run's access to Google Cloud resources.
PROJECT_ID : your project ID.
REGION : the region where your schedule will run.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud  
colab  
schedules  
create  
--display-name = 
 " DISPLAY_NAME 
" 
  
 \ 
  
--cron-schedule = 
 CRON_SCHEDULE 
  
 \ 
  
--execution-display-name = 
 NOTEBOOK_RUN_NAME 
  
 \ 
  
--notebook-runtime-template = 
 NOTEBOOK_RUNTIME_TEMPLATE 
  
 \ 
  
--gcs-notebook-uri = 
 NOTEBOOK_URI 
  
 \ 
  
--gcs-output-uri = 
 OUTPUT_URI 
  
 \ 
  
--user-email = 
 USER_EMAIL 
  
 \ 
  
--project = 
 PROJECT_ID 
  
 \ 
  
--region = 
 REGION

Windows (PowerShell)

gcloud  
colab  
schedules  
create  
--display-name = 
 " DISPLAY_NAME 
" 
  
 ` 
  
--cron-schedule = 
 CRON_SCHEDULE 
  
 ` 
  
--execution-display-name = 
 NOTEBOOK_RUN_NAME 
  
 ` 
  
--notebook-runtime-template = 
 NOTEBOOK_RUNTIME_TEMPLATE 
  
 ` 
  
--gcs-notebook-uri = 
 NOTEBOOK_URI 
  
 ` 
  
--gcs-output-uri = 
 OUTPUT_URI 
  
 ` 
  
--user-email = 
 USER_EMAIL 
  
 ` 
  
--project = 
 PROJECT_ID 
  
 ` 
  
--region = 
 REGION

Windows (cmd.exe)

gcloud  
colab  
schedules  
create  
--display-name = 
 " DISPLAY_NAME 
" 
  
^  
--cron-schedule = 
 CRON_SCHEDULE 
  
^  
--execution-display-name = 
 NOTEBOOK_RUN_NAME 
  
^  
--notebook-runtime-template = 
 NOTEBOOK_RUNTIME_TEMPLATE 
  
^  
--gcs-notebook-uri = 
 NOTEBOOK_URI 
  
^  
--gcs-output-uri = 
 OUTPUT_URI 
  
^  
--user-email = 
 USER_EMAIL 
  
^  
--project = 
 PROJECT_ID 
  
^  
--region = 
 REGION

For more information about creating Colab Enterprise notebook schedules from the command line, see the gcloud CLI documentation .

Python

To run the following code sample, you'll need the Dataform repository ID of your notebook. To get the repository ID of your notebook, you can use Dataform's list_repositories method.

 from 
  
 google.cloud 
  
 import 
 aiplatform_v1 
 PROJECT_ID 
 = 
 "my-project" 
 LOCATION 
 = 
 "us-central1" 
 REPOSITORY_ID 
 = 
 "b223577f-a3fb-482c-a22c-0658c6602598" 
 TEMPLATE_ID 
 = 
 "6524523989455339520" 
 API_ENDPOINT 
 = 
 f 
 " 
 { 
 LOCATION 
 } 
 -aiplatform.googleapis.com" 
 PARENT 
 = 
 f 
 "projects/ 
 { 
 PROJECT_ID 
 } 
 /locations/ 
 { 
 LOCATION 
 } 
 " 
 schedules_service_client 
 = 
 aiplatform_v1 
 . 
  ScheduleServiceClient 
 
 ( 
 client_options 
 = 
 { 
 "api_endpoint" 
 : 
 API_ENDPOINT 
 , 
 }) 
 schedule 
 = 
 schedules_service_client 
 . 
  create_schedule 
 
 ( 
 parent 
 = 
 PARENT 
 , 
 schedule 
 = 
 { 
 "display_name" 
 : 
 "my-notebook-schedule" 
 , 
 # Time specification. TZ is optional. 
 # cron = "* * * * *" to run it in the next minute. 
 "cron" 
 : 
 "TZ=America/Los_Angeles * * * * *" 
 , 
 # How many runs the schedule will trigger before it becomes COMPLETED. 
 # A Schedule in COMPLETED state will not trigger any more runs. 
 "max_run_count" 
 : 
 1 
 , 
 "max_concurrent_run_count" 
 : 
 1 
 , 
 "create_notebook_execution_job_request" 
 : 
 { 
 "parent" 
 : 
 PARENT 
 , 
 "notebook_execution_job" 
 : 
 { 
 "display_name" 
 : 
 "my-execution-job" 
 , 
 # Specify a NotebookRuntimeTemplate to source compute configuration from 
 "notebook_runtime_template_resource_name" 
 : 
 f 
 "projects/ 
 { 
 PROJECT_ID 
 } 
 /locations/ 
 { 
 LOCATION 
 } 
 /notebookRuntimeTemplates/ 
 { 
 TEMPLATE_ID 
 } 
 " 
 , 
 # Specify a Colab Enterprise notebook to run 
 "dataform_repository_source" 
 : 
 { 
 "dataform_repository_resource_name" 
 : 
 f 
 "projects/ 
 { 
 PROJECT_ID 
 } 
 /locations/ 
 { 
 LOCATION 
 } 
 /repositories/ 
 { 
 REPOSITORY_ID 
 } 
 " 
 , 
 }, 
 # Specify a Cloud Storage bucket to store output artifacts 
 "gcs_output_uri" 
 : 
 "gs://my-bucket/" 
 , 
 # Specify the identity that runs the notebook 
 "execution_user" 
 : 
 " 
 {EMAIL} 
 " 
 , 
 # Run as the service account instead 
 # "service_account": "my-service-account", 
 } 
 } 
 })

Terraform

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands . For more information, see the Terraform provider reference documentation .

The following sample uses the google_colab_schedule Terraform resource to schedule a Colab Enterprise notebook run.

  resource 
  
 "google_colab_runtime_template" 
  
 "my_runtime_template" 
  
 { 
  
 provider 
  
 = 
  
 google-beta 
  
 name 
  
 = 
  
 "{{index $.Vars "runtime_template_name"}}" 
  
 display_name 
  
 = 
  
 "Runtime template" 
  
 location 
  
 = 
  
 "us-central1" 
  
 machine_spec 
  
 { 
  
 machine_type 
  
 = 
  
 "e2-standard-4" 
  
 } 
  
 network_spec 
  
 { 
  
 enable_internet_access 
  
 = 
  
 true 
  
 } 
 } 
 resource 
  
 "google_storage_bucket" 
  
 "output_bucket" 
  
 { 
  
 provider 
  
 = 
  
 google-beta 
  
 name 
  
 = 
  
 "{{index $.Vars "bucket"}}" 
  
 location 
  
 = 
  
 "US" 
  
 force_destroy 
  
 = 
  
 true 
  
 uniform_bucket_level_access 
  
 = 
  
 true 
 } 
 resource 
  
 "google_secret_manager_secret" 
  
 "secret" 
  
 { 
  
 provider 
  
 = 
  
 google-beta 
  
 secret_id 
  
 = 
  
 "{{index $.Vars "secret"}}" 
  
 replication 
  
 { 
  
 auto 
  
 {} 
  
 } 
 } 
 resource 
  
 "google_secret_manager_secret_version" 
  
 "secret_version" 
  
 { 
  
 provider 
  
 = 
  
 google-beta 
  
 secret 
  
 = 
  
 google_secret_manager_secret.secret.id 
  
 secret_data 
  
 = 
  
 "secret-data" 
 } 
 resource 
  
 "google_dataform_repository" 
  
 "dataform_repository" 
  
 { 
  
 provider 
  
 = 
  
 google-beta 
  
 name 
  
 = 
  
 "{{index $.Vars "dataform_repository"}}" 
  
 display_name 
  
 = 
  
 "dataform_repository" 
  
 npmrc_environment_variables_secret_version 
  
 = 
  
 google_secret_manager_secret_version.secret_version.id 
  
 kms_key_name 
  
 = 
  
 "{{index $.Vars "key_name"}}" 
  
 labels 
  
 = 
  
 { 
  
 label_foo1 
  
 = 
  
 "label-bar1" 
  
 } 
  
 git_remote_settings 
  
 { 
  
 url 
  
 = 
  
 "https://github.com/OWNER/REPOSITORY.git" 
  
 default_branch 
  
 = 
  
 "main" 
  
 authentication_token_secret_version 
  
 = 
  
 google_secret_manager_secret_version.secret_version.id 
  
 } 
  
 workspace_compilation_overrides 
  
 { 
  
 default_database 
  
 = 
  
 "database" 
  
 schema_suffix 
  
 = 
  
 "_suffix" 
  
 table_prefix 
  
 = 
  
 "prefix_" 
  
 } 
 } 
 resource 
  
 "google_colab_schedule" "{{$.PrimaryResourceId}}" 
  
 { 
  
 provider 
  
 = 
  
 google-beta 
  
 display_name 
  
 = 
  
 "{{index $.Vars "display_name"}}" 
  
 location 
  
 = 
  
 "{{index $.TestEnvVars "location"}}" 
  
 allow_queueing 
  
 = 
  
 true 
  
 max_concurrent_run_count 
  
 = 
  
 2 
  
 cron 
  
 = 
  
 "TZ=America/Los_Angeles * * * * *" 
  
 max_run_count 
  
 = 
  
 5 
  
 start_time 
  
 = 
  
 "{{index $.Vars "start_time"}}" 
  
 end_time 
  
 = 
  
 "{{index $.Vars "end_time"}}" 
  
 desired_state 
  
 = 
  
 "ACTIVE" 
  
 create_notebook_execution_job_request 
  
 { 
  
 notebook_execution_job 
  
 { 
  
 display_name 
  
 = 
  
 "Notebook execution" 
  
 execution_timeout 
  
 = 
  
 "86400s" 
  
 dataform_repository_source 
  
 { 
  
 commit_sha 
  
 = 
  
 "randomsha123" 
  
 dataform_repository_resource_name 
  
 = 
  
 "projects/{{index $.TestEnvVars "project_id"}}/locations/{{index $.TestEnvVars "location"}}/repositories/${google_dataform_repository.dataform_repository.name}" 
  
 } 
  
 notebook_runtime_template_resource_name 
  
 = 
  
 "projects/${google_colab_runtime_template.my_runtime_template.project}/locations/${google_colab_runtime_template.my_runtime_template.location}/notebookRuntimeTemplates/${google_colab_runtime_template.my_runtime_template.name}" 
  
 gcs_output_uri 
  
 = 
  
 "gs://${google_storage_bucket.output_bucket.name}" 
  
 service_account 
  
 = 
  
 "{{index $.TestEnvVars "service_account"}}" 
  
 } 
  
 } 
  
 depends_on 
  
 = 
  
 [ 
  
 google_colab_runtime_template.my_runtime_template 
 , 
  
 google_storage_bucket.output_bucket 
 , 
  
 google_secret_manager_secret_version.secret_version 
 , 
  
 google_dataform_repository.dataform_repository 
 , 
  
 ] 
 }

In the Google Cloud console, you can view your schedules on the Schedulespage . You can view results from the completed notebook runs on the Executionspage .

View results

To view notebook run results, you can use the Google Cloud console, the gcloud CLI, or the Vertex AI Python client library.

Console

In the Google Cloud console, go to the Colab Enterprise Executionspage.

Go to Executions
Next to the notebook run that you want to view results for, click View result.

Colab Enterprise opens the result of the notebook run in a new tab.
To view the result, click the tab.

gcloud

Before using any of the command data below, make the following replacements:

PROJECT_ID : your project ID.
REGION : the region where your notebook run results are located.
SCHEDULE_NAME : the name of the schedule to view results for. To see results from all schedules, omit the --filter flag.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud  
colab  
executions  
list  
--project = 
 PROJECT_ID 
  
 \ 
  
--region = 
 REGION 
  
 \ 
  
--filter = 
 "scheduleResourceName: SCHEDULE_NAME 
"

Windows (PowerShell)

gcloud  
colab  
executions  
list  
--project = 
 PROJECT_ID 
  
 ` 
  
--region = 
 REGION 
  
 ` 
  
--filter = 
 "scheduleResourceName: SCHEDULE_NAME 
"

Windows (cmd.exe)

gcloud  
colab  
executions  
list  
--project = 
 PROJECT_ID 
  
^  
--region = 
 REGION 
  
^  
--filter = 
 "scheduleResourceName: SCHEDULE_NAME 
"

For more information about listing Colab Enterprise notebook runs from the command line, see the gcloud CLI documentation .

Python

To run the following code sample, you'll need the Dataform repository ID of your notebook. To get the repository ID of your notebook, you can use Dataform's list_repositories method.

 from 
  
 google.cloud 
  
 import 
 aiplatform_v1 
 PROJECT_ID 
 = 
 "my-project" 
 LOCATION 
 = 
 "us-central1" 
 API_ENDPOINT 
 = 
 f 
 " 
 { 
 LOCATION 
 } 
 -aiplatform.googleapis.com" 
 PARENT 
 = 
 f 
 "projects/ 
 { 
 PROJECT_ID 
 } 
 /locations/ 
 { 
 LOCATION 
 } 
 " 
 notebook_service_client 
 = 
 aiplatform_v1 
 . 
  NotebookServiceClient 
 
 ( 
 client_options 
 = 
 { 
 "api_endpoint" 
 : 
 API_ENDPOINT 
 , 
 }) 
 notebook_execution_jobs 
 = 
 notebook_service_client 
 . 
  list_notebook_execution_jobs 
 
 ( 
 parent 
 = 
 PARENT 
 ) 
 notebook_execution_jobs

Delete results

To delete a result from one of your notebook runs, you can use the Google Cloud console or the gcloud CLI.

Console

In the Google Cloud console, go to the Colab Enterprise Executionspage.

Go to Executions
Select the notebook run that you want to delete the result for.
Click Delete.
To confirm the deletion, click Confirm.

gcloud

Before using any of the command data below, make the following replacements:

NOTEBOOK_RUN_ID : the ID of the notebook run that you want to delete.
PROJECT_ID : your project ID.
REGION : the region where your notebook run is located.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud  
colab  
executions  
delete  
 NOTEBOOK_RUN_ID 
  
 \ 
  
--project = 
 PROJECT_ID 
  
 \ 
  
--region = 
 REGION

Windows (PowerShell)

gcloud  
colab  
executions  
delete  
 NOTEBOOK_RUN_ID 
  
 ` 
  
--project = 
 PROJECT_ID 
  
 ` 
  
--region = 
 REGION

Windows (cmd.exe)

gcloud  
colab  
executions  
delete  
 NOTEBOOK_RUN_ID 
  
^  
--project = 
 PROJECT_ID 
  
^  
--region = 
 REGION

For more information about deleting Colab Enterprise notebook runs from the command line, see the gcloud CLI documentation .

You can share notebook run results by providing access to the Cloud Storage bucket that contains your notebook run. Providing this access also grants users access to any other resources in the same Cloud Storage bucket (see Security considerations ).

For more information, see the Cloud Storage Sharing and collaboration page .

Security considerations

Your notebook run results are stored as notebook (IPYNB) files in a Cloud Storage bucket. Consider the following when you grant access to this bucket:

Anyone with access to the bucket can see the notebook file's code and the results of the notebook run.
Anyone with the ability to change the contents of the bucket can change the contents of the notebook file.

When your schedule is configured to use personal credentials, only the specified user is able to modify the schedule or trigger the schedule.

When your schedule is configured to use a service account, only users with the iam.serviceAccounts.actAs permission on the service account is able to modify the schedule or trigger the schedule.

View schedule details

You can view information about a schedule, including:

The Cloud Storage bucket that the schedule stores results in.
The start and end time.
The frequency.

To view schedule details, you can use the Google Cloud console or the gcloud CLI.

Console

In the Google Cloud console, go to the Colab Enterprise Schedulespage.

Go to Schedules
Click the name of a schedule.

The Schedule detailspage opens.
To go back to the Schedulespage, click Back to previous page.

gcloud

Before using any of the command data below, make the following replacements:

SCHEDULE : your schedule ID.
PROJECT_ID : your project ID.
REGION : the region where your schedule is located.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud  
colab  
schedules  
describe  
 SCHEDULE 
  
 \ 
  
--project = 
 PROJECT_ID 
  
 \ 
  
--region = 
 REGION

Windows (PowerShell)

gcloud  
colab  
schedules  
describe  
 SCHEDULE 
  
 ` 
  
--project = 
 PROJECT_ID 
  
 ` 
  
--region = 
 REGION

Windows (cmd.exe)

gcloud  
colab  
schedules  
describe  
 SCHEDULE 
  
^  
--project = 
 PROJECT_ID 
  
^  
--region = 
 REGION

For more information about viewing Colab Enterprise schedules from the command line, see the gcloud CLI documentation .

Pause, resume, or delete a schedule

To pause, resume, or delete a schedule, you can use the Google Cloud console, the gcloud CLI, or Terraform.

Console

In the Google Cloud console, go to the Colab Enterprise Schedulespage.

Go to Schedules
Select a schedule.
Click Pause, Resume, or Delete.

gcloud

Before using any of the command data below, make the following replacements:

ACTION : one of pause , resume , or delete .
SCHEDULE_ID : your schedule ID.
PROJECT_ID : your project ID.
REGION : the region where your schedule is located.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud  
colab  
schedules  
 ACTION 
  
 SCHEDULE_ID 
  
 \ 
  
--project = 
 PROJECT_ID 
  
 \ 
  
--region = 
 REGION

Windows (PowerShell)

gcloud  
colab  
schedules  
 ACTION 
  
 SCHEDULE_ID 
  
 ` 
  
--project = 
 PROJECT_ID 
  
 ` 
  
--region = 
 REGION

Windows (cmd.exe)

gcloud  
colab  
schedules  
 ACTION 
  
 SCHEDULE_ID 
  
^  
--project = 
 PROJECT_ID 
  
^  
--region = 
 REGION

For more information about managing Colab Enterprise schedules from the command line, see the gcloud CLI documentation .

Terraform

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands . For more information, see the Terraform provider reference documentation .

The following sample uses the google_colab_schedule Terraform resource to pause or resume a schedule.

To use this sample, change the value of desired_state according to the following:

PAUSED to pause the schedule
ACTIVE to resume the schedule

  resource 
  
 "google_colab_runtime_template" 
  
 "my_runtime_template" 
  
 { 
  
 name 
  
 = 
  
 "{{index $.Vars "runtime_template_name"}}" 
  
 display_name 
  
 = 
  
 "Runtime template" 
  
 location 
  
 = 
  
 "us-central1" 
  
 machine_spec 
  
 { 
  
 machine_type 
  
 = 
  
 "e2-standard-4" 
  
 } 
  
 network_spec 
  
 { 
  
 enable_internet_access 
  
 = 
  
 true 
  
 } 
 } 
 resource 
  
 "google_storage_bucket" 
  
 "output_bucket" 
  
 { 
  
 name 
  
 = 
  
 "{{index $.Vars "bucket"}}" 
  
 location 
  
 = 
  
 "US" 
  
 force_destroy 
  
 = 
  
 true 
  
 uniform_bucket_level_access 
  
 = 
  
 true 
 } 
 resource 
  
 "google_storage_bucket_object" 
  
 "notebook" 
  
 { 
  
 name 
  
 = 
  
 "hello_world.ipynb" 
  
 bucket 
  
 = 
  
 google_storage_bucket.output_bucket.name 
  
 content 
  
 = 
  
<< EOF 
  
 { 
  
 "cells" 
 : 
  
 [ 
  
 { 
  
 "cell_type" 
 : 
  
 "code" 
 , 
  
 "execution_count" 
 : 
  
 null 
 , 
  
 "metadata" 
 : 
  
 {}, 
  
 "outputs" 
 : 
  
 [], 
  
 "source" 
 : 
  
 [ 
  
 "print(\"Hello, World!\")" 
  
 ] 
  
 } 
  
 ], 
  
 "metadata" 
 : 
  
 { 
  
 "kernelspec" 
 : 
  
 { 
  
 "display_name" 
 : 
  
 "Python 3" 
 , 
  
 "language" 
 : 
  
 "python" 
 , 
  
 "name" 
 : 
  
 "python3" 
  
 }, 
  
 "language_info" 
 : 
  
 { 
  
 "codemirror_mode" 
 : 
  
 { 
  
 "name" 
 : 
  
 "ipython" 
 , 
  
 "version" 
 : 
  
 3 
  
 }, 
  
 "file_extension" 
 : 
  
 ".py" 
 , 
  
 "mimetype" 
 : 
  
 "text/x-python" 
 , 
  
 "name" 
 : 
  
 "python" 
 , 
  
 "nbconvert_exporter" 
 : 
  
 "python" 
 , 
  
 "pygments_lexer" 
 : 
  
 "ipython3" 
 , 
  
 "version" 
 : 
  
 "3.8.5" 
  
 } 
  
 }, 
  
 "nbformat" 
 : 
  
 4 
 , 
  
 "nbformat_minor" 
 : 
  
 4 
  
 } 
  
 EOF 
 } 
 resource 
  
 "google_colab_schedule" "{{$.PrimaryResourceId}}" 
  
 { 
  
 display_name 
  
 = 
  
 "{{index $.Vars "display_name"}}" 
  
 location 
  
 = 
  
 "{{index $.TestEnvVars "location"}}" 
  
 max_concurrent_run_count 
  
 = 
  
 2 
  
 cron 
  
 = 
  
 "TZ=America/Los_Angeles * * * * *" 
  
 desired_state 
  
 = 
  
 "PAUSED" 
  
 create_notebook_execution_job_request 
  
 { 
  
 notebook_execution_job 
  
 { 
  
 display_name 
  
 = 
  
 "Notebook execution" 
  
 gcs_notebook_source 
  
 { 
  
 uri 
  
 = 
  
 "gs://${google_storage_bucket_object.notebook.bucket}/${google_storage_bucket_object.notebook.name}" 
  
 generation 
  
 = 
  
 google_storage_bucket_object.notebook.generation 
  
 } 
  
 notebook_runtime_template_resource_name 
  
 = 
  
 "projects/${google_colab_runtime_template.my_runtime_template.project}/locations/${google_colab_runtime_template.my_runtime_template.location}/notebookRuntimeTemplates/${google_colab_runtime_template.my_runtime_template.name}" 
  
 gcs_output_uri 
  
 = 
  
 "gs://${google_storage_bucket.output_bucket.name}" 
  
 service_account 
  
 = 
  
 "{{index $.TestEnvVars "service_account"}}" 
  
 } 
  
 } 
  
 depends_on 
  
 = 
  
 [ 
  
 google_colab_runtime_template.my_runtime_template 
 , 
  
 google_storage_bucket.output_bucket 
 , 
  
 ] 
 }

What's next

To find a notebook that can help you get your project started quickly, see the notebook gallery .
Learn more about runtimes and runtime templates .
Learn how to create a runtime template .
Learn more about accessing Google Cloud services and APIs in your notebook.

Schedule a notebook run

Overview

Limitations

Before you begin

Required roles for scheduling the notebook run

Required roles for running the notebook

Required permissions

Run a notebook once

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Terraform

Schedule a notebook run

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Terraform

View results

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Delete results

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Share a notebook run's results

Security considerations

View schedule details

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Pause, resume, or delete a schedule

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

What's next