Create an instance with user credential access

This page describes how to create a Vertex AI Workbench instance that accesses 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 your Google 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 using the credentials associated with your instance's service account. This means that your instance has the same access to Google Cloud as the service account.

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

Overview

Vertex AI Workbench doesn't directly support user credential access, but you can still configure an instance to have user credential-based access to Google Cloud services and APIs.

This page describes how to configure and authenticate a user credential-based instance by using these steps:

Prepare a service account with limited permissions. This service account won't have the ability to access Google Cloud, except for specific access that is required for the instance to function.
Create an instance with the following specifications:
- Single user access. This limits access to JupyterLab to only the user you specify.
- SSH access turned off. SSH access to your instance is managed through OS Login by default. Turning off SSH access prevents access from users who might have SSH access to your underlying Compute Engine VM.
- Owned by your service account with limited permissions. By default a new instance is owned by a service account and can access any Google Cloud services and APIs that the service account has access to. Specifying your service account with limited permissions prevents unexpected access to Google Cloud services and APIs so that you can set up access that is controlled by your user credentials.
Authenticate the instance with your user credentials. After the instance is running, you provide your user credentials to Application Default Credentials (ADC). ADC authenticates your user credentials to Google Cloud services and APIs. This is what gives your Vertex AI Workbench instance the same access to Google Cloud as your user 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.

Go to project selector

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

Enable the Notebooks API.

Enable the API

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

Go to project selector

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

Enable the Notebooks API.

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 the Notebooks Runner (roles/notebooks.runner) IAM role on the project. 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.

Prepare a service account

A Vertex AI Workbench instance requires a service account to create a Compute Engine VM instance that hosts the JupyterLab server. This service account also manages required logging activities.

You must prepare a service account with only the following permissions:

logging.logEntries.create
logging.logEntries.route
monitoring.metricDescriptors.create
monitoring.metricDescriptors.get
monitoring.metricDescriptors.list
monitoring.monitoredResourceDescriptors.get
monitoring.monitoredResourceDescriptors.list
monitoring.timeSeries.create

To create a service account, see Create service accounts.

To modify an existing service account, see List and edit service accounts.

Create a single user instance

You can create a Vertex AI Workbench instance by using the Google Cloud console or the Google Cloud CLI.

Console

To create a Vertex AI Workbench instance, do the following:

In the Google Cloud console, go to the Instances page.

Go to Instances
Click Create new.
In the New instance dialog, click Advanced options.
In the Create instance dialog, in the Details section, provide the following information for your new instance:
- Name: Provide a name for your new instance. The name must start with a letter followed by up to 62 lowercase letters, numbers, or hyphens (-), and cannot end with a hyphen.
- Region and Zone: Select a region and zone for the new instance. For best network performance, select the region that is geographically closest to you. See the available Vertex AI Workbench locations.
To turn off SSH access:
1. In the Environment section, in Metadata, click Add metadata.
2. For Key 1, enter disable-ssh.
3. For Value 1, enter true.
Note: SSH access can also be turned off through the constraints/compute.disableSshInBrowser organization policy.
In the IAM and Security section, select Single user, and then, in the User email field, enter the user account that you want to grant access. If the specified user is not the creator of the instance, you must grant the specified user the Service Account User role (roles/iam.serviceAccountUser) on the instance's service account.
Clear Use default Compute Engine service account, and then enter the email address of the service account that you prepared earlier in this guide. If you didn't prepare a service account yet, see Prepare a service account.
Complete the rest of the instance creation dialog, and then click Create.

Vertex AI Workbench creates an instance and automatically starts it. When the instance is ready to use, Vertex AI Workbench activates an Open JupyterLab link.

gcloud

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

INSTANCE_NAME: the name of your Vertex AI Workbench instance; must start with a letter followed by up to 62 lowercase letters, numbers, or hyphens (-), and cannot end with a hyphen
PROJECT_ID: your project ID
LOCATION: the zone where you want your instance to be located
VM_IMAGE_PROJECT: the ID of the Google Cloud project that VM image belongs to, in the format: projects/IMAGE_PROJECT_ID
VM_IMAGE_NAME: the full image name; to find the image name of a specific version, see Find the specific version
MACHINE_TYPE: the machine type of your instance's VM
METADATA: custom metadata to apply to this instance; for example, to disable SSH you can use the disable-ssh metadata tag, in the format: "--metadata=disable-ssh=true"
SERVICE_ACCOUNT: the email address of the service account to use for the instance
OWNER: the account email address of the single user who can access the instance; only one user is supported

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud workbench instances create INSTANCE_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --vm-image-project=VM_IMAGE_PROJECT \
    --vm-image-name=VM_IMAGE_NAME \
    --machine-type=MACHINE_TYPE \
    --metadata=METADATA \
    --service-account-email=SERVICE_ACCOUNT
    --instance-owners=OWNER

Windows (PowerShell)

gcloud workbench instances create INSTANCE_NAME `
    --project=PROJECT_ID `
    --location=LOCATION `
    --vm-image-project=VM_IMAGE_PROJECT `
    --vm-image-name=VM_IMAGE_NAME `
    --machine-type=MACHINE_TYPE `
    --metadata=METADATA `
    --service-account-email=SERVICE_ACCOUNT
    --instance-owners=OWNER

Windows (cmd.exe)

gcloud workbench instances create INSTANCE_NAME ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --vm-image-project=VM_IMAGE_PROJECT ^
    --vm-image-name=VM_IMAGE_NAME ^
    --machine-type=MACHINE_TYPE ^
    --metadata=METADATA ^
    --service-account-email=SERVICE_ACCOUNT
    --instance-owners=OWNER

For more information about the command for creating an instance from the command line, see the gcloud CLI documentation.

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

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.

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

Google Account

After you can access JupyterLab on your instance, do the following:

In the Google Cloud console, go to the Instances page.

Go to Instances
Next to your instance's name, click Open JupyterLab.
In JupyterLab, select File > New > Terminal.
In the terminal window, run the following:
```
gcloud auth login
```
Enter Y.
Follow the instructions to copy a verification code and enter it into the terminal.

Third party credentials

If you created an instance with third party credentials, then after the JupyterLab proxy is available, do the following:

Open JupyterLab by using the federated JupyterLab proxy.
In JupyterLab, select File > New > Terminal.
Create a Workforce Identity Federation credential file with headless sign-in.
In the terminal window, run the following:
```
gcloud auth login --cred-file="CREDENTIAL_FILE"
```
Replace CREDENTIAL_FILE with the path and name of the credential file that you created.
Follow the instructions to authenticate through the third party authentication portal.
Confirm that your credentials are accessible through your instance by using the following command:
```
gcloud auth list
```

Limitations

Migrating a managed notebooks instance to Vertex AI Workbench instances doesn't retain the user credential-based access of the original instance. You must configure the migrated instance and authenticate the user credentials as described in this guide.