Creazione di un'istanza utilizzando un container personalizzato

Questa pagina descrive come creare un'istanza di Gemini Enterprise Agent Platform Workbench basata su un container personalizzato.

Panoramica

Le istanze Workbench di Agent Platform 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 Agent Platform Workbench.

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

Limitazioni

Quando pianifichi il 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 Workbench di Agent Platform.

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

• La VM che ospita il container personalizzato è in esecuzione su un 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.

• Le istanze Workbench di Agent Platform 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 di immagini. Tutti i parametri del container aggiunti utilizzando un valore dei metadati devono rispettare quanto supportato da nerdctl.

• Le istanze Workbench di Agent Platform sono configurate per eseguire il pull 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

Agent Platform Workbench fornisce immagini container di base create da Google in due varianti: standard e slim. Ogni variante include Python 3.10 (predefinito) o Python 3.12. Utilizza l'URI corrispondente alla versione di Python che vuoi quando scrivi l'istruzione FROM del container derivato.

Container di base standard

Il container di base standard supporta tutte le funzionalità di Agent Platform Workbench e include quanto segue:

• Pacchetti di data science preinstallati.
• Librerie Cuda simili a Deep Learning Containers.
• Google Cloud Integrazioni di JupyterLab come le integrazioni di Managed Service for Apache Spark e BigQuery.
• Pacchetti di sistema comuni come curl o git.
• Configurazione di JupyterLab basata sui metadati.
• Gestione del kernel basata su Micromamba.

Specifiche

Il container di base standard ha le seguenti specifiche:

• Immagine di base: nvidia/cuda:12.6.1-cudnn-devel-ubuntu24.04
• Dimensioni dell'immagine: circa 22 GB
• URI (Python 3.10, predefinito): us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
• URI (Python 3.12): us-docker.pkg.dev/workbench-images/gcr.io/workbench-container-2606:latest

Container di base slim

Il container di base slim fornisce un insieme minimo di configurazioni che consentono una connessione proxy all'istanza. Standard Le funzionalità e i pacchetti di Agent Platform Workbench non sono inclusi, ad eccezione dei seguenti:

• JupyterLab
• Configurazione di JupyterLab basata sui metadati
• Gestione del kernel basata su Micromamba

I pacchetti aggiuntivi o le estensioni di JupyterLab devono essere installati e gestiti in modo indipendente.

Specifiche

Il container di base slim ha le seguenti specifiche:

• Immagine di base: marketplace.gcr.io/google/ubuntu24.04
• Dimensioni dell'immagine: circa 2 GB
• URI (Python 3.10, predefinito): us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest
• URI (Python 3.12): us-docker.pkg.dev/workbench-images/gcr.io/workbench-container-slim-2606:latest

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Notebooks API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare un'istanza di Agent Platform 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: Artifact Registry Reader (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 container personalizzato da utilizzare con le istanze di Agent Platform Workbench:

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

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

Crea l'istanza

Puoi creare un'istanza di Agent Platform Workbench basata su un container personalizzato utilizzando la console Google Cloud o Google Cloud CLI.

Console

Per creare un'istanza di Agent Platform Workbench basata su un container personalizzato, segui questi passaggi:

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 Usa container personalizzato.

5. In 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. In Script post-avvio, inserisci il percorso di uno script post-avvio che vuoi utilizzare.

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

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

10. Completa il resto della finestra di dialogo per la creazione dell'istanza, quindi fai clic su Crea.

    Agent Platform Workbench crea un'istanza e la avvia automaticamente. Quando l'istanza è pronta per l'uso, Agent Platform 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 Agent Platform 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: i metadati personalizzati da applicare a questa istanza; ad esempio, per specificare uno script post-avvio, puoi utilizzare il tag dei metadati post-startup-script, nel formato: "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"

Esegui questo comando:

Linux, macOS o Cloud Shell

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init o gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init o gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init o gcloud auth login e gcloud config set project.

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

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

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

Opzioni di configurazione di rete

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

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

Abilita flusso immagine

L'host del container personalizzato è sottoposto a provisioning per interagire con Image Streaming 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 di GKE.

Per visualizzare i requisiti per l'attivazione di Image Streaming, consulta Requisiti. Spesso, lo streaming di immagini può essere utilizzato con le istanze di Agent Platform 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, Agent Platform 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 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 container 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/REPOSITORY_NAME/IMAGE_NAME \
       --container-tag=latest

Kernel persistenti per container personalizzati

I container personalizzati di Agent Platform Workbench montano un disco dati solo nella directory /home/USER all'interno di ogni container, 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 hai bisogno che i pacchetti installati vengano mantenuti per un kernel specifico, puoi creare un kernel nella directory /home/USER.

Nota: i container di base sono configurati con un punto di montaggio su /home/USER. Per creare un kernel permanente durante la creazione di un'immagine personalizzata, devi attivare Docker BuildKit. Consulta le note sulla specifica dei volumi. Per saperne di più su BuildKit, consulta la documentazione di BuildKit.

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 per l'aggiornamento dei kernel.

Aggiornamento dell'avvio del container di base

Il container di base per un'istanza Agent Platform 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 sul container di base, devi procedere nel seguente modo:

• Assicurati che JupyterLab sia configurato sulla 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 micromamba jupyterlab. Forniamo un ambiente di pacchetti separato per eseguire JupyterLab e il suo plug-in per garantire 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 container personalizzato

Oltre all'elenco standard di metadati che possono essere applicati a un'istanza di Gemini Enterprise Agent Platform Workbench, le istanze con container personalizzati includono i seguenti metadati per la gestione della creazione di istanze del container del 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: abilita Cloud Storage FUSE. false (predefinito): non abilita Cloud Storage FUSE.
Parametri di esecuzione del container aggiuntivi	Aggiunge ulteriori parametri del container a nerdctl run, dove nerdctl è l'interfaccia a riga di comando di Containerd.	container-custom-params	Una stringa di parametri di esecuzione del container. Esempio: --v /mnt/disk1:/mnt/disk1.
Flag aggiuntivi per l'ambiente del 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.

Esegui l'upgrade di un container personalizzato

Quando l'istanza viene avviata per la prima volta, esegue il pull dell'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é 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 container personalizzata su un'istanza di Agent Platform 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 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 Agent Platform Workbench. Per scoprire di più, consulta Attività eseguite dallo strumento diagnostico.

Quando crei un'istanza di Agent Platform 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 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, completa i seguenti passaggi:

1. Utilizza ssh per connetterti all'istanza di Agent Platform Workbench.

2. Nel terminale SSH, esegui questo comando:

   sudo docker exec diagnostic-service ./diagnostic_tool

3. Per visualizzare altre opzioni del 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 sul monitoraggio dello stato di integrità.

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 Agent Platform Workbench
• PROJECT_ID: il tuo ID progetto
• LOCATION: la zona in cui si trova l'istanza

Esegui questo comando:

Linux, macOS o Cloud Shell

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init o gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init o gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init o gcloud auth login e gcloud config set project.

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 di gcloud CLI.