Connect to a runtime

Connect to a runtime

This page shows you how to connect to a runtime in Colab Enterprise.

To run code in your notebook, you must connect to a runtime. A runtime is a compute resource that runs your code.

Before you begin

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

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

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

   Enable the APIs

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

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

   Enable the APIs

Connect by using different methods

This page shows you how to connect to a runtime by using the following methods:

• Use the default runtime
• Connect to an existing runtime
• Create a runtime

Use the default runtime

This section describes how to connect to the default runtime.

Required roles

To ensure that your user account has the necessary permissions to connect to the default runtime in a Colab Enterprise notebook, ask your administrator to grant your user account the Colab Enterprise User (roles/aiplatform.colabEnterpriseUser) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

Your administrator might also be able to give your user account 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.

Connect to the default runtime

When you run code in a notebook for the first time, Colab Enterprise automatically connects to the default runtime unless you specify a different runtime.

To connect to the default runtime without running code, do the following:

1. In the Google Cloud console, go to the Colab Enterprise Notebooks page.

   Go to Notebooks

2. In the Region menu, select the region that contains your notebook.

3. On the My notebooks tab, click the notebook that you want to open. If you haven't created a notebook yet, create a notebook.

4. In your notebook, click Connect.
   

5. If this is your first time connecting to a runtime with end-user credentials enabled, a Sign in dialog appears.

   The default runtime has end-user credentials enabled by default. To use a runtime that doesn't have access to your user credentials, create a runtime template without end-user credentials enabled.

   To grant Colab Enterprise access to your user credentials, complete the following steps:

   1. In the Sign in dialog, click your user account.

   2. Select See, edit, configure, and delete your Google Cloud data... to grant Colab Enterprise access to your user credentials.

      

   3. Click Continue.

Colab Enterprise connects to the default runtime. If the default runtime isn't running, Colab Enterprise starts the default runtime, and then connects to it.

Connect to an existing runtime

This section describes how to connect to an existing runtime by using the Connect to Vertex AI runtime dialog.

Required roles

To ensure that your user account has the necessary permissions to connect to an existing runtime in a Colab Enterprise notebook, ask your administrator to grant your user account the Colab Enterprise User (roles/aiplatform.colabEnterpriseUser) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

Your administrator might also be able to give your user account 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.

Connect to the existing runtime

To connect to an existing runtime:

1. In the Google Cloud console, go to the Colab Enterprise Notebooks page.

   Go to Notebooks

2. In the Region menu, select the region that contains your notebook.

3. On the My notebooks tab, click the notebook that you want to open. If you haven't created a notebook yet, create a notebook.

4. In your notebook, click the Additional connection options expander arrow, and then select Connect to a runtime.
   

   The Connect to Vertex AI runtime dialog opens.

5. For Select a runtime, select Connect to an existing runtime.

6. For Select an existing runtime option, select the runtime that you want to connect to. If there aren't any runtimes in the list, create a runtime or connect to the default runtime.

7. Click Connect.

8. If your runtime has end-user credentials enabled, and this is your first time connecting to a runtime with end-user credentials enabled, a Sign in dialog appears.

   To use a runtime that doesn't have access to your user credentials, create a runtime template without end-user credentials enabled.

   To grant Colab Enterprise access to your user credentials, complete the following steps:

   1. In the Sign in dialog, click your user account.

   2. Select See, edit, configure, and delete your Google Cloud data... to grant Colab Enterprise access to your user credentials.

      

   3. Click Continue.

Colab Enterprise connects to the runtime. If the runtime isn't running, Colab Enterprise starts the runtime, and then connects to it.

Create a runtime

This section describes how to create a runtime and connect to it by using the Connect to Vertex AI runtime dialog. Alternatively, you can create a runtime from the Runtimes tab.

Required roles

To ensure that your user account has the necessary permissions to create a runtime in Colab Enterprise, ask your administrator to grant your user account the Colab Enterprise Admin (roles/aiplatform.colabEnterpriseAdmin) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

Your administrator might also be able to give your user account 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.

Create a runtime and connect to it

To create a runtime and connect to it by using the Connect to Vertex AI runtime dialog:

1. In the Google Cloud console, go to the Colab Enterprise Notebooks page.

   Go to Notebooks

2. In the Region menu, select the region that contains your notebook.

3. On the My notebooks tab, click the notebook that you want to open. If you haven't created a notebook yet, create a notebook.

4. In your notebook, click the Additional connection options expander arrow, and then select Connect to a runtime.
   

   The Connect to Vertex AI runtime dialog opens.

5. For Select a runtime, select Create new runtime.

6. In the Runtime template menu, select a runtime template. If there aren't any runtime templates listed, create a runtime template.

7. In the Runtime name field, enter a name for your runtime.

8. Click Connect.

9. If the runtime template that you selected has end-user credentials enabled, and this is your first time connecting to a runtime with end-user credentials enabled, a Sign in dialog appears.

   To use a runtime that doesn't have access to your user credentials, create a runtime template without end-user credentials enabled.

   To grant Colab Enterprise access to your user credentials, complete the following steps:

   1. In the Sign in dialog, click your user account.

   2. Select See, edit, configure, and delete your Google Cloud data... to grant Colab Enterprise access to your user credentials.

      

   3. Click Continue.

Colab Enterprise starts the default runtime, and then connects to it.

Runtime management

By default, when you create a runtime, you automatically have the required permissions to delete (aiplatform.googleapis.com/notebookRuntimes.delete) and start (aiplatform.googleapis.com/notebookRuntimes.start) that runtime.

Troubleshoot

This section shows you how to resolve issues with connecting to runtimes in Colab Enterprise.

Unable to connect to a runtime

This issue occurs due to several reasons. See also Unable to connect to a default runtime. The most common causes are:

Browser blocks third party cookies

The browser that you are using is blocking a third party cookie that Colab Enterprise uses to establish an HTTPS connection with the runtime.

To resolve this issue, configure your browser's settings to allow the DATALAB_TUNNEL_TOKEN third party cookie from the domain *.aiplatform-notebook.googleusercontent.com.

Network blocks outbound traffic to notebook domains

Your network's firewall rules block outbound traffic to *.aiplatform-notebook.cloud.google.com or *aiplatform.googleapis.com.

To resolve this issue, configure your network's firewall rules to allow outbound traffic to *.aiplatform-notebook.cloud.google.com and *aiplatform.googleapis.com.

Unable to connect to a default runtime

The following error occurs when you try to connect to a default runtime when there isn't an existing default runtime template.

Failed to connect to runtime

When you connect to a default runtime that hasn't been created yet, Colab Enterprise first creates a default runtime template, and then uses that default runtime template to generate the default runtime. However, if you don't have the permissions required to create a runtime template, then Colab Enterprise can't create the default runtime template nor the default runtime.

To resolve this issue, ask your administrator to grant you a role that includes the aiplatform.notebookRuntimeTemplates.create permission.

Notebook slow to connect to runtime

A few minutes after starting a connection to a runtime, the Connecting message is still in the top right corner of the notebook, and Colab Enterprise hasn't connected to the runtime yet.

To resolve this issue, wait a few more minutes. Colab Enterprise is still connecting to a runtime. Connecting to a runtime that isn't already running can take a few minutes because Vertex AI is allocating a new virtual machine (VM) instance.

Unable to create a runtime

This issue occurs when you're unable to create a runtime. See also Unable to create a default runtime. The most common causes are:

Unavailable resources

The following error occurs when you try to create a runtime.

No available zone found for runtime RUNTIME_ID
for machine type MACHINE_TYPE
with accelerator type: ACCELERATOR. Please try again later.

This error occurs if there are no resources available for your machine type configuration within your notebook's region.

To resolve this issue, try a runtime with a different machine type configuration, or try again at a later time.

Default runtime already exists

The following error occurs when you try to create a runtime from the default runtime template when the default runtime already exists.

Failed to create runtime

One click runtime already exists.

If you try to create a runtime from a default runtime template, Colab Enterprise tries to create a default runtime. There can only be one default runtime per user, project, and region. If the default runtime already exists, Colab Enterprise is unable to create another default runtime.

To resolve this issue, connect to the existing default runtime or create a runtime from a non-default runtime template.

Unable to create a default runtime

When Colab Enterprise creates a default runtime, it first creates a default runtime template that it uses to generate the default runtime. If you try to create a default runtime without the permissions required to create a runtime template, then Colab Enterprise can't create the default runtime.

To resolve this issue, ask your administrator to grant you a role that includes the aiplatform.notebookRuntimeTemplates.create permission.

What's next

• Learn more about runtimes and runtime templates.
• Create a runtime template.