Crie uma instância com um contentor personalizado

Esta página descreve como criar uma instância do Vertex AI Workbench com base num contentor personalizado.

Vista geral

As instâncias do Vertex AI Workbench suportam a utilização de um contentor personalizado derivado de um dos contentores base fornecidos pela Google. Pode modificar estes contentores base para criar uma imagem de contentor personalizada e usar estes contentores personalizados para criar uma instância do Vertex AI Workbench.

Os contentores de base estão configurados com um SO otimizado para contentores na máquina virtual (VM) do anfitrião. A imagem anfitriã é criada a partir da cos-stable família de imagens.

Limitações

Considere as seguintes limitações ao planear o seu projeto:

  • O contentor personalizado tem de ser derivado de um contentor base fornecido pela Google. A utilização de um contentor que não seja derivado de um contentor base aumenta o risco de problemas de compatibilidade e limita a nossa capacidade de apoiar a sua utilização de instâncias do Vertex AI Workbench.

  • A utilização de mais do que um contentor com uma instância do Vertex AI Workbench não é suportada.

  • Os metadados suportados para contentores personalizados de blocos de notas geridos pelo utilizador e blocos de notas geridos podem ter um comportamento diferente quando usados com instâncias do Vertex AI Workbench.

  • A VM que aloja o contentor personalizado está a ser executada num SO otimizado para contentores, o que restringe a forma como pode interagir com o computador anfitrião. Por exemplo, o SO otimizado para contentores não inclui um gestor de pacotes. Isto significa que os pacotes que atuam no anfitrião têm de ser executados num contentor com montagens. Isto afeta os scripts de pós-inicialização migrados de instâncias de blocos de notas geridas e instâncias de blocos de notas geridas pelo utilizador, em que a máquina anfitriã contém significativamente mais ferramentas do que o SO otimizado para contentores.

  • As instâncias do Vertex AI Workbench usam nerdctl (uma CLI do containerd) para executar o contentor personalizado. Isto é necessário para a compatibilidade com o serviço de streaming de imagens. Todos os parâmetros do contentor adicionados através de um valor de metadados têm de estar em conformidade com o que é suportado pelo nerdctl.

  • As instâncias do Vertex AI Workbench estão configuradas para extrair dados do Artifact Registry ou de um repositório de contentores público. Para configurar uma instância para extrair de um repositório privado, tem de configurar manualmente as credenciais usadas pelo containerd.

Contentores base

Contentor base padrão

O contentor base padrão suporta todas as funcionalidades do Vertex AI Workbench e inclui o seguinte:

Especificações

O contentor de base padrão tem as seguintes especificações:

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

Contentor de base compacta

O contentor base reduzido fornece um conjunto mínimo de configurações que permitem uma ligação de proxy à instância. As funcionalidades e os pacotes do Vertex AI Workbench não estão incluídos, exceto os seguintes:

  • JupyterLab
  • Configuração do JupyterLab baseada em metadados
  • Gestão de kernels baseada no Micromamba

Os pacotes adicionais ou as extensões do JupyterLab têm de ser instalados e geridos de forma independente.

Especificações

O contentor de base simples tem as seguintes especificações:

  • Imagem base: marketplace.gcr.io/google/ubuntu24.04
  • 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.

    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 necessárias

    Para receber as autorizações de que precisa para criar uma instância do Vertex AI Workbench com um contentor personalizado, peça ao seu administrador para lhe conceder as seguintes funções de IAM:

    Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

    Crie um contentor personalizado

    Para criar um contentor personalizado para utilização com instâncias do Vertex AI Workbench:

    1. Crie um contentor derivado de uma imagem de contentor base fornecida pela Google.

    2. Crie e envie o contentor para o Artifact Registry. Vai usar o URI do contentor quando criar a instância do Vertex AI Workbench. Por exemplo, o URI pode ter o seguinte aspeto: gcr.io/PROJECT_ID/IMAGE_NAME.

    Crie a instância

    Pode criar uma instância do Vertex AI Workbench com base num contentor personalizado através da Google Cloud consola ou da CLI Google Cloud.

    Consola

    Para criar uma instância do Vertex AI Workbench com base num contentor personalizado, faça o seguinte:

    1. Na Google Cloud consola, aceda à página Instâncias.

      Aceda a Instâncias

    2. Clique em  Criar novo.

    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 secção Ambiente, selecione Usar contentor personalizado.

    5. Para Imagem do contentor Docker, clique em Selecionar.

    6. Na caixa de diálogo Selecionar imagem do contentor, navegue até à imagem do contentor que quer usar e, de seguida, clique em Selecionar.

    7. Opcional. Para o Script de pós-inicialização, introduza um caminho para um script de pós-inicialização que quer usar.

    8. Opcional. Adicione metadados para a sua instância. Para saber mais, consulte o artigo Metadados do contentor personalizado.

    9. Opcional. Na secção Rede, personalize as definições de rede. Para saber mais, consulte as opções de configuração de rede.

    10. Conclua o resto da caixa de diálogo de criação da instância e, de seguida, clique em Criar.

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

    gcloud

    Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

    • INSTANCE_NAME: o nome da sua instância do Vertex AI Workbench; tem de começar por uma letra seguida de até 62 letras minúsculas, números ou hífenes (-) e não pode terminar com um hífen
    • PROJECT_ID: o ID do seu projeto
    • LOCATION: a zona onde quer que a sua instância esteja localizada
    • CUSTOM_CONTAINER_PATH: o caminho para o repositório de imagens de contentores, por exemplo: gcr.io/PROJECT_ID/IMAGE_NAME
    • METADATA: metadados personalizados a aplicar a esta instância; por exemplo, para especificar um script de pós-arranque, pode usar a etiqueta 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 a partir da linha de comandos, consulte a documentação da CLI gcloud.

    O Vertex AI Workbench cria uma instância e inicia-a automaticamente. Quando a instância estiver pronta a usar, o Vertex AI Workbench ativa um link Abrir JupyterLab na Google Cloud consola.

    Opções de configuração de rede

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

    Se tiver desativado o acesso ao IP público para a sua VPC, certifique-se de que ativou o acesso privado à Google.

    Ative o streaming de imagens

    O anfitrião do contentor personalizado é aprovisionado para interagir com o streaming de imagens no Google Kubernetes Engine (GKE), que extrai contentores mais rapidamente e reduz o tempo de inicialização para contentores grandes assim que são colocados em cache no sistema de ficheiros remoto do GKE.

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

    Ative a API Container File System

    Como a VM anfitriã executa o contentor personalizado

    Em vez de usar o Docker para executar o contentor personalizado, a VM anfitriã usa o nerdctl no espaço de nomes do Kubernetes para carregar e executar o contentor. Isto permite que o Vertex AI Workbench use o streaming de imagens para contentores personalizados.

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

    Exemplo de instalação: contentor personalizado com um kernel predefinido personalizado

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

    1. Crie um novo contentor 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 contentor 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/REPOSITORY_NAME/IMAGE_NAME \
    --container-tag=latest

    Kernels persistentes para contentores personalizados

    Os contentores personalizados do Vertex AI Workbench apenas montam um disco de dados no diretório /home/USER em cada contentor, onde jupyter é o utilizador predefinido. Isto significa que qualquer alteração fora de /home/USER é efémera e não é mantida após um reinício. Se precisar que os pacotes instalados persistam para um kernel específico, pode criar um kernel no diretório /home/USER.

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

    1. Crie um ambiente 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 o seguinte:

      • USER: o nome do diretório do utilizador, que é jupyter por predefinição
      • ENVIRONMENT_NAME: o nome do ambiente
      • PYTHON_VERSION: a versão do Python, por exemplo, 3.11

    2. Aguarde entre 30 segundos e 1 minuto para que os kernels sejam atualizados.

    Atualizar o arranque do contentor base

    O contentor 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 modificar o arranque do contentor num contentor derivado, tem de anexar /run_jupyter.sh para executar a configuração predefinida do JupyterLab.

    Segue-se um exemplo de como o Dockerfile pode ser modificado:

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

CP startup_file.sh /
# Ensure that you have the correct permissions and startup is executable.
RUN chmod 755 /startup_file.sh && \
    chown jupyter:jupyter /startup_file.sh

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

echo "Running startup scripts"
...

/run_jupyter.sh

    Atualizar a configuração do JupyterLab no contentor base

    Se precisar de modificar a configuração do JupyterLab no contentor base, tem de fazer o seguinte:

    • Certifique-se de que o JupyterLab está configurado para a porta 8080. O nosso agente de proxy está configurado para encaminhar qualquer pedido para a porta 8080 e, se o servidor Jupyter não estiver a ouvir a porta correta, a instância encontra problemas de aprovisionamento.

    • Modifique os pacotes do JupyterLab no ambiente jupyterlabmicromamba. Disponibilizamos um ambiente de pacote separado para executar o JupyterLab e o respetivo plug-in para garantir que não existem conflitos de dependências com o ambiente do kernel. Se quiser instalar uma extensão adicional do JupyterLab, tem de a instalar no ambiente jupyterlab. Por exemplo:

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

    Metadados do contentor 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 contentores personalizados incluem os seguintes metadados para gerir a instanciação do contentor de payload:

    Funcionalidade Descrição Chave de metadados Valores aceites e predefinições
    Ativa o FUSE do Cloud Storage numa imagem de contentor

    Monta /dev/fuse no contentor e ativa gcsfuse para utilização no contentor.

    		container-allow-fuse
    • true: ativa o FUSE do Cloud Storage.
    • false (predefinição): não ativa o FUSE do Cloud Storage.
    Parâmetros de execução do contentor adicionais

    Anexa parâmetros de contentor adicionais a nerdctl run, onde nerdctl é a CLI do Containerd.

    		container-custom-params

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

    Flags do ambiente do contentor adicionais

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

    		container-env-file

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

    Atualize um contentor personalizado

    Quando a instância é iniciada pela primeira vez, extrai a imagem do contentor de um URI armazenado nos metadados custom-container-payload. Se usar a etiqueta :latest, o contentor é atualizado a cada reinício. Não é possível modificar diretamente o custom-container-payloadvalor dos metadados porque é uma chave de metadados protegida.

    Para atualizar a imagem do contentor personalizada da sua instância, pode usar os seguintes métodos suportados pela CLI Google Cloud, pelo Terraform ou pela API Notebooks.

    gcloud

    Pode atualizar os metadados da imagem do contentor personalizado numa instância do Vertex AI Workbench através do seguinte comando:

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

    Terraform

    Pode alterar o campo container_image na configuração do Terraform para atualizar a carga útil do contentor.

    Para saber como aplicar ou remover uma configuração do Terraform, consulte os 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 alterações a gce_setup.container_image.repository e gce_setup.container_image.tag no updateMask.

    Execute a ferramenta de diagnóstico

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

    Quando cria uma instância do Vertex AI Workbench com um contentor personalizado, a ferramenta de diagnóstico não está disponível como um script no ambiente de anfitrião que os utilizadores podem executar. Em alternativa, é compilado num ficheiro binário e carregado num contentor de tempo de execução da Google criado para executar serviços de diagnóstico num ambiente do SO otimizado para contentores. Consulte a descrição geral do SO otimizado para contentores.

    Para executar a ferramenta de diagnóstico, conclua os passos seguintes:

    1. Use o SSH para se ligar à sua instância do Vertex AI Workbench.

    2. No terminal SSH, execute o seguinte comando:

      sudo docker exec diagnostic-service ./diagnostic_tool

    3. Para ver opções de comandos adicionais, 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 de monitorização do estado de funcionamento.

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

    Aceda à sua instância

    Pode aceder à sua instância através de um URL de proxy.

    Depois de criar a instância e esta estar ativa, pode obter o URL do proxy através da CLI gcloud.

    Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

    • INSTANCE_NAME: o nome da sua instância do Vertex AI Workbench
    • PROJECT_ID: o ID do seu projeto
    • LOCATION: a zona onde a sua 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 devolve o URL de proxy. Para aceder à instância, abra o URL do proxy num navegador de Internet.

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