Criar uma instância usando um contêiner personalizado

Esta página descreve como criar uma instância do Vertex AI Workbench com base em um contêiner personalizado.

Visão geral

As instâncias do Vertex AI Workbench aceitam o uso de um contêiner personalizado derivado de um dos contêineres base fornecidos pelo Google. Você pode modificar esses contêineres base para criar uma imagem de contêiner personalizada e usar esses contêineres personalizados para criar uma instância do Vertex AI Workbench.

Os contêineres base são configurados com um Container-Optimized OS na máquina virtual host. A imagem do host é criada a partir da família de imagens cos-stable.

Limitações

Considere as seguintes limitações ao planejar seu projeto:

  • O contêiner personalizado precisa ser derivado de um contêiner base fornecido pelo Google. O uso de um contêiner que não é derivado de um contêiner base aumenta o risco de problemas de compatibilidade e limita nossa capacidade de oferecer suporte ao uso de instâncias do Vertex AI Workbench.

  • Não há suporte para o uso de mais de um contêiner com uma instância do Vertex AI Workbench.

  • Os metadados compatíveis para contêineres personalizados de notebooks gerenciados pelo usuário e notebooks gerenciados podem ter comportamentos diferentes quando usados com instâncias do Vertex AI Workbench.

  • A VM que hospeda o contêiner personalizado está sendo executada em um sistema operacional otimizado para contêineres, o que restringe como você pode interagir com a máquina host. Por exemplo, o Container-Optimized OS não inclui um gerenciador de pacotes. Isso significa que os pacotes que atuam no host precisam ser executados em um contêiner com montagens. Isso afeta os scripts pós-inicialização que são migrados de instâncias de notebooks gerenciadas e instâncias de notebooks gerenciadas pelo usuário, em que a máquina host contém muito mais ferramentas do que o SO otimizado para contêineres.

  • As instâncias do Vertex AI Workbench usam nerdctl (uma CLI containerd) para executar o contêiner personalizado. Isso é necessário para compatibilidade com o serviço de streaming de imagens. Todos os parâmetros do contêiner adicionados usando um valor de metadados precisam aderir ao que é aceito por nerdctl.

  • As instâncias do Vertex AI Workbench são configuradas para extrair dados do Artifact Registry ou de um repositório de contêineres público. Para configurar uma instância para extrair de um repositório particular, é necessário configurar manualmente as credenciais usadas pelo containerd.

Contêineres de base

Contêiner de base padrão

O contêiner de base padrão oferece suporte a todos os recursos do Vertex AI Workbench e inclui o seguinte:

Especificações

O contêiner de base padrão tem as seguintes especificações:

  • Imagem de base: nvidia/cuda:12.6.1-cudnn-devel-ubuntu22.04
  • Tamanho da imagem: aproximadamente 22 GB
  • URI: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

Contêiner de base fino

O contêiner de base fino fornece um conjunto mínimo de configurações que permitem uma conexão de proxy à instância. Os recursos e pacotes padrão do Vertex AI Workbench não estão incluídos, exceto:

  • JupyterLab
  • Configuração do JupyterLab baseada em metadados
  • Gerenciamento de kernel baseado em Micromamba

Pacotes adicionais ou extensões do JupyterLab precisam ser instalados e gerenciados de forma independente.

Especificações

O contêiner de base fino tem as seguintes especificações:

  • Imagem de base: marketplace.gcr.io/google/ubuntu22041
  • Tamanho da imagem: aproximadamente 2 GB
  • URI: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest

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.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Notebooks API.

    Enable the API

    5.

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

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Notebooks API.

    Enable the API

    8.

Funções exigidas

Para receber as permissões necessárias para criar uma instância do Vertex AI Workbench com um contêiner personalizado, peça ao administrador para conceder a você os seguintes papéis do IAM:

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

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Criar um contêiner personalizado

Para criar um contêiner personalizado para uso com instâncias do Vertex AI Workbench:

  1. Crie um contêiner derivado de uma imagem de contêiner base fornecida pelo Google.

  2. Crie e envie o contêiner para o Artifact Registry. Você vai usar o URI do contêiner ao criar sua instância do Vertex AI Workbench. Por exemplo, o URI pode ser parecido com este: gcr.io/PROJECT_ID/IMAGE_NAME.

Criar instância

É possível criar uma instância do Vertex AI Workbench com base em um contêiner personalizado usando o console do Google Cloud ou a CLI do Google Cloud.

Console

Para criar uma instância do Vertex AI Workbench com base em um contêiner personalizado, faça o seguinte:

  1. No console do Google Cloud, acesse a página Instâncias.

    Acesse "Instâncias"

  2. Clique em Criar.

  3. Na caixa de diálogo Nova instância, clique em Opções avançadas.

  4. Na caixa de diálogo Criar instância, na seção Ambiente, selecione Usar contêiner personalizado.

  5. Em Imagem do contêiner do Docker, clique em Selecionar.

  6. Na caixa de diálogo Selecionar imagem do contêiner, acesse a imagem do contêiner que você quer usar e clique em Selecionar.

  7. Opcional. Em Script pós-inicialização, insira um caminho para um script pós-inicialização que você quer usar.

  8. Opcional. Adicione metadados à sua instância. Para saber mais, consulte Metadados de contêineres personalizados.

  9. Opcional. Na seção "Rede", personalize as configurações de rede. Para saber mais, consulte Opções de configuração de rede.

  10. Preencha o restante da caixa de diálogo de criação de instância e clique em Criar.

    O Vertex AI Workbench cria uma instância e a inicia automaticamente. Quando a instância estiver pronta para uso, o Vertex AI Workbench ativa um link Abrir JupyterLab.

gcloud

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

  • INSTANCE_NAME: o nome da sua instância do Vertex AI Workbench. Precisa começar com uma letra seguida por até 62 letras minúsculas, números ou hifens (-) e não pode terminar com um hífen.
  • PROJECT_ID: ID do projeto;
  • LOCATION: a zona em que você quer que a instância esteja localizada
  • CUSTOM_CONTAINER_PATH: o caminho para o repositório de imagens do contêiner, por exemplo: gcr.io/PROJECT_ID/IMAGE_NAME
  • METADATA: metadados personalizados a serem aplicados a esta instância. Por exemplo, para especificar um script pós-inicialização, use a tag de metadados post-startup-script no formato: "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud workbench instances create INSTANCE_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --container-repository=CUSTOM_CONTAINER_URL \
    --container-tag=latest \
    --metadata=METADATA

Windows (PowerShell)

gcloud workbench instances create INSTANCE_NAME `
    --project=PROJECT_ID `
    --location=LOCATION `
    --container-repository=CUSTOM_CONTAINER_URL `
    --container-tag=latest `
    --metadata=METADATA

Windows (cmd.exe)

gcloud workbench instances create INSTANCE_NAME ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --container-repository=CUSTOM_CONTAINER_URL ^
    --container-tag=latest ^
    --metadata=METADATA

Para mais informações sobre o comando para criar uma instância usando a linha de comando, consulte a documentação da CLI gcloud.

O Vertex AI Workbench cria uma instância e a inicia automaticamente. Quando a instância estiver pronta para uso, o Vertex AI Workbench ativa um link Abrir JupyterLab no console do Google Cloud.

Opções de configuração de rede

Além das opções gerais de rede, uma instância do Vertex AI Workbench com um contêiner personalizado precisa ter acesso ao serviço do Artifact Registry.

Se você desativou o acesso de IP público para sua VPC, verifique se ativou o Acesso privado do Google.

Ativar o streaming de imagens

O host de contêiner personalizado é provisionado para interagir com o streaming de imagens no Google Kubernetes Engine (GKE), que extrai contêineres mais rapidamente e reduz o tempo de inicialização de contêineres grandes depois que eles são armazenados em cache no sistema de arquivos remoto do GKE.

Para conferir os requisitos para ativar o streaming de imagens, consulte Requisitos. Muitas vezes, o streaming de imagens pode ser usado com instâncias do Vertex AI Workbench ativando a API Container File System.

Ativar a API Container File System

Como a VM do host executa o contêiner personalizado

Em vez de usar o Docker para executar o contêiner personalizado, a VM de host usa nerdctl no namespace do Kubernetes para carregar e executar o contêiner. Isso permite que o Vertex AI Workbench use o streaming de imagens para contêineres personalizados.

# Runs the custom container.
sudo /var/lib/google/nerdctl/nerdctl --snapshotter=gcfs -n k8s.io run --name payload-container

Exemplo de instalação: contêiner personalizado com um kernel padrão personalizado

O exemplo a seguir mostra como criar um novo kernel com um pacote pip pré-instalado.

  1. Crie um contêiner personalizado:

    FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

ENV MAMBA_ROOT_PREFIX=/opt/micromamba

RUN micromamba create -n ENVIRONMENT_NAME -c conda-forge python=PYTHON_VERSION -y

SHELL ["micromamba", "run", "-n", "ENVIRONMENT_NAME", "/bin/bash", "-c"]

RUN micromamba install -c conda-forge pip -y
RUN pip install PACKAGE
RUN pip install ipykernel
RUN python -m ipykernel install --prefix /opt/micromamba/envs/ENVIRONMENT_NAME --name ENVIRONMENT_NAME --display-name KERNEL_NAME
# Creation of a micromamba kernel automatically creates a python3 kernel
# that must be removed if it's in conflict with the new kernel.
RUN rm -rf "/opt/micromamba/envs/ENVIRONMENT_NAME/share/jupyter/kernels/python3"

  2. Adicione o novo contêiner ao Artifact Registry:

    gcloud auth configure-docker REGION-docker.pkg.dev
docker build -t REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME .
docker push REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest

  3. Crie uma instância:

    gcloud workbench instances create INSTANCE_NAME  \
    --project=PROJECT_ID \
    --location=ZONE \
    --container-repository=REGION-docker.pkg.dev/PROJECT_ID/IMAGE_NAME \
    --container-tag=latest

Kernels persistentes para contêineres personalizados

Os contêineres personalizados do Vertex AI Workbench montam um disco de dados no diretório /home/USER de cada contêiner, em que jupyter é o usuário padrão. Isso significa que qualquer mudança fora de /home/USER é temporária e não persiste após uma reinicialização. Se você precisar que os pacotes instalados persistam para um kernel específico, crie um kernel no diretório /home/USER.

Para criar um kernel no diretório /home/USER:

  1. Crie um ambiente da micromamba:

    micromamba create -p /home/USER/ENVIRONMENT_NAME -c conda-forge python=3.11 -y
micromamba activate /home/USER/ENVIRONMENT_NAME
pip install ipykernel
pip install -r ~/requirement.txt
python -m ipykernel install --prefix "/home/USER/ENVIRONMENT_NAME" --display-name "Example Kernel"

    Substitua:

    • USER: o nome do diretório do usuário, que é jupyter por padrão
    • ENVIRONMENT_NAME: o nome do ambiente
    • PYTHON_VERSION: a versão do Python, por exemplo, 3.11

  2. Aguarde de 30 segundos a 1 minuto para que os kernels sejam atualizados.

Como atualizar a inicialização do contêiner base

O contêiner base de uma instância do Vertex AI Workbench (us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest) inicia o JupyterLab executando /run_jupyter.sh.

Se você modificar a inicialização do contêiner em um contêiner derivado, será necessário anexar /run_jupyter.sh para executar a configuração padrão do JupyterLab.

Confira a seguir um exemplo de como o Dockerfile pode ser modificado:

# DockerFile
FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

# Override the existing CMD directive from the base container.
CMD ["/startup_file.sh"]
 
# /startup_file.sh

echo "Running startup scripts"
...

/run_jupyter.sh

Como atualizar a configuração do JupyterLab no contêiner base

Se você precisar modificar a configuração do JupyterLab no contêiner base, faça o seguinte:

  • Verifique se o JupyterLab está configurado para a porta 8080. Nosso agente de proxy está configurado para encaminhar qualquer solicitação à porta 8080. Se o servidor Jupyter não estiver detectando a porta correta, a instância vai encontrar problemas de provisionamento.

  • Modifique os pacotes do JupyterLab no ambiente jupyterlab micromamba. Fornecemos um ambiente de pacote separado para executar o JupyterLab e o plug-in dele, garantindo que não haja conflitos de dependência com o ambiente do kernel. Se você quiser instalar outra extensão do JupyterLab, faça isso no ambiente jupyterlab. Exemplo:

    # DockerFile
FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
RUN micromamba activate jupyterlab && \
  jupyter nbextension install nbdime

Metadados de contêiner personalizados

Além da lista padrão de metadados que podem ser aplicados a uma instância do Vertex AI Workbench, as instâncias com contêineres personalizados incluem os seguintes metadados para gerenciar a instanciação do contêiner de payload:

Recurso Descrição Chave de metadados Valores e padrões aceitos
Ativa o Cloud Storage FUSE em uma imagem de contêiner

Monta /dev/fuse no contêiner e ativa gcsfuse para uso no contêiner.

container-allow-fuse
  • true: ativa o Cloud Storage FUSE.
  • false (padrão): não ativa o Cloud Storage FUSE.
Outros parâmetros de execução do contêiner

Adiciona outros parâmetros de contêiner a nerdctl run, em que nerdctl é a CLI do Containerd.

container-custom-params

Uma string de parâmetros de execução do contêiner. Exemplo: --v /mnt/disk1:/mnt/disk1.

Outras flags do ambiente do contêiner

Armazena variáveis de ambiente em uma flag em /mnt/stateful_partition/workbench/container_env e as anexa a nerdctl run.

container-env-file

Uma string de variáveis de ambiente do contêiner. Exemplo: CONTAINER_NAME=derivative-container.

Fazer upgrade de um contêiner personalizado

Quando a instância é iniciada pela primeira vez, ela extrai a imagem do contêiner de um URI armazenado nos metadados custom-container-payload. Se você usar a tag :latest, o contêiner será atualizado a cada reinicialização. O valor de metadados custom-container-payload não pode ser modificado diretamente porque é uma chave de metadados protegida.

Para atualizar a imagem do contêiner personalizado da sua instância, use os métodos abaixo, com suporte da CLI do Google Cloud, do Terraform ou da API Notebooks.

gcloud

É possível atualizar os metadados da imagem do contêiner personalizado em uma instância do Vertex AI Workbench usando o comando a seguir:

gcloud workbench instances update INSTANCE_NAME \
    --container-repository=CONTAINER_URI \
    --container-tag=CONTAINER_TAG

Terraform

É possível mudar o campo container_image na configuração do Terraform para atualizar o payload do contêiner.

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

resource "google_workbench_instance" "default" {
  name     = "workbench-instance-example"
  location = "us-central1-a"

  gce_setup {
    machine_type = "n1-standard-1"
    container_image {
      repository = "us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container"
      family  = "latest"
    }
  }
}

API Notebooks

Use o método instances.patch com mudanças em gce_setup.container_image.repository e gce_setup.container_image.tag no updateMask.

Executar a ferramenta de diagnóstico

A ferramenta de diagnóstico verifica o status de vários serviços do Vertex AI Workbench. Para saber mais, consulte Tarefas realizadas pela ferramenta de diagnóstico.

Quando você cria uma instância do Vertex AI Workbench usando um contêiner personalizado, a ferramenta de diagnóstico não está disponível como um script no ambiente do host que os usuários podem executar. Em vez disso, ele é compilado em um binário e carregado em um contêiner de execução do Google criado para executar serviços de diagnóstico em um ambiente do Container-Optimized OS. Consulte a Visão geral do Container-Optimized OS.

Para executar a ferramenta de diagnóstico, siga estas etapas:

  1. Use ssh para se conectar à sua instância do Vertex AI Workbench.

  2. No terminal SSH, execute o seguinte comando:

    sudo docker exec diagnostic-service ./diagnostic_tool

  3. Para conferir outras opções de comando, execute o seguinte comando:

    sudo docker exec diagnostic-service ./diagnostic_tool --help

Para mais informações sobre as opções da ferramenta de diagnóstico, consulte a documentação sobre o status de integridade do monitoramento.

Para executar a ferramenta de diagnóstico usando a API REST, consulte a documentação da API REST.

Acessar a instância

Você pode acessar sua instância por meio de um URL proxy.

Depois que sua instância for criada e estiver ativa, você poderá obter o URL do proxy usando a CLI gcloud.

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

  • INSTANCE_NAME: o nome da sua instância do Vertex AI Workbench.
  • PROJECT_ID: ID do projeto
  • LOCATION: a zona em que a instância está localizada

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud workbench instances describe INSTANCE_NAME \
--project=PROJECT_ID \
--location=LOCATION | grep proxy-url

Windows (PowerShell)

gcloud workbench instances describe INSTANCE_NAME `
--project=PROJECT_ID `
--location=LOCATION | grep proxy-url

Windows (cmd.exe)

gcloud workbench instances describe INSTANCE_NAME ^
--project=PROJECT_ID ^
--location=LOCATION | grep proxy-url
 
proxy-url: 7109d1b0d5f850f-dot-datalab-vm-staging.googleusercontent.com

O comando describe retorna seu URL de proxy. Para acessar sua instância, abra o URL do proxy em um navegador da web.

Para mais informações sobre o comando para descrever uma instância usando a linha de comando, consulte a documentação da CLI gcloud.