Usa Terraform para crear una instancia de notebook administrada por el usuario

Los notebooks administrados por el usuario de Vertex AI Workbench están obsoletos. El 30 de enero de 2025, finalizará la compatibilidad con notebooks administrados por el usuario y se quitará la capacidad de crear instancias de notebooks administrados por el usuario. Las instancias existentes seguirán funcionando, pero los parches y las actualizaciones no estarán disponibles. Para seguir usando Vertex AI Workbench, te recomendamos que migres tus instancias de notebooks administrados por el usuario a instancias de Vertex AI Workbench.

En este instructivo, aprenderás a crear un archivo de configuración de Terraform y a aprovisionar una instancia de notebook administrada por el usuario en Vertex AI en el modo de cuenta de servicio.

Usa estas herramientas para completar los pasos de este instructivo:

• CLI de Terraform: Terraform está preinstalado en Cloud Shell. No es necesario instalar Terraform por separado para usar los comandos de la CLI de Terraform.

• Editor de Cloud Shell: Usa el editor de Cloud Shell para crear y administrar tu archivo de configuración de Terraform y la estructura de carpetas.

• Terminal de Cloud Shell: Usa la terminal de Cloud Shell para ejecutar los siguientes comandos de la CLI de Terraform, como terraform init, terraform plan, terraform apply y terraform destroy.

Antes de comenzar

Antes de compilar la infraestructura para los recursos de Vertex AI mediante Terraform, configura un proyecto de Google Cloud y un entorno de desarrollo. En esta sección, también se describe cómo habilitar la API de Vertex AI, que Terraform usa para interactuar con los recursos en tu proyecto.

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

Roles obligatorios

Si creaste el proyecto, tienes el rol de IAM Propietario (roles/owner) en el proyecto, que incluye todos los permisos necesarios. Pasa a la siguiente sección. Si tú no creaste el proyecto, quédate en esta sección.

Para garantizar que tu cuenta de usuario tenga los permisos necesarios para crear una instancia de notebooks administradas por el usuario de Vertex AI Workbench mediante Terraform, pídele a tu administrador que otorgue a tu cuenta de usuario los siguientes roles de IAM en el proyecto:

• Administrador de notebooks (roles/notebooks.admin) para crear y borrar instancias en Vertex AI Workbench.
• Usuario de la cuenta de servicio (roles/iam.serviceAccountUser) para ejecutar operaciones como cuenta de servicio. En este instructivo, no se especifica una cuenta de servicio, por lo que tu instancia de notebooks administrados por el usuario usa la cuenta de servicio predeterminada de Compute Engine.
• Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer) para inspeccionar estados y operaciones de servicio, y consumir cuotas y facturación de recursos del proyecto.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Es posible que tu administrador también pueda otorgar a tu cuenta de usuario los permisos necesarios a través de roles personalizados o de otros roles predefinidos.

Crea la estructura de carpetas y el archivo de configuración de Terraform

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. En la terminal de Cloud Shell, ejecuta el siguiente comando para establecer el directorio principal como el directorio activo:
   

   cd

3. Ejecuta el siguiente comando para crear una carpeta nueva llamada terraform:
   

   mkdir terraform

4. Inicia el editor de Cloud Shell
5. En el panel Explorer, haz clic con el botón derecho en la carpeta terraform y, luego, en Explorer.
6. Ingresa main.tf como el nombre del archivo y haz clic en Aceptar.

Define la infraestructura en el archivo de configuración de Terraform

1. Abre el archivo main.tf en el editor de código de Cloud Shell.

2. Reemplaza los marcadores de posición PROJECT_NAME y LOCATION en la siguiente muestra de configuración de Terraform y, luego, copia la muestra en el archivo main.tf:

   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: Ingresa el ID del proyecto de Google Cloud.

   • LOCATION: Ingresa una región y una zona para la instancia de notebooks administrados por el usuario. Por ejemplo, us-west2-b Para obtener el mejor rendimiento de red, selecciona la región que se encuentra más cerca de tu ubicación geográfica. Consulta las ubicaciones de notebooks administrados por el usuario disponibles.

3. Guarda el archivo main.tf.

Inicializa el directorio de trabajo que contiene el archivo de configuración de Terraform

1. Para abrir la terminal de Cloud Shell, en la barra de herramientas del editor de Cloud Shell, haz clic en Abrir terminal.

2. En la terminal de Cloud Shell, ejecuta el siguiente comando para establecer la carpeta terraform como el directorio de trabajo actual:

   cd ~/terraform
   

3. Ejecuta el siguiente comando:

   terraform init
   

4. Terraform inicializa el directorio de trabajo. Aparece este resultado:

   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.

   Nota: Debes ejecutar terraform init cada vez que actualices cualquier archivo de configuración en el directorio de trabajo de Terraform.

Obtén una vista previa del plan de ejecución según la configuración de Terraform

El plan de ejecución de Terraform indica los cambios que Terraform planea realizar en los servicios y la infraestructura de Vertex AI.

Ejecuta el siguiente comando para ver el plan de ejecución de Terraform.

terraform plan

Si se te solicita que autorices Cloud Shell, haz clic en Autorizar. Cloud Shell usa las credenciales del usuario de forma predeterminada durante la autorización.

Verás un resultado similar al siguiente:

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 indica el ID del proyecto de Google Cloud que especificaste.

• us-west2-b indica la región y la zona para la instancia de notebooks administrados por el usuario que especificaste.

Aplica los cambios propuestos en el plan de ejecución

1. Ejecuta el siguiente comando para aplicar los cambios del plan de ejecución a la infraestructura de Vertex AI y crear la instancia de notebooks administrados por el usuario:

   terraform apply
   

2. Verás un resultado similar al siguiente:

   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 indica el ID del proyecto de Google Cloud que especificaste.

   • us-west2-b indica la región y la zona para la instancia de notebooks administrados por el usuario que especificaste.

3. Escribe yes y presiona Intro. Verás un resultado similar al siguiente:

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

Visualiza tu instancia de notebooks administrados por el usuario

En la consola de Google Cloud, ve a la página Notebooks administrados por el usuario.

Ir a Notebooks administrados por el usuario

El notebook nuevo llamado “notebooks-instance-basic” aparece en la tabla. Ten en cuenta que la instancia de notebooks administrados por el usuario nueva puede tardar unos minutos en aprovisionarse después de ejecutar terraform apply.

Limpie su proyecto.

Limpia los recursos de Google Cloud que creaste durante este instructivo. Sigue estos pasos para evitar que se generen cargos inesperados de algunos recursos:

1. En la terminal de Cloud Shell, ejecuta el siguiente comando para establecer la carpeta terraform como el directorio de trabajo actual:

   cd ~/terraform
   

2. Para borrar los recursos de Vertex AI que creaste según tu configuración de Terraform, ejecuta el siguiente comando:

   terraform destroy
   

3. Verás un resultado similar al siguiente:

   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 indica el ID del proyecto de Google Cloud que especificaste.

   • us-west2-b indica la región y la zona para la instancia de notebooks administrados por el usuario que especificaste.

4. Escribe yes y presiona Intro. Verás un resultado similar al siguiente:

   Destroy complete! Resources: 2 destroyed.
   

5. Para verificar que se borró la instancia de notebooks administrados por el usuario, ve a la página Notebooks administrados por el usuario.

   Ir a Notebooks administrados por el usuario

6. Inicia el editor de Cloud Shell

7. Para borrar la carpeta terraform y su contenido, haz clic con el botón derecho en la carpeta terraform en el panel Explorer y, luego, en Explorer.

8. Cuando se te solicite, haz clic en Aceptar para confirmar.

Más formas de usar Terraform en Vertex AI

En este instructivo, se mostró cómo usar Terraform mediante la creación de un solo archivo de configuración y el aprovisionamiento de infraestructura basada en un recurso de Terraform. También puedes usar Terraform de las siguientes maneras:

• Agrega varios recursos de Terraform al mismo archivo de configuración de Terraform. A fin de obtener una lista de los recursos de Terraform para Vertex AI, consulta los recursos de Terraform disponibles para Vertex AI.

• Crea una estructura de directorio que incluya varias carpetas y archivos de configuración de Terraform Por ejemplo, puedes crear una carpeta y un archivo de configuración de Terraform independientes para cada tipo de recurso de Terraform.

¿Qué sigue?

• Obtén más información sobre el recurso google_notebooks_instance de Terraform en el registro de Terraform.

• Obtén más información sobre los notebooks administrados por el usuario y Vertex AI Workbench.

• Instala Terraform en la interfaz de línea de comandos local.

• Obtén más información sobre Terraform en el sitio web para desarrolladores de Terraform.

• Consulta la documentación de recursos de Terraform en el registro de Terraform.