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 uno dei contenitori di base forniti da Google. Puoi modificare questi contenuti di base per creare un'immagine contenitore personalizzata e utilizzare questi contenuti personalizzati per creare un'istanza di Vertex AI Workbench.

I container di base sono configurati con un sistema operativo ottimizzato per i container nella macchina virtuale (VM) di destinazione. L'immagine host viene creata dalla cos-stable famiglia di immagini.

Limitazioni

Tieni presenti le seguenti limitazioni quando pianifichi il tuo progetto:

• Il container personalizzato deve essere derivato da un container di base fornito da Google. L'utilizzo di un contenitore non derivato da un 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 contenitori 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 essere conformi a quanto supportato da nerdctl.

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

Container di base

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. 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

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 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 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 Google Cloud console o Google Cloud CLI.

Console

Per creare un'istanza di Vertex AI Workbench basata su un contenitore personalizzato, procedi nel seguente modo:

1. Nella Google Cloud console, 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 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. Per 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 di 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 Google Cloud console.

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 abilitato 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

Come la VM host esegue il contenitore personalizzato

Anziché utilizzare Docker per eseguire il contenitore personalizzato, la VM host utilizza nerdctl nello spazio dei nomi Kubernetes per caricare ed eseguire il contenutore. 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

Esempio di installazione: container 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/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 è jupyter per impostazione predefinita
   • ENVIRONMENT_NAME: il nome dell'ambiente
   • PYTHON_VERSION: la versione di Python, ad esempio 3.11

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

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 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 sul 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.

Eseguire l'upgrade di un container personalizzato

Quando l'istanza viene avviata per la prima volta, estrae l'immagine container da un URI archiviato nei metadati custom-container-payload. Se utilizzi il tag :latest, il contenitore viene aggiornato a ogni riavvio. Il valore dei metadati custom-container-payload non può essere modificato direttamente perché si tratta di una chiave dei 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 del contenitore personalizzato 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 contenitore.

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 le 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 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 di 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.