Usar o Terraform para criar uma instância de notebooks gerenciados pelo usuário

Os notebooks gerenciados pelo usuário do Vertex AI Workbench foram descontinuados. Em 30 de janeiro de 2025, o suporte a notebooks gerenciados pelo usuário será encerrado, e não será mais possível criar instâncias de notebooks gerenciados pelo usuário. As instâncias que já existem continuarão funcionando, mas patches, atualizações e upgrades não estarão disponíveis. Para continuar usando o Vertex AI Workbench, recomendamos que você migre suas instâncias de notebooks gerenciados pelo usuário para instâncias do Vertex AI Workbench.

Neste tutorial, você vai aprender a criar um arquivo de configuração do Terraform e provisionar uma instância de notebooks gerenciados pelo usuário na Vertex AI no modo de conta de serviço.

Use as seguintes ferramentas para concluir as etapas deste tutorial:

• CLI do Terraform: o Terraform é pré-instalado no Cloud Shell. Não é necessário instalar o Terraform separadamente para usar os comandos da CLI.

• Editor do Cloud Shell: use o editor do Cloud Shell para criar e gerenciar seu arquivo de configuração do Terraform e gerenciar a estrutura da pasta.

• Terminal do Cloud Shell: use o terminal do Cloud Shell para executar os seguintes comandos da CLI do Terraform, como terraform init, terraform plan terraform apply e terraform destroy.

Antes de começar

Antes de criar a infraestrutura de recursos da Vertex AI usando o Terraform, configure um projeto do Google Cloud e um ambiente de desenvolvimento. Nesta seção, também descrevemos como ativar a API Vertex AI, que o Terraform usa para interagir com os recursos no projeto.

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

Funções exigidas

Caso tenha criado o projeto, você terá o papel do IAM de Proprietário (roles/owner) no projeto, que inclui todas as permissões necessárias. Vá para a próxima seção. Se você não criou o projeto, continue nesta seção.

Para garantir que sua conta de usuário tenha as permissões necessárias para criar uma instância de notebooks gerenciados pelo usuário do Vertex AI Workbench, peça ao administrador para conceder à sua conta de usuário os seguintes papéis do IAM no projeto:

• Administrador de notebooks (roles/notebooks.admin) para criar e excluir instâncias no Vertex AI Workbench.
• Usuário da conta de serviço (roles/iam.serviceAccountUser) para executar operações como uma conta de serviço. Este tutorial não especifica uma conta de serviço, portanto, sua instância de notebooks gerenciados pelo usuário usa a conta de serviço padrão do Compute Engine.
• Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer) para inspecionar estados e operações de serviço, além de consumir cota e o faturamento dos recursos do projeto.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

O administrador também pode conceder à sua conta de usuário as permissões necessárias via funções personalizadas ou outros papéis predefinidos.

Criar a estrutura de pastas e o arquivo de configuração do 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. No terminal do Cloud Shell, execute o seguinte comando para definir o diretório inicial como o ativo:
   

   cd

3. Execute este comando para criar uma nova pasta chamada terraform:
   

   mkdir terraform

4. Inicie o editor do Cloud Shell.
5. No painel Explorer, clique com o botão direito do mouse na pasta terraform e, em seguida, clique em Novo arquivo.
6. Insira main.tf como o nome do arquivo e clique em OK.

Definir a infraestrutura no arquivo de configuração do Terraform

1. Abra o arquivo main.tf no editor de código do Cloud Shell.

2. Substitua os marcadores de posição PROJECT_NAME e LOCATION na amostra de configuração do Terraform a seguir e, depois, copie a amostra para o arquivo 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: digite o código do projeto do Google Cloud.

   • LOCATION: insira uma região e uma zona para a instância de notebooks gerenciados pelo usuário. Por exemplo, us-west2-b. Para ter o melhor desempenho de rede, selecione a região mais próxima de você. Consulte os locais de notebooks gerenciados pelo usuário disponíveis.

3. Salve o arquivo main.tf.

Inicializar o diretório de trabalho que contém o arquivo de configuração do Terraform

1. Para abrir o terminal do Cloud Shell, clique em Abrir terminal na barra de ferramentas do editor.

2. No terminal do Cloud Shell, execute o seguinte comando para definir a pasta terraform como o diretório de trabalho atual:

   cd ~/terraform
   

3. Execute este comando:

   terraform init
   

4. O Terraform inicializa o diretório de trabalho. A seguinte saída é exibida:

   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.

   Observação: execute o comando terraform init sempre que um arquivo de configuração for atualizado no diretório de trabalho do Terraform.

Visualizar o plano de execução com base na configuração do Terraform

O plano de execução do Terraform indica as alterações que o Terraform pretende fazer na infraestrutura e nos serviços da Vertex AI.

Execute este comando para ver o plano de execução do Terraform.

terraform plan

Se for preciso autorizar o Cloud Shell, clique em Autorizar. O Cloud Shell usa as credenciais do usuário por padrão após a autorização.

Você verá uma saída semelhante a esta:

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 o ID do projeto do Google Cloud que você especificou.

• us-west2-b indica a região e a zona da instância de notebooks gerenciada pelo usuário que você especificou.

Aplicar as alterações propostas no plano de execução

1. Execute o comando a seguir para aplicar as alterações do plano de execução à infraestrutura da Vertex AI e criar a instância de notebooks gerenciados pelo usuário:

   terraform apply
   

2. Você verá uma saída semelhante a esta:

   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 o ID do projeto do Google Cloud que você especificou.

   • us-west2-b indica a região e a zona da instância de notebooks gerenciada pelo usuário que você especificou.

3. Digite yes e pressione Enter. Você verá uma saída semelhante a esta:

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

Visualizar sua instância de notebooks gerenciados pelo usuário

No Console do Google Cloud, acesse a página Notebooks gerenciados pelo usuário.

Acesse Notebooks gerenciados pelo usuário

O novo notebook chamado "notebooks-instance-basic" aparece listado na tabela. Observe que a nova instância de notebooks gerenciados pelo usuário pode levar alguns minutos para ser provisionada depois que você executar terraform apply.

Limpar o projeto

Limpe os recursos do Google Cloud que você criou durante este tutorial. Siga estas etapas para evitar cobranças inesperadas de alguns dos recursos.

1. No terminal do Cloud Shell, execute o seguinte comando para definir a pasta terraform como o diretório de trabalho atual:

   cd ~/terraform
   

2. Para excluir os recursos da Vertex AI que você criou com base na configuração do Terraform, execute o seguinte comando:

   terraform destroy
   

3. Você verá uma saída semelhante a esta:

   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 o ID do projeto do Google Cloud que você especificou.

   • us-west2-b indica a região e a zona da instância de notebooks gerenciada pelo usuário que você especificou.

4. Digite yes e pressione Enter. Você verá uma saída semelhante a esta:

   Destroy complete! Resources: 2 destroyed.
   

5. Para verificar se a instância de notebooks gerenciados pelo usuário foi excluída, acesse a página Notebooks gerenciados pelo usuário.

   Acesse Notebooks gerenciados pelo usuário

6. Inicie o editor do Cloud Shell.

7. Para excluir a pasta terraform e o conteúdo dela, clique com o botão direito do mouse na pasta terraform no painel Explorer e clique em Excluir.

8. Quando solicitado, clique em OK para confirmar.

Outras maneiras de usar o Terraform na Vertex AI

Neste tutorial, mostramos como usar o Terraform criando apenas um arquivo de configuração e provisionando infraestrutura com base em um recurso do Terraform. Também é possível usar o Terraform das seguintes maneiras:

• Adicionar vários recursos do Terraform ao mesmo arquivo de configuração. Confira uma lista de recursos do Terraform para a Vertex AI em Recursos do Terraform disponíveis para a Vertex AI.

• Criar uma estrutura de diretórios composta por várias pastas e arquivos de configuração do Terraform. Por exemplo, é possível criar uma pasta separada e um arquivo de configuração do Terraform para cada tipo de recurso do Terraform.

A seguir

• Saiba mais sobre o recurso do Terraform google_notebooks_instance no registro do Terraform.

• Saiba mais sobre notebooks gerenciados pelo usuário e o Vertex AI Workbench.

• Instale o Terraform na interface de linha de comando local.

• Saiba mais sobre o Terraform no site para desenvolvedores do Terraform.

• Consulte a documentação de recursos do Terraform no registro do Terraform.