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 contenitore personalizzato derivato da un contenitore di base fornito da Google. Puoi modificare questo contenitore di base per creare un'immagine contenitore personalizzata e utilizzare questo contenitore personalizzato per creare un'istanza di Vertex AI Workbench.

Il contenitore di base è configurato con un sistema operativo ottimizzato per i container nella macchina virtuale (VM) di destinazione. Il contenitore di base fornisce pacchetti di data science preinstallati e configurazioni specifiche che consentono all'istanza di integrarsi con Google Cloud.

Il contenitore di base si trova in gcr.io/deeplearning-platform-release/workbench-container:latest.

Limitazioni

Tieni presenti le seguenti limitazioni quando pianifichi il tuo progetto:

  • Il contenitore personalizzato deve essere derivato dal contenitore di base fornito da Google (gcr.io/deeplearning-platform-release/workbench-container:latest). L'utilizzo di un contenitore non derivato dal contenitore 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 contenitore con un'istanza di 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 di Vertex AI Workbench.

  • La VM che ospita il contenitore personalizzato è in esecuzione su un sistema operativo ottimizzato per i container, che limita le modalità di interazione con la macchina host. Ad esempio, Container-Optimized OS non include un gestore dei pacchetti. Ciò significa che i pacchetti che agiscono sull'host devono essere eseguiti su un contenitore con i mount. Ciò influisce sugli script di post-avvio di cui viene eseguita la migrazione da istanze di notebook gestite e da istanze di notebook gestite dall'utente, in cui la macchina host contiene molti più strumenti rispetto a Container-Optimized OS.

  • Le istanze Vertex AI Workbench utilizzano nerdctl (una CLI di containerd) per eseguire il container personalizzato. Questo passaggio è obbligatorio per la compatibilità con il servizio di streaming di immagini. Tutti i parametri del contenitore aggiunti utilizzando un valore dei metadati devono rispettare quanto supportato da nerdctl.

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

Prima di iniziare

  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.

Ruoli obbligatori

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

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

Per saperne di più sulla concessione dei ruoli, consulta Gestire 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 di Vertex AI Workbench:

  1. Crea un container derivato dall'immagine container di base fornita da Google (gcr.io/deeplearning-platform-release/workbench-container:latest).

  2. Crea ed esegui il push del container in Artifact Registry. Utilizzerai l'URI del contenitore quando crei l'istanza di 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 di 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 contenitore personalizzato, procedi nel seguente modo:

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

    Vai a Istanze

  2. Fai clic su  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 Utilizza contenitore personalizzato.

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

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

  7. Facoltativo. In Script post-avvio, inserisci il percorso di uno script post-avvio che vuoi utilizzare.

  8. Facoltativo. Aggiungi i metadati per l'istanza. Per scoprire di più, consulta Metadati dei contenitori personalizzati.

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

  10. Completa la parte rimanente 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, effettua le seguenti sostituzioni:

  • INSTANCE_NAME: il nome dell'istanza di 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 delle immagini container, ad esempio: gcr.io/PROJECT_ID/IMAGE_NAME
  • METADATA: metadati personalizzati da applicare a questa istanza. Ad esempio, per specificare uno script post-avvio, puoi utilizzare il tag metadati post-startup-script nel formato: "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"

Esegui il seguente 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 la creazione di un'istanza dalla riga di comando, consulta la documentazione della riga di comando 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 contenitore personalizzato deve avere accesso al servizio Artifact Registry.

Se hai disattivato l'accesso tramite IP pubblico per la tua VPC, assicurati di aver attivato l'accesso privato Google.

Attivare il flusso di immagini

L'host del contenitore personalizzato viene eseguito il provisioning per interagire con il flusso di immagini in Google Kubernetes Engine (GKE), che estrae i contenitori più velocemente e riduce i tempi di inizializzazione per i contenitori di grandi dimensioni una volta memorizzati nella cache nel file system remoto GKE.

Per visualizzare i requisiti per attivare lo 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.

Attivare l'API Container File System

Esempio di installazione: contenitore personalizzato con un kernel predefinito personalizzato

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

  1. Crea un nuovo contenitore 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 permanenti per i container personalizzati

I contenitori personalizzati di Vertex AI Workbench montano un disco di dati solo 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 è effimera e non verrà mantenuta dopo un riavvio. Se hai bisogno che i pacchetti installati rimangano 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/jupyter/ENVIRONMENT_NAME -c conda-forge python=3.11 -y
micromamba activate ENVIRONMENT_NAME
pip install ipykernel
pip install -r ~/requirement.txt
python -m ipykernel install --prefix "/home/jupyter/ENVIRONMENT_NAME" --display-name "Example Kernel"

  2. Attendi da 30 secondi a 1 minuto per l'aggiornamento dei kernel.

Aggiornamento dell'avvio del contenitore di base

Il contenitore 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 contenitore in un contenitore 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

# 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 contenitore di base

Se devi modificare la configurazione di JupyterLab nel contenitore 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 ascolta la porta corretta, l'istanza riscontra problemi di provisioning.

  • Modifica i pacchetti JupyterLab nell'ambiente jupyterlab micromamba. Forniamo un ambiente del pacchetto separato per eseguire JupyterLab e il relativo plug-in per assicurarci che non ci siano conflitti di dipendenza 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 contenitore personalizzato

Oltre all'elenco standard di metadati che può essere applicato a un'istanza di Vertex AI Workbench, le istanze con contenuti personalizzati includono i seguenti metadati per la gestione della instanziazione del contenitore del payload:

Funzionalità Descrizione Chiave dei metadati Valori accettati e valori predefiniti
Consente di attivare Cloud Storage FUSE in un'immagine container

Monta /dev/fuse sul contenitore e attiva gcsfuse per l'utilizzo nel contenitore.

container-allow-fuse
  • true: attiva Cloud Storage FUSE.
  • false (valore predefinito): non attiva Cloud Storage FUSE.
Parametri di esecuzione del contenitore aggiuntivi

Aggiunge parametri del contenitore aggiuntivi a nerdctl run, dove nerdctl è l'interfaccia a riga di comando Containerd.

container-custom-params

Una stringa di parametri di esecuzione del contenitore. Esempio: --v /mnt/disk1:/mnt/disk1.

Flag aggiuntivi per l'ambiente del contenitore

Memorizza le variabili di ambiente in un flag in /mnt/stateful_partition/workbench/container_env e le aggiunge a nerdctl run.

container-env-file

Una stringa di variabili di ambiente del contenitore. Esempio: CONTAINER_NAME=derivative-container.

URI del contenitore del payload

Il payload del contenitore personalizzato con JupyterLab che viene caricato nell'istanza di Vertex AI Workbench.

custom-container-payload

Una stringa URI. Esempio: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest.

Eseguire l'upgrade di un container personalizzato

Se il contenitore personalizzato deve essere aggiornato, puoi farlo aggiornando il valore del metadato custom-container-payload con il nuovo URI del contenitore. Ogni riavvio del contenitore tenta di estrarlo dall'URI memorizzato in custom-container-payload.

Se utilizzi il tag :latest, il contenitore di base viene aggiornato a ogni riavvio. Vedi il seguente esempio:

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

Per evitare di aggiornare il contenitore di base, puoi specificare la versione. Vedi l'esempio seguente:

custom-container-payload = us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:20240920-2200-rc0

Esegui lo strumento di diagnostica

Lo strumento di diagnostica controlla e verifica lo stato di vari servizi di Vertex AI Workbench. Per scoprire di più, consulta la sezione Attività svolte dallo strumento di diagnostica.

Quando crei un'istanza di Vertex AI Workbench utilizzando un contenitore 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 su un contenitore di 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, svolgi 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 il seguente comando:

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

Per ulteriori informazioni sulle opzioni dello strumento di diagnostica, consulta la documentazione relativa allo stato di salute del monitoraggio.

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

Accedi all'istanza

Puoi accedere all'istanza tramite un URL proxy.

Dopo aver creato l'istanza e averla attivata, puoi ottenere l'URL del proxy utilizzando gcloud CLI.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua 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 il seguente 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 all'istanza, apri l'URL proxy in un browser web.

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