Créer une instance à l'aide d'un conteneur personnalisé

Cette page explique comment créer une instance Vertex AI Workbench basée sur un conteneur personnalisé.

Présentation

Les instances Vertex AI Workbench permettent d'utiliser un conteneur personnalisé dérivé d'un des conteneurs de base fournis par Google. Vous pouvez modifier ces conteneurs de base pour créer une image de conteneur personnalisé et utiliser ces conteneurs personnalisés pour créer une instance Vertex AI Workbench.

Les conteneurs de base sont configurés avec un OS optimisé pour les conteneurs dans la machine virtuelle (VM) hôte. L'image hôte est créée à partir de la famille d'images cos-stable.

Limites

Tenez compte des limites suivantes lors de la planification de votre projet :

  • Le conteneur personnalisé doit être dérivé d'un conteneur de base fourni par Google. L'utilisation d'un conteneur qui n'est pas dérivé d'un conteneur de base augmente le risque de problèmes de compatibilité et limite notre capacité à vous aider à utiliser les instances Vertex AI Workbench.

  • L'utilisation de plusieurs conteneurs avec une instance Vertex AI Workbench n'est pas possible.

  • Les métadonnées compatibles avec les conteneurs personnalisés des notebooks gérés par l'utilisateur et des notebooks gérés peuvent présenter un comportement différent lorsqu'elles sont utilisées avec des instances Vertex AI Workbench.

  • La VM qui héberge le conteneur personnalisé s'exécute sur un OS optimisé pour les conteneurs, ce qui limite la façon dont vous pouvez interagir avec la machine hôte. Par exemple, Container-Optimized OS n'inclut pas de gestionnaire de packages. Cela signifie que les packages agissant sur l'hôte doivent être exécutés sur un conteneur avec des montages. Cela affecte les scripts post-démarrage migrés à partir d'instances de notebooks gérés et d'instances de notebooks gérés par l'utilisateur, où la machine hôte contient beaucoup plus d'outils que Container-Optimized OS.

  • Les instances Vertex AI Workbench utilisent nerdctl (une CLI containerd) pour exécuter le conteneur personnalisé. Cette option est requise pour la compatibilité avec le service de streaming d'images. Tous les paramètres de conteneur ajoutés à l'aide d'une valeur de métadonnées doivent respecter les paramètres compatibles avec nerdctl.

  • Les instances Vertex AI Workbench sont configurées pour extraire des données d'Artifact Registry ou d'un dépôt de conteneurs publics. Pour configurer une instance afin qu'elle extrait des données d'un dépôt privé, vous devez configurer manuellement les identifiants utilisés par containerd.

Conteneurs de base

Conteneur de base standard

Le conteneur de base standard est compatible avec toutes les fonctionnalités de Vertex AI Workbench et inclut les éléments suivants :

Spécifications

Le conteneur de base standard présente les spécifications suivantes :

  • Image de base : nvidia/cuda:12.6.1-cudnn-devel-ubuntu24.04
  • Taille de l'image : environ 22 Go
  • URI : us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

Conteneur de base fin

Le conteneur de base léger fournit un ensemble minimal de configurations permettant une connexion proxy à l'instance. Les packages et fonctionnalités standards de Vertex AI Workbench ne sont pas inclus, à l'exception des suivants :

  • JupyterLab
  • Configuration de JupyterLab basée sur les métadonnées
  • Gestion des kernels basée sur Micromamba

Les packages ou extensions JupyterLab supplémentaires doivent être installés et gérés indépendamment.

Spécifications

Le conteneur de base fin présente les spécifications suivantes :

  • Image de base : marketplace.gcr.io/google/ubuntu24.04
  • Taille de l'image : environ 2 Go
  • URI : us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container-slim:latest

Avant de commencer

  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.

    Rôles requis

    Pour obtenir les autorisations nécessaires pour créer une instance Vertex AI Workbench avec un conteneur personnalisé, demandez à votre administrateur de vous accorder les rôles IAM suivants :

    Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

    Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

    Créer un conteneur personnalisé

    Pour créer un conteneur personnalisé à utiliser avec les instances Vertex AI Workbench, procédez comme suit :

    1. Créez un conteneur dérivé d'une image de conteneur de base fournie par Google.

    2. Créez et transférez le conteneur vers Artifact Registry. Vous utiliserez l'URI du conteneur lorsque vous créerez votre instance Vertex AI Workbench. Par exemple, l'URI peut se présenter comme suit : gcr.io/PROJECT_ID/IMAGE_NAME.

    Créer l'instance

    Vous pouvez créer une instance Vertex AI Workbench basée sur un conteneur personnalisé à l'aide de la console Google Cloud ou de Google Cloud CLI.

    Console

    Pour créer une instance Vertex AI Workbench basée sur un conteneur personnalisé, procédez comme suit :

    1. Dans la console Google Cloud , accédez à la page Instances.

      Accéder à la page "Instances"

    2. Cliquez sur Créer.

    3. Dans la boîte de dialogue Nouvelle instance, cliquez sur Options avancées.

    4. Dans la boîte de dialogue Créer une instance, dans la section Environnement, sélectionnez Utiliser un conteneur personnalisé.

    5. Dans Image de conteneur Docker, cliquez sur Sélectionner.

    6. Dans la boîte de dialogue Sélectionner l'image de conteneur, accédez à l'image de conteneur que vous souhaitez utiliser, puis cliquez sur Sélectionner.

    7. Facultatif. Pour Script post-démarrage, saisissez le chemin d'accès au script post-démarrage que vous souhaitez utiliser.

    8. Facultatif. Ajoutez des métadonnées pour votre instance. Pour en savoir plus, consultez Métadonnées de conteneur personnalisé.

    9. Facultatif. Dans la section Mise en réseau, personnalisez vos paramètres réseau. Pour en savoir plus, consultez Options de configuration du réseau.

    10. Renseignez le reste de la boîte de dialogue de création d'instance, puis cliquez sur Créer.

      Vertex AI Workbench crée une instance et la démarre automatiquement. Lorsque l'instance est prête à l'emploi, Vertex AI Workbench active automatiquement un lien Ouvrir JupyterLab.

    gcloud

    Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

    • INSTANCE_NAME : nom de votre instance Vertex AI Workbench. Ce nom doit commencer par une lettre, suivie de 62 caractères (lettres minuscules, chiffres ou traits d'union (-)), et ne peut pas se terminer par un trait d'union.
    • PROJECT_ID : ID de votre projet.
    • LOCATION : zone dans laquelle vous souhaitez placer votre instance.
    • CUSTOM_CONTAINER_PATH : chemin d'accès au dépôt d'images de conteneurs, par exemple : gcr.io/PROJECT_ID/IMAGE_NAME
    • METADATA : métadonnées personnalisées à appliquer à cette instance. Par exemple, pour spécifier un script post-démarrage, vous pouvez utiliser le tag de métadonnées post-startup-script au format "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh".

    Exécutez la commande suivante :

    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

    Pour en savoir plus sur la commande permettant de créer une instance à partir de la ligne de commande, consultez la documentation de la gcloud CLI.

    Vertex AI Workbench crée une instance et la démarre automatiquement. Lorsque l'instance est prête à l'emploi, Vertex AI Workbench active un lien Ouvrir JupyterLab dans la console Google Cloud .

    Options de configuration du réseau

    En plus des options réseau générales, une instance Vertex AI Workbench avec un conteneur personnalisé doit avoir accès au service Artifact Registry.

    Si vous avez désactivé l'accès aux adresses IP publiques pour votre VPC, assurez-vous d'avoir activé l'accès privé à Google.

    Activer le streaming d'images

    L'hôte de conteneur personnalisé est provisionné pour interagir avec le streaming d'images dans Google Kubernetes Engine (GKE), qui extrait les conteneurs plus rapidement et réduit le temps d'initialisation des grands conteneurs une fois qu'ils sont mis en cache dans le système de fichiers distant GKE.

    Pour connaître les conditions requises pour activer le streaming d'images, consultez Conditions requises. Le streaming d'images peut souvent être utilisé avec les instances Vertex AI Workbench en activant l'API Container File System.

    Activer l'API Container File System

    Comment la VM hôte exécute le conteneur personnalisé

    Au lieu d'utiliser Docker pour exécuter le conteneur personnalisé, la VM hôte utilise nerdctl sous l'espace de noms Kubernetes pour charger et exécuter le conteneur. Cela permet à Vertex AI Workbench d'utiliser le streaming d'images pour les conteneurs personnalisés.

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

    Exemple d'installation : conteneur personnalisé avec un kernel par défaut personnalisé

    L'exemple suivant montre comment créer un kernel avec un paquet pip préinstallé.

    1. Créez un conteneur personnalisé :

      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. Ajoutez le nouveau conteneur dans 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. Créer une instance

      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

    Noyaux persistants pour les conteneurs personnalisés

    Les conteneurs personnalisés Vertex AI Workbench ne montent un disque de données que dans le répertoire /home/USER de chaque conteneur, où jupyter est l'utilisateur par défaut. Cela signifie que toute modification en dehors de /home/USER est éphémère et ne persistera pas après un redémarrage. Si vous avez besoin que les packages installés persistent pour un noyau spécifique, vous pouvez créer un noyau dans le répertoire /home/USER.

    Pour créer un noyau dans le répertoire /home/USER :

    1. Créez un environnement 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"

      Remplacez les éléments suivants :

      • USER : nom du répertoire utilisateur, qui est jupyter par défaut
      • ENVIRONMENT_NAME : nom de l'environnement
      • PYTHON_VERSION : version de Python, par exemple 3.11

    2. Patientez 30 secondes à 1 minute pour que les kernels s'actualisent.

    Mettre à jour le démarrage du conteneur de base

    Le conteneur de base d'une instance Vertex AI Workbench (us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest) démarre JupyterLab en exécutant /run_jupyter.sh.

    Si vous modifiez le démarrage du conteneur dans un conteneur dérivé, vous devez ajouter /run_jupyter.sh pour exécuter la configuration par défaut de JupyterLab.

    Voici un exemple de modification du fichier 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

    Mettre à jour la configuration JupyterLab dans le conteneur de base

    Si vous devez modifier la configuration JupyterLab sur le conteneur de base, procédez comme suit :

    • Assurez-vous que JupyterLab est configuré sur le port 8080. Notre agent proxy est configuré pour transférer toute requête vers le port 8080. Si le serveur Jupyter n'écoute pas le bon port, l'instance rencontre des problèmes de provisionnement.

    • Modifiez les packages JupyterLab dans l'environnement micromamba jupyterlab. Nous fournissons un environnement de package distinct pour exécuter JupyterLab et son plug-in afin de nous assurer qu'il n'y a pas de conflits de dépendances avec l'environnement du noyau. Si vous souhaitez installer une extension JupyterLab supplémentaire, vous devez l'installer dans l'environnement jupyterlab. Exemple :

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

    Métadonnées de conteneur personnalisé

    En plus de la liste standard des métadonnées pouvant être appliquées à une instance Vertex AI Workbench, les instances avec des conteneurs personnalisés incluent les métadonnées suivantes pour gérer l'instanciation du conteneur de charge utile :

    Fonctionnalité Description Clé de métadonnée Valeurs acceptées et valeurs par défaut
    Active Cloud Storage FUSE sur une image de conteneur

    Installe /dev/fuse sur le conteneur et active gcsfuse pour une utilisation sur le conteneur.

    		container-allow-fuse
    • true : active Cloud Storage FUSE.
    • false (par défaut) : n'active pas Cloud Storage FUSE.
    Paramètres d'exécution de conteneur supplémentaires

    Ajoute des paramètres de conteneur supplémentaires à nerdctl run, où nerdctl est la CLI Containerd.

    		container-custom-params

    Chaîne de paramètres d'exécution du conteneur. Exemple : --v /mnt/disk1:/mnt/disk1.

    Options supplémentaires pour l'environnement de conteneur

    Stocke les variables d'environnement dans un indicateur sous /mnt/stateful_partition/workbench/container_env et l'ajoute à nerdctl run.

    		container-env-file

    Chaîne de variables d'environnement de conteneur. Exemple : CONTAINER_NAME=derivative-container.

    Mettre à niveau un conteneur personnalisé

    Lorsque votre instance démarre pour la première fois, elle extrait l'image de conteneur à partir d'un URI stocké dans les métadonnées custom-container-payload. Si vous utilisez le tag :latest, le conteneur est mis à jour à chaque redémarrage. La valeur de métadonnées custom-container-payload ne peut pas être modifiée directement, car il s'agit d'une clé de métadonnées protégée.

    Pour mettre à jour l'image de conteneur personnalisée de votre instance, vous pouvez utiliser les méthodes suivantes compatibles avec la Google Cloud CLI, Terraform ou l'API Notebooks.

    gcloud

    Vous pouvez mettre à jour les métadonnées de l'image de conteneur personnalisé sur une instance Vertex AI Workbench à l'aide de la commande suivante :

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

    Terraform

    Vous pouvez modifier le champ container_image dans la configuration Terraform pour mettre à jour la charge utile du conteneur.

    Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez la page Commandes Terraform de 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

    Utilisez la méthode instances.patch avec les modifications apportées à gce_setup.container_image.repository et gce_setup.container_image.tag dans updateMask.

    Lancer l'outil de diagnostic

    L'outil de diagnostic vérifie l'état de différents services Vertex AI Workbench. Pour en savoir plus, consultez Tâches effectuées par l'outil de diagnostic.

    Lorsque vous créez une instance Vertex AI Workbench à l'aide d'un conteneur personnalisé, l'outil de diagnostic n'est pas disponible en tant que script que les utilisateurs peuvent exécuter dans l'environnement hôte. Il est plutôt compilé dans un binaire et chargé dans un conteneur d'exécution Google conçu pour exécuter des services de diagnostic dans un environnement Container-Optimized OS. Consultez la présentation de Container-Optimized OS.

    Pour exécuter l'outil de diagnostic, procédez comme suit :

    1. Utilisez le protocole ssh pour vous connecter à votre instance Vertex AI Workbench.

    2. Dans le terminal SSH, exécutez la commande suivante :

      sudo docker exec diagnostic-service ./diagnostic_tool

    3. Pour afficher d'autres options de commande, exécutez la commande suivante :

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

    Pour en savoir plus sur les options de l'outil de diagnostic, consultez la documentation sur la surveillance de l'état de santé.

    Pour exécuter l'outil de diagnostic à l'aide de l'API REST, consultez la documentation de l'API REST.

    Accéder à votre instance

    Vous pouvez accéder à votre instance via une URL de proxy.

    Une fois votre instance créée et active, vous pouvez obtenir l'URL du proxy à l'aide de gcloud CLI.

    Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

    • INSTANCE_NAME : nom de votre instance Vertex AI Workbench
    • PROJECT_ID : ID de votre projet.
    • LOCATION : zone où se trouve votre instance

    Exécutez la commande suivante :

    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

    La commande describe renvoie l'URL de votre proxy. Pour accéder à votre instance, ouvrez l'URL du proxy dans un navigateur Web.

    Pour en savoir plus sur la commande permettant de créer une instance à partir de la ligne de commande, consultez la documentation de gcloud CLI.