Migrar de notebooks gerenciados pelo usuário para instâncias do Vertex AI Workbench

Nesta página, descrevemos como migrar de uma instância de notebooks gerenciados pelo usuário para uma instância do Vertex AI Workbench. É possível migrar usando a ferramenta de migração Vertex AI Workbench ou migrar os dados e arquivos da instância manualmente.

Visão geral da ferramenta de migração

O Vertex AI Workbench fornece uma ferramenta de migração para migrar de uma instância de notebooks gerenciados pelo usuário para uma instância do Vertex AI Workbench.

A ferramenta de migração cria uma instância do Vertex AI Workbench com uma configuração semelhante à instância de notebooks gerenciados pelo usuário que você quer migrar. Por exemplo, a ferramenta de migração cria uma instância que tem o mesmo tipo de máquina, configuração de rede, configurações de desligamento inativo e outras especificações semelhantes. Em seguida, os arquivos no disco de dados da instância dos notebooks gerenciados pelo usuário são copiados para a instância do Vertex AI Workbench.

O Vertex AI Workbench não exclui nem altera sua instância de notebooks gerenciados pelo usuário. Portanto, após a migração, você pode continuar a usá-lo. Se você não precisar mais da instância de notebooks gerenciados pelo usuário, exclua a instância para evitar outras cobranças.

Faturamento

Se a instância de notebooks gerenciados pelo usuário usa discos permanentes extremos, a migração gera cobranças para operações de E/S. Consulte "IOPS provisionadas extremas" na seção de preços de disco permanente e hiperdisco do artigo de preços de disco.

Após a migração, a instância de notebooks gerenciados pelo usuário ainda existirá e gerará cobranças como antes. Se você não precisar mais da instância de notebooks gerenciados pelo usuário, exclua-a para evitar cobranças adicionais.

Comportamentos padrão da ferramenta de migração

A ferramenta de migração do Vertex AI Workbench tenta migrar sua instância de notebooks gerenciados pelo usuário para uma instância do Vertex AI Workbench com especificações correspondentes. Quando uma especificação na instância de notebooks gerenciados pelo usuário não está disponível nas instâncias do Vertex AI Workbench, a plataforma usa uma especificação padrão quando possível. Quando a ferramenta de migração não puder migrar uma especificação da instância de notebooks gerenciados pelo usuário, ela não será migrada.

A tabela a seguir lista alguns dos principais comportamentos de migração padrão para a ferramenta de migração.

Categoria especificação dos notebooks gerenciados pelo usuário Resultado da migração
SO Qualquer versão do Ubuntu Debian 11
Qualquer versão do Debian Debian 11
Framework Qualquer versão do CUDA CUDA 11.3
Qualquer versão do Python Python 3.10
Qualquer versão do PyTorch PyTorch 1.13
Qualquer versão do TensorFlow TensorFlow 2.11
Qualquer versão R Não migrado. consulte Adicionar um ambiente conda
Qualquer versão local do PySpark Não migrado. consulte Adicionar um ambiente conda
Qualquer versão do XGBoost Não migrado. consulte Adicionar um ambiente conda
Qualquer versão Python do Kaggle Não migrado. consulte Adicionar um ambiente conda
Qualquer versão do Jax Não migrado. consulte Adicionar um ambiente conda
Qualquer versão do Apache Beam Não migrado. consulte Adicionar um ambiente conda
Tipo de máquina Um tipo de máquina com suporte Tipo de máquina idêntico
Um tipo de máquina incompatível e2-standard-4
Aceleradores Aceleradores compatíveis Aceleradores idênticos
Aceleradores sem suporte A migração não inclui aceleradores
Configuração Encerramento de inatividade Migrado
Excluir para a lixeira Migrado
nbconvert Migrado
Permitir downloads do arquivo Migrado
Acesso ao terminal Migrado
Outro Permissões de gerenciamento de identidade e acesso Migrado, embora novas permissões sejam necessárias para usar a instância do Vertex AI Workbench
Modo de acesso Migrado
Rede Migrado
Script pós-inicialização Ao usar o console Google Cloud , a instância é migrada sem o script pós-inicialização. Para migrar a instância com esse script de inicialização, use a Google Cloud CLI ou a API REST para especificar a opção PostStartupScriptOption.
Dataproc Hub Não migrado. precisam migrar manualmente

Como especificar o script pós-inicialização

As instâncias de notebooks gerenciados pelo usuário que usam um script pós-inicialização precisam ser migradas para uma instância com a opção PostStartupScriptOption especificada. Use essa opção para indicar se você quer pular ou executar novamente o script pós-inicialização na nova instância do Vertex AI Workbench.

Não é possível especificar a opção PostStartupScriptOption no console do Google Cloud . Para especificar a opção PostStartupScriptOption ao migrar sua instância de notebooks gerenciados pelo usuário, use a Google Cloud CLI ou a API REST.

Antes de começar

  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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Notebooks API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Notebooks API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

    Funções exigidas

    Para receber as permissões necessárias para migrar uma instância de notebooks gerenciados pelo usuário para uma instância do Vertex AI Workbench, peça ao administrador para conceder a você o papel do IAM de executor de notebooks (roles/notebooks.runner) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Esse papel predefinido contém as permissões necessárias para migrar uma instância de notebooks gerenciados pelo usuário para uma instância do Vertex AI Workbench. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

    Permissões necessárias

    As permissões a seguir são necessárias para migrar uma instância de notebooks gerenciados pelo usuário para uma instância do Vertex AI Workbench:

    • notebooks.instances.create
    • notebooks.instances.get

    Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

    Verificação pré-migração

    Antes de migrar, verifique a qualificação para migração da instância de notebooks gerenciados pelo usuário. Para isso, liste suas instâncias e verifique se há avisos ou erros na saída.

    Liste suas instâncias

    Para listar as instâncias de notebooks gerenciados pelo usuário que ainda não foram migradas, use o método projects.locations.instances.list com o filtro migrated:false. É possível listá-los usando a gcloud CLI ou a API REST:

    gcloud

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • PROJECT_ID: o ID do projeto
    • LOCATION: a região onde a instância de notebooks gerenciados pelo usuário está localizada, ou use - para listar as instâncias de todas as regiões

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud notebooks instances list --project=PROJECT_ID \
    --location=LOCATION --filter=migrated:false --format=default

    Windows (PowerShell)

    gcloud notebooks instances list --project=PROJECT_ID `
    --location=LOCATION --filter=migrated:false --format=default

    Windows (cmd.exe)

    gcloud notebooks instances list --project=PROJECT_ID ^
    --location=LOCATION --filter=migrated:false --format=default

    REST

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto
    • LOCATION: a região onde a instância de notebooks gerenciados pelo usuário está localizada, ou use - para listar as instâncias de todas as regiões

    Método HTTP e URL: 

    GET https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?filter=migrated:false

    Para enviar a solicitação, escolha uma destas opções:

    curl

    Execute o seguinte comando:

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?filter=migrated:false"

    PowerShell

    execute o seguinte comando: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?filter=migrated:false" | Select-Object -Expand Content

    Verificar se há avisos ou erros na saída

    Se avisos ou erros de migração forem detectados, a saída do método projects.locations.instances.list vai incluir essas informações.

    Os avisos aparecem quando componentes específicos na configuração da instância dos notebooks gerenciados pelo usuário não são migrados para a mesma especificação em uma instância do Vertex AI Workbench. Por exemplo, se a instância de notebooks gerenciados pelo usuário usar um acelerador não compatível, um aviso será exibido na saída. Nesse caso, a instância é migrada sem acelerador. É possível anexar aceleradores após a migração. Analise os avisos na saída, considere os comportamentos padrão da ferramenta de migração e avalie se ela é aceitável para sua migração.

    Um ou mais erros na saída significam que não é possível migrar a instância de notebooks gerenciados pelo usuário usando a ferramenta de migração. É preciso migrar a instância manualmente.

    Para mais informações sobre avisos e erros de migração, consulte avisos e erros na documentação de InstanceMigrationEligibility.

    Migrar usando a ferramenta de migração

    É possível migrar a instância de notebooks gerenciados pelo usuário usando o Google Cloud console, a CLI gcloud ou a API REST.

    Console

    1. No console Google Cloud , acesse a página Notebooks gerenciados pelo usuário.

      Acesse Notebooks gerenciados pelo usuário

    2. Clique no botão Migrar.

    3. Na página Migrar notebooks gerenciados pelo usuário para instâncias, na guia Pronto, selecione a instância que você quer migrar.

    4. Clique em Migrar.

    5. Após a conclusão da migração, acesse a página Instâncias para ver sua nova instância do Vertex AI Workbench.

      Acesse "Instâncias"

    gcloud

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • PROJECT_ID: o ID do projeto
    • LOCATION: a região onde a instância de notebooks gerenciados pelo usuário está localizada
    • INSTANCE_ID: o ID da instância de notebooks gerenciados pelo usuário
    • POST_STARTUP_SCRIPT_OPTION: opcional: uma das opções de script pós-inicialização

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud notebooks instances migrate RUNTIME_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

    Windows (PowerShell)

    gcloud notebooks instances migrate RUNTIME_ID `
    --project=PROJECT_ID `
    --location=LOCATION `
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

    Windows (cmd.exe)

    gcloud notebooks instances migrate RUNTIME_ID ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

    REST

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID do projeto
    • LOCATION: a região onde a instância de notebooks gerenciados pelo usuário está localizada
    • INSTANCE_ID: o ID da instância de notebooks gerenciados pelo usuário
    • POST_STARTUP_SCRIPT_OPTION: opcional: uma das opções de script pós-inicialização

    Método HTTP e URL: 

    POST https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:migrate

    Corpo JSON da solicitação:

    {
  "postStartupScriptOption": (POST_STARTUP_SCRIPT_OPTION)
}

    Para enviar a solicitação, escolha uma destas opções:

    curl

    Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:migrate"

    PowerShell

    Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:migrate" | Select-Object -Expand Content

    Migrar anualmente

    Para migrar sua instância manualmente para uma instância do Vertex AI Workbench, use os seguintes métodos:

    • Use o Cloud Storage e o terminal: copie seus dados e arquivos para o Cloud Storage e, em seguida, para outra instância usando o terminal.

    • Usar o GitHub: copie seus dados e arquivos para um repositório do GitHub usando a extensão Git para JupyterLab.

    Neste guia, descrevemos como migrar dados e arquivos usando o Cloud Storage e o terminal.

    Requisitos

    Você precisa ter acesso ao terminal da sua instância de notebooks gerenciados pelo usuário. O acesso ao terminal é definido manualmente durante a criação de uma instância. Não é possível alterar a configuração de acesso ao terminal após a criação da instância.

    Migrar manualmente usando o Cloud Storage e o terminal

    Para migrar dados e arquivos para uma nova instância do Vertex AI Workbench usando o Cloud Storage e o terminal, siga as etapas a seguir.

    1. Crie um bucket do Cloud Storage no mesmo projeto em que a instância de notebooks gerenciados pelo usuário está localizada.

    2. Nesse mesmo projeto, crie uma instância do Vertex AI Workbench para migrar seus dados. Ao criar essa instância:

      • Ative o acesso ao terminal.
      • Especifique o tipo de máquina, a rede e outras características para corresponder ao que você precisa.

    3. Na interface do JupyterLab da instância gerenciada pelos usuários, selecione File > New > Terminal para abrir uma janela de terminal.

    4. Use a gcloud CLI para copiar os dados do usuário para um bucket do Cloud Storage. O exemplo de comando a seguir copia todos os arquivos do diretório /home/jupyter/ da instância para um diretório em um bucket do Cloud Storage.

      gcloud storage cp /home/jupyter/* gs://BUCKET_NAMEPATH --recursive

      Substitua:

      • BUCKET_NAME: o nome do bucket do Cloud Storage.
      • PATH: o caminho para o diretório em que você quer copiar os arquivos, por exemplo: /copy/jupyter/

    5. Na interface do JupyterLab na nova instância do Vertex AI Workbench, selecione Arquivo > Novo > Terminal para abrir uma janela de terminal.

    6. Use a gcloud CLI para copiar os dados para a nova instância. O comando de exemplo a seguir copia todos os arquivos de um diretório do Cloud Storage para o diretório /home/jupyter/ da sua nova instância.

      gcloud storage cp gs://BUCKET_NAMEPATH* /home/jupyter/ --recursive

    Confirmar a migração

    Após a migração, a instância original de notebooks gerenciados pelo usuário continua a funcionar como antes. Confirme se a migração foi bem-sucedida antes de excluir a instância original.

    Excluir a instância de notebooks gerenciado pelo usuário

    Se você não precisa da instância de notebooks gerenciados pelo usuário da qual migrou, exclua-a para evitar outras cobranças.

    1. No console Google Cloud , acesse a página Notebooks gerenciados pelo usuário.

      Acesse Notebooks gerenciados pelo usuário

    2. Selecione a instância que você quer excluir.

    3. Clique em  Excluir. Dependendo do tamanho da janela, o botão Excluir vai estar no menu "opções" ().

    4. Para confirmar, clique em Excluir.

    Resolver problemas

    Para encontrar métodos para diagnosticar e resolver problemas de migração, consulte Solução de problemas do Vertex AI Workbench.

    A seguir