Creazione di un'istanza utilizzando un container personalizzato

Questa pagina descrive come creare un'istanza di Vertex AI Workbench basata su un contenitore personalizzato.

Panoramica

Le istanze Vertex AI Workbench supportano l'utilizzo di un container personalizzato derivato da uno dei container di base forniti da Google. Puoi modificare questi container di base per creare un'immagine container personalizzata e utilizzare questi container personalizzati per creare un'istanza di Vertex AI Workbench.

I container di base sono configurati con un Container-Optimized OS nella macchina virtuale (VM) host. L'immagine host è creata a partire dalla cos-stable famiglia di immagini.

Limitazioni

Quando pianifichi il tuo progetto, tieni presente le seguenti limitazioni:

• Il container personalizzato deve essere derivato da un container di base fornito da Google. L'utilizzo di un container non derivato da un container di base aumenta il rischio di problemi di compatibilità e limita la nostra capacità di supportare l'utilizzo delle istanze di Vertex AI Workbench.

• L'utilizzo di più di un container con un'istanza Vertex AI Workbench non è supportato.

• I metadati supportati per i container personalizzati dei notebook gestiti dall'utente e dei notebook gestiti possono avere un comportamento diverso se utilizzati con le istanze Vertex AI Workbench.

• La VM che ospita il container personalizzato viene eseguita su Container-Optimized OS, che limita il modo in cui puoi interagire con la macchina host. Ad esempio, Container-Optimized OS non include un gestore di pacchetti. Ciò significa che i pacchetti che agiscono sull'host devono essere eseguiti su un container con montaggi. Ciò influisce sugli script post-avvio di cui viene eseguita la migrazione dalle istanze di notebook gestiti e dalle istanze di notebook gestiti dall'utente, in cui la macchina host contiene molti più strumenti rispetto a Container-Optimized OS.

• Le istanze Vertex AI Workbench utilizzano nerdctl (un'interfaccia a riga di comando containerd) per l'esecuzione del container personalizzato. Questo è necessario per la compatibilità con il servizio di streaming delle immagini. Tutti i parametri del contenitore aggiunti utilizzando un valore dei metadati devono rispettare ciò che è supportato da nerdctl.

• Le istanze Vertex AI Workbench sono configurate per eseguire il pull da Artifact Registry o da un repository di container pubblico. Per configurare un'istanza in modo che estragga da un repository privato, devi configurare manualmente le credenziali utilizzate da containerd.

Container di base

Prima di iniziare

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.

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

Go to project selector

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

Enable the Notebooks API.

Enable the API

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

Go to project selector

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

Enable the Notebooks API.

Enable the API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare un'istanza Vertex AI Workbench con un container personalizzato, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Notebooks Runner (roles/notebooks.runner) sull'account utente
• Per eseguire il pull delle immagini dal repository Artifact Registry: Lettore Artifact Registry (roles/artifactregistry.reader) sul account di servizio

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Creazione di un container personalizzato

Per creare un contenitore personalizzato da utilizzare con le istanze Vertex AI Workbench:

1. Crea un container derivato da un'immagine container di base fornita da Google.

2. Crea ed esegui il push del container in Artifact Registry. Utilizzerai l'URI del container quando crei l'istanza Vertex AI Workbench. Ad esempio, l'URI potrebbe avere il seguente aspetto: gcr.io/PROJECT_ID/IMAGE_NAME.

Crea l'istanza

Puoi creare un'istanza Vertex AI Workbench basata su un container personalizzato utilizzando la console Google Cloud o Google Cloud CLI.

Console

Per creare un'istanza di Vertex AI Workbench basata su un container personalizzato, svolgi i seguenti passaggi:

1. Nella console Google Cloud , vai alla pagina Istanze.

   Vai a Istanze

2. Fai clic su add_box Crea nuova.

3. Nella finestra di dialogo Nuova istanza, fai clic su Opzioni avanzate.

4. Nella finestra di dialogo Crea istanza, nella sezione Ambiente, seleziona Usa contenitore personalizzato.

5. Per Immagine container Docker, fai clic su Seleziona.

6. Nella finestra di dialogo Seleziona immagine container, vai all'immagine container che vuoi utilizzare, quindi fai clic su Seleziona.

7. Facoltativo. Per Script post-avvio, inserisci un percorso a uno script post-avvio che vuoi utilizzare.

8. Facoltativo. Aggiungi metadati per l'istanza. Per saperne di più, consulta Metadati personalizzati del contenitore.

9. Facoltativo. Nella sezione Networking, personalizza le impostazioni di rete. Per saperne di più, consulta Opzioni di configurazione di rete.

10. Completa il resto della finestra di dialogo di creazione dell'istanza e poi fai clic su Crea.

    Vertex AI Workbench crea un'istanza e la avvia automaticamente. Quando l'istanza è pronta per l'uso, Vertex AI Workbench attiva un link Apri JupyterLab.

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, apporta le seguenti sostituzioni:

• INSTANCE_NAME: il nome dell'istanza Vertex AI Workbench; deve iniziare con una lettera seguita da un massimo di 62 lettere minuscole, numeri o trattini (-) e non può terminare con un trattino
• PROJECT_ID: il tuo ID progetto
• LOCATION: la zona in cui vuoi che si trovi l'istanza
• CUSTOM_CONTAINER_PATH: il percorso del repository dell'immagine container, ad esempio: gcr.io/PROJECT_ID/IMAGE_NAME
• METADATA: metadati personalizzati da applicare a questa istanza; ad esempio, per specificare uno script post-startup, puoi utilizzare il tag di metadati post-startup-script nel formato: "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"

Esegui questo comando:

Linux, macOS o 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

Per ulteriori informazioni sul comando per creare un'istanza dalla riga di comando, consulta la documentazione della CLI gcloud.

Vertex AI Workbench crea un'istanza e la avvia automaticamente. Quando l'istanza è pronta per l'uso, Vertex AI Workbench attiva un link Apri JupyterLab nella console Google Cloud .

Opzioni di configurazione di rete

Oltre alle opzioni di rete generali, un'istanza di Vertex AI Workbench con un container personalizzato deve avere accesso al servizio Artifact Registry.

Se hai disattivato l'accesso IP pubblico per il tuo VPC, assicurati di aver abilitato l'accesso privato Google.

Abilita flusso immagine

L'host container personalizzato viene sottoposto a provisioning per interagire con lo streaming di immagini in Google Kubernetes Engine (GKE), che estrae i container più velocemente e riduce il tempo di inizializzazione per i container di grandi dimensioni una volta memorizzati nella cache nel file system remoto GKE.

Per visualizzare i requisiti per l'attivazione dello streaming di immagini, consulta Requisiti. Spesso, lo streaming di immagini può essere utilizzato con le istanze di Vertex AI Workbench attivando l'API Container File System.

Abilita l'API Container File System

Come la VM host esegue il container personalizzato

Anziché utilizzare Docker per eseguire il container personalizzato, la VM host utilizza nerdctl nello spazio dei nomi Kubernetes per caricare ed eseguire il container. In questo modo, Vertex AI Workbench può utilizzare lo streaming di immagini per i container personalizzati.

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

Installazione di esempio: container personalizzato con un kernel predefinito personalizzato

Il seguente esempio mostra come creare un nuovo kernel con un pacchetto pip preinstallato.

1. Crea un nuovo container personalizzato:

   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. Aggiungi il nuovo contenitore ad 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. Crea un'istanza:

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

Kernel persistenti per container personalizzati

I contenitori personalizzati di Vertex AI Workbench montano solo un disco di dati nella directory /home/USER all'interno di ogni contenitore, dove jupyter è l'utente predefinito. Ciò significa che qualsiasi modifica al di fuori di /home/USER è temporanea e non verrà mantenuta dopo un riavvio. Se vuoi che i pacchetti installati vengano mantenuti per un kernel specifico, puoi creare un kernel nella directory /home/USER.

Per creare un kernel nella directory /home/USER:

1. Crea un 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"

   Sostituisci quanto segue:

   • USER: il nome della directory utente, che per impostazione predefinita è jupyter
   • ENVIRONMENT_NAME: il nome dell'ambiente
   • PYTHON_VERSION: la versione di Python, ad esempio 3.11

2. Attendi da 30 secondi a 1 minuto affinché i kernel si aggiornino.

Aggiornamento dell'avvio del container di base

Il container di base per un'istanza di Vertex AI Workbench (us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest) avvia JupyterLab eseguendo /run_jupyter.sh.

Se modifichi l'avvio del container in un container derivato, devi aggiungere /run_jupyter.sh per eseguire la configurazione predefinita di JupyterLab.

Di seguito è riportato un esempio di come potrebbe essere modificato il Dockerfile:

# 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

Aggiornamento della configurazione di JupyterLab all'interno del container di base

Se devi modificare la configurazione di JupyterLab nel container di base, devi procedere nel seguente modo:

• Assicurati che JupyterLab sia configurato per la porta 8080. Il nostro agente proxy è configurato per inoltrare qualsiasi richiesta alla porta 8080 e se il server Jupyter non è in ascolto sulla porta corretta, l'istanza riscontra problemi di provisioning.

• Modifica i pacchetti JupyterLab nell'ambiente jupyterlab micromamba. Forniamo un ambiente di pacchetti separato per eseguire JupyterLab e il relativo plug-in per garantire che non vi siano conflitti di dipendenze con l'ambiente del kernel. Se vuoi installare un'estensione JupyterLab aggiuntiva, devi installarla nell'ambiente jupyterlab. Ad esempio:

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

Metadati del container personalizzati

Oltre all'elenco standard di metadati che possono essere applicati a un'istanza Vertex AI Workbench, le istanze con container personalizzati includono i seguenti metadati per la gestione dell'istanza del container di payload:

Funzionalità	Descrizione	Chiave dei metadati	Valori accettati e predefiniti
Abilita Cloud Storage FUSE su un'immagine container	Monta /dev/fuse sul container e attiva gcsfuse per l'utilizzo sul container.	container-allow-fuse	true: attiva Cloud Storage FUSE. false (impostazione predefinita): non abilita Cloud Storage FUSE.
Parametri di esecuzione del container aggiuntivi	Aggiunge parametri del container aggiuntivi a nerdctl run, dove nerdctl è la CLI Containerd.	container-custom-params	Una stringa di parametri di esecuzione del container. Esempio: --v /mnt/disk1:/mnt/disk1.
Flag aggiuntivi per l'ambiente dei container	Memorizza le variabili di ambiente in un flag in /mnt/stateful_partition/workbench/container_env e lo aggiunge a nerdctl run.	container-env-file	Una stringa di variabili di ambiente del container. Esempio: CONTAINER_NAME=derivative-container.

Eseguire l'upgrade di un container personalizzato

Quando l'istanza viene avviata per la prima volta, recupera l'immagine container da un URI archiviato nei metadati custom-container-payload. Se utilizzi il tag :latest, il container viene aggiornato a ogni riavvio. Il valore dei metadati custom-container-payload non può essere modificato direttamente perché è una chiave di metadati protetta.

Per aggiornare l'immagine container personalizzata dell'istanza, puoi utilizzare i seguenti metodi supportati da Google Cloud CLI, Terraform o dall'API Notebooks.

gcloud

Puoi aggiornare i metadati dell'immagine container personalizzata su un'istanza di Vertex AI Workbench utilizzando il seguente comando:

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

Terraform

Puoi modificare il campo container_image nella configurazione di Terraform per aggiornare il payload del container.

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base.

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

Utilizza il metodo instances.patch con modifiche a gce_setup.container_image.repository e gce_setup.container_image.tag in updateMask.

Esegui lo strumento di diagnostica

Lo strumento di diagnostica controlla e verifica lo stato di vari servizi Vertex AI Workbench. Per saperne di più, vedi Attività eseguite dallo strumento di diagnostica.

Quando crei un'istanza di Vertex AI Workbench utilizzando un container personalizzato, lo strumento di diagnostica non è disponibile come script nell'ambiente host che gli utenti possono eseguire. Viene invece compilato in un file binario e caricato in un container runtime Google creato per eseguire servizi di diagnostica in un ambiente Container-Optimized OS. Consulta la panoramica di Container-Optimized OS.

Per eseguire lo strumento di diagnostica, completa i seguenti passaggi:

1. Utilizza SSH per connetterti all'istanza di Vertex AI Workbench.

2. Nel terminale SSH, esegui il seguente comando:

   sudo docker exec diagnostic-service ./diagnostic_tool

3. Per visualizzare altre opzioni di comando, esegui questo comando:

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

Per saperne di più sulle opzioni dello strumento di diagnostica, consulta la documentazione sullo stato di integrità del monitoraggio.

Per eseguire lo strumento di diagnostica utilizzando l'API REST, consulta la documentazione dell'API REST.

Accedere all'istanza

Puoi accedere alla tua istanza tramite un URL proxy.

Una volta creata e attivata l'istanza, puoi ottenere l'URL proxy utilizzando gcloud CLI.

Prima di utilizzare i dati dei comandi riportati di seguito, apporta le seguenti sostituzioni:

• INSTANCE_NAME: il nome dell'istanza Vertex AI Workbench
• PROJECT_ID: il tuo ID progetto
• LOCATION: la zona in cui si trova l'istanza

Esegui questo comando:

Linux, macOS o 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

Il comando describe restituisce l'URL del proxy. Per accedere alla tua istanza, apri l'URL del proxy in un browser web.

Per saperne di più sul comando per descrivere un'istanza dalla riga di comando, consulta la documentazione della CLI gcloud.