Use Terraform to create a user-managed notebooks instance

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

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 Cloud project. Learn how to check if billing is enabled on a 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 Cloud project. Learn how to check if billing is enabled on a project.

7. Enable the Vertex AI API.

   Enable the API

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. If prompted to authorize Cloud Shell, click Authorize.

   Terraform initializes the working directory. you'll see the following output:

   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

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.