Create an instance with third party credentials

Create an instance with third party credentials

Preview

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

This page describes how to create a Vertex AI Workbench instance with third party credentials.

Overview

You can create and manage Vertex AI Workbench instances with third party credentials provided by Workforce Identity Federation. Workforce Identity Federation uses your external identity provider (IdP) to grant a group of users access to Vertex AI Workbench instances through a proxy.

Access to a Vertex AI Workbench instance is granted by assigning a workforce pool principal to the Vertex AI Workbench instance's service account.

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 Notebooks API.

   Enable the API

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 Notebooks API.

   Enable the API

8. Configure your IdP with a workforce identity pool.

Required role for creating an instance

To ensure that your workforce pool principal has the necessary permissions to create a Vertex AI Workbench instance, ask your administrator to grant your workforce pool principal the Notebooks Admin (roles/notebooks.admin) 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 workforce pool principal the required permissions through custom roles or other predefined roles.

Required roles for using third party credentials

Your workforce pool principal needs access to your Vertex AI Workbench instance's service account, with specific permissions.

To ensure that the workforce pool principal has the necessary permissions to use a Vertex AI Workbench instance with third party credentials, ask your administrator to grant the workforce pool principal the following IAM roles on the service account that you'll specify when you create your instance:

• Service Account Token Creator (roles/iam.serviceAccountTokenCreator)
• Service Account User (roles/iam.serviceAccountUser)

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

Your administrator might also be able to give the workforce pool principal the required permissions through custom roles or other predefined roles.

Create the instance using third party credentials

You can create a Vertex AI Workbench using third party credentials by using the Google Cloud console or the gcloud CLI:

Console

1. Sign in to the Google Cloud console using a workforce pool provider.

   Go to the Console

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

   Go to Instances

3. Click  Create new.

4. In the New instance dialog, click Advanced options.

5. In the Create instance dialog, in the IAM and security section, do the following:

   1. Make sure Service account is selected.

   2. Clear Use default Compute Engine service account, and then, in the Service account email field, enter the service account email address that is associated with your workforce principal.

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

Follow the IAM guide for authenticating the gcloud CLI with a workforce identity pool.

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 specify a post-startup-script, you can use the post-startup-script metadata tag, in the format: "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"
• SERVICE_ACCOUNT_EMAIL: the service account email address that is associated with your workforce principal

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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_EMAIL

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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_EMAIL

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

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_EMAIL

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.

Access Jupyterlab with third party credentials

Your new Vertex AI Workbench instance creates two separate proxy URLs with the following domains:

• byoid.googleusercontent.com: This domain can only be used by users authenticating with a workforce identity pool. Its value is stored in your instance's metadata field proxy-byoid-url. This metadata value activates an Open JupyterLab link in the Google Cloud Workforce Identity Federation console (console.cloud.google/).

• googleusercontent.com: This domain can only be used by users authenticating with the default Google's First Party Authentication. Its value is stored in your instance's metadata field proxy-url. This metadata value activates an Open JupyterLab link in the Google Cloud console (console.cloud.google.com).

What's next

• To learn more about third party principals to use for provisioning notebooks, see Workforce Identity Federation.