Use Terraform to create a user-managed notebooks instance

Vertex AI Workbench user-managed notebooks is deprecated. On January 30, 2025, support for user-managed notebooks will end and the ability to create user-managed notebooks instances will be removed. Existing instances will continue to function but patches, updates, and upgrades won't be available. To continue using Vertex AI Workbench, we recommend that you migrate your user-managed notebooks instances to Vertex AI Workbench instances.

In this tutorial, you learn how to create a Terraform configuration file and provision a user-managed notebooks instance in Vertex AI in Service account mode.

Use the following tools to complete the steps in this tutorial:

• Terraform CLI: Terraform is preinstalled in the Cloud Shell. You don't need to install Terraform separately to use the Terraform CLI commands.

• Cloud Shell Editor: Use the Cloud Shell Editor to create and manage your Terraform configuration file, and manage the folder structure.

• Cloud Shell terminal: Use the Cloud Shell terminal to run the following Terraform CLI commands, such as terraform init, terraform plan, terraform apply, and terraform destroy.

Before you begin

Before you can build the infrastructure for Vertex AI resources using Terraform, set up a Google Cloud project and a development environment. This section also describes how to enable the Vertex AI API, which Terraform uses to interact with the resources in your project.

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 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 Vertex AI API.

   Enable the API

Required roles

If you created the project, you have the Owner (roles/owner) IAM role on the project, which includes all required permissions. Skip to the next section. If you didn't create the project yourself, continue in this section.

To ensure that your user account has the necessary permissions to create a Vertex AI Workbench user-managed notebooks instance by using Terraform, ask your administrator to grant your user account the following IAM roles on the project:

• Notebooks Admin (roles/notebooks.admin) for creating and deleting instances in Vertex AI Workbench.
• Service Account User (roles/iam.serviceAccountUser) for running operations as a service account. This tutorial doesn't specify a service account, so your user-managed notebooks instance uses the default Compute Engine service account.
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) for inspecting service states and operations, and consuming quota and billing for project resources.

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.

Create the folder structure and Terraform configuration file

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. In the Cloud Shell terminal, run the following command to set the home directory as the active directory:
   

   cd

3. Run the following command to create a new folder named terraform:
   

   mkdir terraform

4. Launch the Cloud Shell Editor.
5. In the Explorer pane, right-click the terraform folder and then click New File.
6. Enter main.tf as the filename and click OK.

Define the infrastructure in the Terraform configuration file

1. Open the main.tf file in the Cloud Shell Editor.

2. Replace the PROJECT_NAME and LOCATION placeholders in the following Terraform configuration sample, and then copy the sample to the main.tf file:

   resource "google_project_service" "notebooks" {
     provider           = google
     service            = "notebooks.googleapis.com"
     disable_on_destroy = false
   }
   
   resource "google_notebooks_instance" "basic_instance" {
     project      = "PROJECT_ID"
     name         = "notebooks-instance-basic"
     provider     = google
     location     = "LOCATION"
     machine_type = "e2-medium"
   
     vm_image {
       project      = "deeplearning-platform-release"
       image_family = "tf-ent-2-9-cu113-notebooks"
     }
   
     depends_on = [
       google_project_service.notebooks
     ]
   }
   

   • PROJECT_ID: Enter the Google Cloud project ID.

   • LOCATION: Enter a region and zone for the user-managed notebooks instance. For example, us-west2-b. For best network performance, select the region that is geographically closest to you. See the available user-managed notebooks locations.

3. Save the main.tf file.

Initialize the working directory containing the Terraform configuration file

1. To open the Cloud Shell terminal, on the toolbar of the Cloud Shell Editor, click Open Terminal.

2. In the Cloud Shell terminal, run the following command to set the terraform folder as the current working directory:

   cd ~/terraform
   

3. Run the following command:

   terraform init
   

4. Terraform initializes the working directory. The following output appears:

   Terraform has been successfully initialized!
   
   You may now begin working with Terraform. Try running "terraform plan" to see
   any changes that are required for your infrastructure. All Terraform commands
   should now work.
   
   If you ever set or change modules or backend configuration for Terraform,
   rerun this command to reinitialize your working directory. If you forget, other
   commands will detect it and remind you to do so if necessary.

   Note: You need to run terraform init every time you update any configuration file in the Terraform working directory.

Preview the execution plan based on the Terraform configuration

The Terraform execution plan indicates the changes that Terraform plans to make to the Vertex AI infrastructure and services.

Run the following command to view the Terraform execution plan.

terraform plan

If prompted to authorize Cloud Shell, click Authorize. Cloud Shell uses the user's credentials by default upon authorizing.

You'll see output similar to the following:

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following
symbols:
  + create

Terraform will perform the following actions:

  # google_notebooks_instance.basic_instance will be created
  + resource "google_notebooks_instance" "basic_instance" {
      + create_time     = (known after apply)
      + id              = (known after apply)
      + labels          = (known after apply)
      + location        = "us-west2-b"
      + machine_type    = "e2-medium"
      + name            = "notebooks-instance-basic"
      + network         = (known after apply)
      + project         = "my_project"
      + proxy_uri       = (known after apply)
      + service_account = (known after apply)
      + state           = (known after apply)
      + subnet          = (known after apply)
      + update_time     = (known after apply)

      + shielded_instance_config {
          + enable_integrity_monitoring = (known after apply)
          + enable_secure_boot          = (known after apply)
          + enable_vtpm                 = (known after apply)
        }

      + vm_image {
          + image_family = "tf-ent-2-9-cu113-notebooks"
          + project      = "deeplearning-platform-release"
        }
    }

  # google_project_service.notebooks will be created
  + resource "google_project_service" "notebooks" {
      + disable_on_destroy = false
      + id                 = (known after apply)
      + project            = (known after apply)
      + service            = "notebooks.googleapis.com"
    }

Plan: 2 to add, 0 to change, 0 to destroy.

• my_project indicates the Google Cloud project ID that you specified.

• us-west2-b indicates the region and zone for the user-managed notebooks instance that you specified.

Apply the changes proposed in the execution plan

1. Run the following command to apply the changes from the execution plan to the Vertex AI infrastructure and create the user-managed notebooks instance:

   terraform apply
   

2. You'll see output similar to the following:

   Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following
   symbols:
     + create
   
   Terraform will perform the following actions:
   
     # google_notebooks_instance.basic_instance will be created
     + resource "google_notebooks_instance" "basic_instance" {
         + create_time     = (known after apply)
         + id              = (known after apply)
         + labels          = (known after apply)
         + location        = "us-west2-b"
         + machine_type    = "e2-medium"
         + name            = "notebooks-instance-basic"
         + network         = (known after apply)
         + project         = "my_project"
         + proxy_uri       = (known after apply)
         + service_account = (known after apply)
         + state           = (known after apply)
         + subnet          = (known after apply)
         + update_time     = (known after apply)
   
         + shielded_instance_config {
             + enable_integrity_monitoring = (known after apply)
             + enable_secure_boot          = (known after apply)
             + enable_vtpm                 = (known after apply)
           }
   
         + vm_image {
             + image_family = "tf-ent-2-9-cu113-notebooks"
             + project      = "deeplearning-platform-release"
           }
       }
   
     # google_project_service.notebooks will be created
     + resource "google_project_service" "notebooks" {
         + disable_on_destroy = false
         + id                 = (known after apply)
         + project            = (known after apply)
         + service            = "notebooks.googleapis.com"
       }
   
   Plan: 2 to add, 0 to change, 0 to destroy.
   
   Do you want to perform these actions?
     Terraform will perform the actions described above.
     Only 'yes' will be accepted to approve.
   
     Enter a value:
   

   • my_project indicates the Google Cloud project ID that you specified.

   • us-west2-b indicates the region and zone for the user-managed notebooks instance that you specified.

3. Type yes and press Enter. You'll see output similar to the following:

   Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
   

View your user-managed notebooks instance

In the Google Cloud console, go to the User-managed notebooks page.

Go to User-managed notebooks

The new notebook named "notebooks-instance-basic" appears listed in the table. Note that the new user-managed notebooks instance might take a few minutes to get provisioned after you run terraform apply.

Clean up your project

Clean up the Google Cloud resources that you created during this tutorial. Follow these steps to avoid incurring unexpected charges from some of the resources:

1. In the Cloud Shell terminal, run the following command to set the terraform folder as the current working directory:

   cd ~/terraform
   

2. To delete the Vertex AI resources that you created based on your Terraform configuration, run the following command:

   terraform destroy
   

3. You'll see output similar to the following:

   Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
     - destroy
   
   Terraform will perform the following actions:
   
     # google_notebooks_instance.basic_instance will be destroyed
     - resource "google_notebooks_instance" "basic_instance" {
         - create_time            = "2022-12-01T21:14:05.065893475Z" -> null
         - id                     = "projects/my_project/locations/us-west2-b/instances/notebooks-instance-basic" -> null
         - install_gpu_driver     = false -> null
         - labels                 = {
             - "goog-caip-notebook" = ""
           } -> null
         - location               = "us-west2-b" -> null
         - machine_type           = "e2-medium" -> null
         - name                   = "notebooks-instance-basic" -> null
         - network                = "https://www.googleapis.com/compute/v1/projects/my_project/global/networks/default" -> null
         - no_proxy_access        = false -> null
         - no_public_ip           = false -> null
         - project                = "my_project" -> null
         - service_account        = "[e-mail]" -> null
         - service_account_scopes = [] -> null
         - state                  = "PROVISIONING" -> null
         - subnet                 = "https://www.googleapis.com/compute/v1/projects/my_project/regions/us-west2/subnetworks/default" -> null
         - tags                   = [] -> null
         - update_time            = "2022-12-01T21:14:19.048432376Z" -> null
   
         - shielded_instance_config {
             - enable_integrity_monitoring = true -> null
             - enable_secure_boot          = false -> null
             - enable_vtpm                 = true -> null
           }
   
         - vm_image {
             - image_family = "tf-ent-2-9-cu113-notebooks" -> null
             - project      = "deeplearning-platform-release" -> null
           }
       }
   
     # google_project_service.notebooks will be destroyed
     - resource "google_project_service" "notebooks" {
         - disable_on_destroy = false -> null
         - id                 = "my_project/notebooks.googleapis.com" -> null
         - project            = "my_project" -> null
         - service            = "notebooks.googleapis.com" -> null
       }
   
   Plan: 0 to add, 0 to change, 2 to destroy.
   
   Do you really want to destroy all resources?
     Terraform will destroy all your managed infrastructure, as shown above.
     There is no undo. Only 'yes' will be accepted to confirm.
   
     Enter a value:
   

   • my_project indicates the Google Cloud project ID that you specified.

   • us-west2-b indicates the region and zone for the user-managed notebooks instance that you specified.

4. Type yes and press Enter. You'll see output similar to the following:

   Destroy complete! Resources: 2 destroyed.
   

5. To verify that the user-managed notebooks instance was deleted, go to the User-managed notebooks page.

   Go to User-managed notebooks

6. Launch the Cloud Shell Editor.

7. To delete the terraform folder and its contents, right-click the terraform folder in the Explorer pane and then click Delete.

8. When prompted, click OK to confirm.

More ways to use Terraform in Vertex AI

This tutorial showed you how to use Terraform by creating only one configuration file and provisioning infrastructure based on one Terraform resource. You can also use Terraform in the following ways:

• Add multiple Terraform resources to the same Terraform configuration file. For a list of Terraform resources for Vertex AI, see Terraform resources available for Vertex AI.

• Create a directory structure comprising multiple folders and Terraform configuration files. For example, you can create a separate folder and Terraform configuration file for each type of Terraform resource.

What's next

• Learn more about the google_notebooks_instance Terraform resource in the Terraform registry.

• Learn more about user-managed notebooks and Vertex AI Workbench.

• Install Terraform on your local command-line interface.

• Learn more about Terraform on the Terraform Developer website.

• Refer to Terraform resource documentation in the Terraform registry.