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

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.

Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.

Ir al selector de proyectos

Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

Habilita la API de Vertex AI.

Habilita la API

En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.

Ir al selector de proyectos

Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

Habilita la API de Vertex AI.

Habilita la API

Funciones obligatorias

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.

Si quieres obtener más información para otorgar roles, consulta Administra el acceso.

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

En la consola de Google Cloud, activa Cloud Shell.

Activar Cloud Shell

En la parte inferior de la consola de Google Cloud, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

En la terminal de Cloud Shell, ejecuta el siguiente comando para establecer el directorio principal como el directorio activo:
```
cd
```
Ejecuta el siguiente comando para crear una carpeta nueva llamada terraform:
```
mkdir terraform
```
Inicia el editor de Cloud Shell
En el panel Explorador, haz clic con el botón derecho en la carpeta terraform y, luego, en Archivo nuevo.
Ingresa main.tf como el nombre del archivo y haz clic en Aceptar.

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

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

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.

Guarda el archivo main.tf.

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

Para abrir la terminal de Cloud Shell, en la barra de herramientas del editor de Cloud Shell, haz clic en Abrir terminal.
En la terminal de Cloud Shell, ejecuta el siguiente comando para establecer la carpeta terraform como el directorio de trabajo actual:
```
cd ~/terraform
```
Ejecuta el siguiente comando:
```
terraform init
```

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.

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

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
```

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.

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:

En la terminal de Cloud Shell, ejecuta el siguiente comando para establecer la carpeta terraform como el directorio de trabajo actual:
```
cd ~/terraform
```
Para borrar los recursos de Vertex AI que creaste según tu configuración de Terraform, ejecuta el siguiente comando:
```
terraform destroy
```

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        = "329223940713-compute@developer.gserviceaccount.com" -> 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.

Escribe yes y presiona Intro. Verás un resultado similar al siguiente:
```
Destroy complete! Resources: 2 destroyed.
```
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
Inicia el editor de Cloud Shell
Para borrar la carpeta terraform y su contenido, haz clic con el botón derecho en la carpeta terraform en el panel Explorador y, luego, en Borrar.
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.