Migrar de notebooks gerenciados para instâncias do Vertex AI Workbench

Migrar de notebooks gerenciados para instâncias do Vertex AI Workbench

Os notebooks gerenciados do Vertex AI Workbench foram descontinuados. Em 30 de janeiro de 2025, o suporte a notebooks gerenciados será encerrado, e não será mais possível criar instâncias de notebooks gerenciados. 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, conclua as etapas nesta página para migrar suas instâncias de notebooks gerenciados para instâncias do Vertex AI Workbench.

Nesta página, descrevemos como migrar de uma instância de notebooks gerenciados 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 oferece uma ferramenta de migração para migrar de uma instância de notebooks gerenciados 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 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 são copiados para a instância do Vertex AI Workbench.

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

Faturamento

Se a instância de notebooks gerenciados usar discos permanentes extremos, sua migração gerará cobranças para operações de E/S. Consulte "IOPS provisionadas extremas" no relatório Seção de preços de discos permanentes e hiperdiscos do preço de discos de dois minutos.

Após a migração, a instância de notebooks gerenciados continuará existindo e gerando cobranças como antes. Se você não precisar mais da instância de notebooks gerenciados, 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 para uma instância do Vertex AI Workbench com especificações correspondentes. Quando uma especificação na instância de notebooks gerenciados 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 pode migrar uma especificação da instância de notebooks gerenciados, ela não é 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	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 por inatividade	Migrada
	Excluir para a lixeira	Migrada
	nbconvert	Migrada
	Permitir downloads do arquivo	Migrada
	Acesso ao terminal	Migrada
Outros	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; instâncias que usam o modo de acesso JupyterLab de usuário único precisam especificar a opção serviceAccount
	Rede	Migrado; instâncias que usam uma nuvem privada virtual gerenciada pelo Google precisam especificar as opções network e subnet
	Script pós-inicialização	Ao usar o console do Google Cloud, a instância é migrada sem o script pós-inicialização. Para migrar a instância com esse script, use a CLI do Google Cloud ou a API REST para especificar a opção PostStartupScriptOption.
	Dataproc Hub	Não migrado. precisam migrar manualmente

Especificar opções

As seções a seguir descrevem casos em que é necessário especificar uma opção para migrar sua instância de notebooks gerenciados para uma instância do Vertex AI Workbench.

Instâncias que usam o modo de acesso de usuário único

As instâncias de notebooks gerenciados que usam o modo de acesso de usuário único precisam ser migradas para uma instância com a opção serviceAccount especificada. A instância do Vertex AI Workbench que você migra restringe o acesso ao JupyterLab para o único usuário, mas usa uma conta de serviço para interagir com os serviços e as APIs do Google Cloud.

Instâncias que usam uma VPC gerenciada pelo Google

As instâncias de notebooks gerenciados que usam uma VPC gerenciada pelo Google precisam ser migradas para uma instância com as opções network e subnet especificadas. A opção de usar uma VPC gerenciada pelo Google não é compatível com instâncias do Vertex AI Workbench, portanto, é necessário especificar uma rede diferente.

Instâncias que usam um script pós-inicialização

As instâncias de notebooks gerenciados 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 a instância de notebooks gerenciados, use a CLI do Google Cloud ou a API REST.

Antes de começar

1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

2. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

4. Ative a API Notebooks.

   Ative a API

5. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

6. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

7. Ative a API Notebooks.

   Ative a API

8. Crie uma instância de notebook gerenciado se ainda não tiver feito isso.

Funções exigidas

Para garantir que sua conta de usuário tenha as permissões necessárias para migrar uma instância de notebooks gerenciados para uma instância do Vertex AI Workbench, peça ao administrador para conceder à sua conta de usuário o Papel do IAM de executor de notebooks (roles/notebooks.runner) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém as permissões necessárias para migrar uma instância de notebooks gerenciados 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 para uma instância do Vertex AI Workbench:

• notebooks.runtimes.create
• notebooks.runtimes.get

O administrador também pode conceder à conta de serviço essas permissões com papéis personalizados 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. 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 que ainda não foram migradas, use o método projects.locations.runtimes.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 está localizada, ou use - para listar as instâncias de todas as regiões

Execute o este comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud notebooks runtimes 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 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/runtimes?filter=migrated:false

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

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

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/runtimes?filter=migrated:false"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

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/runtimes?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.runtimes.list vai incluir essas informações.

Os avisos aparecem quando componentes específicos na configuração da instância dos notebooks gerenciados 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 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 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 RuntimeMigrationEligibility.

Migrar usando a ferramenta de migração

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

Console

1. No Console do Google Cloud, acesse a página Notebooks gerenciados.

   Acessar notebooks gerenciados

2. Clique no botão Migrar. A página Migrar notebooks gerenciados para instâncias abre.

3. Para migrar instâncias que não precisam de opções especificadas, clique na guia Pronto, selecione as instâncias que você quer migrar e clique em Migrar.

4. Para migrar instâncias que precisam de opções especificadas, clique na guia Precisa de entrada, selecione as instâncias que você quer migrar e clique em Migrar.

   1. Na caixa de diálogo Inserir entrada para migração, especifique uma rede e conta de serviço a serem usadas nas novas instâncias do Vertex AI Workbench que você selecionou.

   2. Clique em Enviar.

5. Depois que as migrações forem concluídas, acesse a página Instâncias para ver as novas instâncias 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 está localizada
• RUNTIME_ID: o ID da instância de notebooks gerenciados
• NETWORK: opcional: a rede para onde você quer migrar a instância
• SUBNET: opcional: a sub-rede para onde você quer migrar a instância
• SERVICE_ACCOUNT: (opcional) o endereço de e-mail da conta de serviço que você quer usar
• POST_STARTUP_SCRIPT_OPTION: opcional: uma das opções de script pós-inicialização

Execute o este comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud notebooks runtimes migrate RUNTIME_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --network=NETWORK \
    --subnet=SUBNET \
    --service-account=SERVICE_ACCOUNT \
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud notebooks runtimes migrate RUNTIME_ID `
    --project=PROJECT_ID `
    --location=LOCATION `
    --network=NETWORK `
    --subnet=SUBNET `
    --service-account=SERVICE_ACCOUNT `
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud notebooks runtimes migrate RUNTIME_ID ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --network=NETWORK ^
    --subnet=SUBNET ^
    --service-account=SERVICE_ACCOUNT ^
    --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 está localizada
• RUNTIME_ID: o ID da instância de notebooks gerenciados
• NETWORK: opcional: a rede para onde você quer migrar a instância
• SUBNET: opcional: a sub-rede para onde você quer migrar a instância
• SERVICE_ACCOUNT: (opcional) o endereço de e-mail da conta de serviço que você quer usar
• 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/runtimes/RUNTIME_ID:migrate

Corpo JSON da solicitação:

{
  "network": NETWORK,
  "subnet": SUBNET,
  "serviceAccount": SERVICE_ACCOUNT_EMAIL_ADDRESS,
  "postStartupScriptOption": (POST_STARTUP_SCRIPT_OPTION)
}

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

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

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

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/runtimes/RUNTIME_ID:migrate"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

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/runtimes/RUNTIME_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 para a instância de notebooks gerenciados. 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 o gsutil tool 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.

   gsutil cp -R /home/jupyter/* gs://BUCKET_NAMEPATH
   

   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 o gsutil tool 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.

   gsutil cp gs://BUCKET_NAMEPATH* /home/jupyter/
   

Confirmar a migração

Após a migração, a instância original de notebooks gerenciados 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 gerenciados

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

1. No Console do Google Cloud, acesse a página Notebooks gerenciados.

   Acessar Notebooks gerenciados

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

• Saiba mais sobre o Vertex AI Workbench.