Create an instance with user credential access

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

This page describes how to create a Vertex AI Workbench instance thataccesses Google Cloud services and APIs through your user credentials.

Your user credentials are the credentials associated with your Google Account.Your user credentials determine which Google Cloud services and APIs yourGoogle Account has access to.

By default, when you run code in a Vertex AI Workbench instance,your instance can access Google Cloud services and APIs by usingthe credentials associated with your instance's service account. Thismeans that your instance has the same access to Google Cloud asthe service account.

This page describes how to create and configure an instance so that ithas the same access to Google Cloud as your user credentials.

Overview

Vertex AI Workbench uses a global google-managed OAuth clientto manage user credential access, scoped for the Google Cloud resourcesin the user's project. Users must grant consent to the OAuth Client tomanage their credentials for each Vertex AI Workbench instance.This is done one time per instance through a dialog that opens whenyou click theOpen JupyterLab button in the Google Cloud console.

The service account used to create the Vertex AI Workbench instance is thefollowing service agent:

service-PROJECT_NUMBER@gcp-sa-notebooks-vm.iam.gserviceaccount.com.

This service agent provides limited permissions for essential services suchas exporting logs. Users can't specify a different service accountif the end user credentials feature is enabled.

Instances with end user credentials enabled have thenotebooks-managed-euc: trueCompute Engine label and theeuc-enabled: true metadata keyattached to the VM resource to denote the feature enablement.

Limitations

Consider the following limitations when you plan your project:

• Vertex AI Workbench uses a global google-managed OAuth clientto manage user credential access. Organizations can'tenact fine grain controls, access the OAuth client, or use loggingto check for use of the OAuth client.

• To protect the security of Vertex AI Workbench instances withmanaged user credentials,users aren't able to:

  • Use SSH to access the instance.
  • Run a Vertex AI Workbench post-startup script or aCompute Engine startup script.
  • Access the detailed VM page.
  • Use an image that isn't created by Google.

• Usingthird partycredentialsisn't supported because the OAuth client only supports Google-managedOAuth credentials.

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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the API

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the API

Required roles

To get the permissions that you need to create a Vertex AI Workbench instance, ask your administrator to grant you theNotebooks Runner (roles/notebooks.runner) IAM role on the project. For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Create a single user instance

To create a Vertex AI Workbench instance by usingthe Google Cloud console, do the following:

1. In the Google Cloud console, go to theInstances page.

   Go to Instances

2. Clickadd_box Create new.

3. In theNew instance dialog, clickAdvanced options.

4. In theCreate instance dialog, in theDetails section,provide the following information for your new instance:

   • Name: Provide a name for your new instance. The namemust start with a letter followed by up to 62 lowercase letters,numbers, or hyphens (-), and cannot end with a hyphen.
   • Region andZone: Select a region and zone forthe new instance. For best network performance,select the region that is geographically closest to you.See the availableVertex AI Workbenchlocations.

5. In theIAM and Security section, selectSingle user.

6. In theUser email field,enter the user account that you want to grant access. If thespecified user is not the creator of the instance, you must grantthe specified user theService Account Userrole(roles/iam.serviceAccountUser) on the instance's service account.

7. SelectEnable managed end user credentials.

8. Complete the rest of the instance creation dialog, and thenclickCreate.

   Vertex AI Workbench creates an instance and automatically starts it.When the instance is ready to use, Vertex AI Workbenchactivates anOpen JupyterLab link in the Google Cloud console.

9. Users must grant consent to the OAuth client to manage their credentialsfor each Vertex AI Workbench instance. This is done one timeper instance. To grant consent, clickOpen JupyterLab and completethe dialog that appears.

   If you try to access the instance without granting consent, JupyterLabdisplays a message to authenticate by opening JupyterLab from theGoogle Cloud console.

10. To verify that your end user credentials are available within JupyterLab,open a Terminal in JupyterLab, and enter the following command:

    gcloudauthlist

Authenticate the instance with your user credentials

Vertex AI Workbench can use Application Default Credentials (ADC)to authenticate your user credentials to Google Cloud services and APIs.This section describes how to provide your user credentials to ADC if any ofthe limitations prevent you from enabling managed credentials.

The authentication steps depend on whether you are using a Google Accountor third party credentials.