Instanz mit einem benutzerdefinierten Container erstellen

Auf dieser Seite wird beschrieben, wie Sie eine Vertex AI Workbench-Instanz basierend auf einem benutzerdefinierten Container erstellen.

Übersicht

Vertex AI Workbench-Instanzen unterstützen die Verwendung eines benutzerdefinierten Containers, der von einem der von Google bereitgestellten Basiscontainer abgeleitet ist. Sie können diese Basiscontainer ändern, um ein benutzerdefiniertes Container-Image zu erstellen, und diese benutzerdefinierten Container verwenden, um eine Vertex AI Workbench-Instanz zu erstellen.

Die Basiscontainer sind mit einem Container-Optimized OS auf der virtuellen Hostmaschine (VM) konfiguriert. Das Host-Image wird aus der cos-stable-Image-Familie erstellt.

Beschränkungen

Beachten Sie beim Planen Ihres Projekts die folgenden Einschränkungen:

• Der benutzerdefinierte Container muss von einem von Google bereitgestellten Basiscontainer abgeleitet sein. Die Verwendung eines Containers, der nicht von einem Basiscontainer abgeleitet ist, erhöht das Risiko von Kompatibilitätsproblemen und schränkt unsere Möglichkeiten ein, Sie bei der Verwendung von Vertex AI Workbench-Instanzen zu unterstützen.

• Verwendung mehrerer Container mit einer Vertex AI Workbench-Instanz wird nicht unterstützt.

• Unterstützte Metadaten für benutzerdefinierte Container aus nutzerverwalteten Notebooks und verwalteten Notebooks können sich bei der Verwendung mit Vertex AI Workbench-Instanzen unterschiedlich verhalten.

• Die VM, auf der der benutzerdefinierte Container gehostet wird, wird mit einem Container-Optimized OS ausgeführt. Dadurch wird eingeschränkt, wie Sie mit dem Hostcomputer interagieren können. Container-Optimized OS enthält beispielsweise keinen Paketmanager. Das bedeutet, dass Pakete, die auf den Host wirken, in einem Container mit Mounts ausgeführt werden müssen. Dies betrifft die Post-Startup-Skripts, die von verwalteten Notebook-Instanzen und von nutzerverwalteten Notebook-Instanzen migriert werden, da die Hostmaschine deutlich mehr Tools als Container-Optimized OS enthält.

• Vertex AI Workbench-Instanzen verwenden nerdctl (eine containerd-Befehlszeilenschnittstelle) zum Ausführen des benutzerdefinierten Containers. Dies ist für die Kompatibilität mit dem Bild-Streamingdienst erforderlich. Alle Containerparameter, die mit einem Metadatenwert hinzugefügt werden, müssen den von nerdctl unterstützten Parametern entsprechen.

• Vertex AI Workbench-Instanzen sind so konfiguriert, dass sie entweder aus Artifact Registry oder aus einem öffentlichen Container-Repository abgerufen werden. Wenn Sie eine Instanz so konfigurieren möchten, dass sie aus einem privaten Repository abgerufen wird, müssen Sie die von containerd verwendeten Anmeldedaten manuell konfigurieren.

Basiscontainer

Hinweise

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

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen einer Vertex AI Workbench-Instanz mit einem benutzerdefinierten Container benötigen:

• Notebooks-Ausführer (roles/notebooks.runner) für das Nutzerkonto
• So rufen Sie Images aus dem Artifact Registry-Repository ab: Artifact Registry-Leser (roles/artifactregistry.reader) für das Dienstkonto

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Benutzerdefinierten Container erstellen

So erstellen Sie einen benutzerdefinierten Container für die Verwendung mit Vertex AI Workbench-Instanzen:

1. Erstellen Sie einen Container, der von einem von Google bereitgestellten Basiscontainer-Image abgeleitet ist.

2. Erstellen Sie den Container und übertragen Sie ihn per Push in die Artifact Registry. Sie verwenden die URI des Containers, wenn Sie Ihre Vertex AI Workbench-Instanz erstellen. Dieser URI könnte so aussehen: gcr.io/PROJECT_ID/IMAGE_NAME.

Die Instanz erstellen

Sie können eine Vertex AI Workbench-Instanz auf Grundlage eines benutzerdefinierten Containers mit der Google Cloud Console oder der Google Cloud CLI erstellen.

Console

So erstellen Sie eine Vertex AI Workbench-Instanz basierend auf einem benutzerdefinierten Container:

1. Rufen Sie in der Google Cloud Console die Seite Instanzen auf.

   Zur Seite „VM-Instanzen“

2. Klicken Sie auf add_box NEU ERSTELLEN.

3. Klicken Sie im Dialogfeld Neue Instanz auf Erweiterte Optionen.

4. Wählen Sie im Dialogfeld Instanz erstellen im Abschnitt Umgebung die Option Benutzerdefinierten Container verwenden aus.

5. Klicken Sie für Docker-Container-Image auf Auswählen.

6. Suchen Sie im Dialogfeld Container-Image auswählen nach dem Container-Image, das Sie verwenden möchten, und klicken Sie dann auf Auswählen.

7. Optional. Geben Sie für Post-Startskript einen Pfad zu einem Post-Startskript ein, das Sie verwenden möchten.

8. Optional. Fügen Sie Metadaten für Ihre Instanz hinzu. Weitere Informationen finden Sie unter Metadaten für benutzerdefinierte Container.

9. Optional. Passen Sie im Bereich „Netzwerk“ Ihre Netzwerkeinstellungen an. Weitere Informationen finden Sie unter Netzwerkkonfigurationsoptionen.

10. Schließen Sie den Rest des Dialogfelds zur Instanzerstellung ab und klicken Sie dann auf Erstellen.

    Vertex AI Workbench erstellt eine Instanz und startet sie automatisch. Sobald die Instanz einsatzbereit ist, aktiviert Vertex AI Workbench den Link JupyterLab öffnen.

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

• INSTANCE_NAME: der Name Ihrer Vertex AI Workbench-Instanz; muss mit einem Buchstaben beginnen, gefolgt von bis zu 62 Kleinbuchstaben, Ziffern oder Bindestrichen (-) und darf nicht mit einem Bindestrich enden
• PROJECT_ID: Ihre Projekt-ID.
• LOCATION: die Zone, in der sich Ihre Instanz befinden soll
• CUSTOM_CONTAINER_PATH: der Pfad zum Container-Image-Repository, z. B. gcr.io/PROJECT_ID/IMAGE_NAME
• METADATA: Benutzerdefinierte Metadaten, die auf diese Instanz angewendet werden sollen. Wenn Sie beispielsweise ein Post-Startscript angeben möchten, können Sie das Metadaten-Tag post-startup-script im folgenden Format verwenden: "--metadata=post-startup-script=gs://BUCKET_NAME/hello.sh"

Führen Sie folgenden Befehl aus:

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

Weitere Informationen zum Befehl zum Erstellen einer Instanz über die Befehlszeile ausführen, siehe gcloud CLI Dokumentation.

Vertex AI Workbench erstellt eine Instanz und startet sie automatisch. Sobald die Instanz einsatzbereit ist, aktiviert Vertex AI Workbench den Link JupyterLab öffnen in der Google Cloud Console.

Optionen für die Netzwerkkonfiguration

Zusätzlich zu den allgemeinen Netzwerkoptionen muss eine Vertex AI Workbench-Instanz mit einem benutzerdefinierten Container Zugriff auf den Artifact Registry-Dienst haben.

Wenn Sie den Zugriff über öffentliche IP-Adressen für Ihre VPC deaktiviert haben, müssen Sie den privater Google-Zugriff aktivieren.

Image-Streaming aktivieren

Der benutzerdefinierte Container-Host wird für die Interaktion mit dem Image-Streaming in Google Kubernetes Engine (GKE) bereitgestellt. Dadurch werden Container schneller abgerufen und die Initialisierungszeit für große Container verkürzt, sobald sie im GKE-Remote-Dateisystem zwischengespeichert sind.

Die Anforderungen für die Aktivierung von Image-Streaming findest du unter Anforderungen. Oft kann Image-Streaming mit Vertex AI Workbench-Instanzen verwendet werden, indem die Container File System API aktiviert wird.

Container File System API aktivieren

So wird der benutzerdefinierte Container auf der Host-VM ausgeführt

Anstatt Docker zum Ausführen des benutzerdefinierten Containers zu verwenden, lädt und führt die Host-VM den Container mit nerdctl unter dem Kubernetes-Namespace aus. So kann Vertex AI Workbench Image-Streaming für benutzerdefinierte Container verwenden.

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

Beispiel für die Installation: benutzerdefinierter Container mit einem benutzerdefinierten Standardkernel

Im folgenden Beispiel wird gezeigt, wie Sie einen neuen Kernel mit einem vorinstallierten Pip-Paket erstellen.

1. So erstellen Sie einen neuen benutzerdefinierten Container:

   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. Fügen Sie den neuen Container zu Artifact Registry hinzu:

   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. Instanz erstellen:

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

Persistente Kernel für benutzerdefinierte Container

Bei benutzerdefinierten Containern von Vertex AI Workbench wird nur eine Datenlaufwerk im Verzeichnis /home/USER in jedem Container bereitgestellt, wobei jupyter der Standardnutzer ist. Das bedeutet, dass alle Änderungen außerhalb von /home/USER nur vorübergehend sind und nach einem Neustart nicht mehr vorhanden sind. Wenn installierte Pakete für einen bestimmten Kernel beibehalten werden sollen, können Sie einen Kernel im Verzeichnis /home/USER erstellen.

So erstellen Sie einen Kernel im Verzeichnis /home/USER:

1. Micromamba-Umgebung erstellen:

   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"

   Ersetzen Sie Folgendes:

   • USER: der Name des Nutzerverzeichnisses, der standardmäßig jupyter ist
   • ENVIRONMENT_NAME: der Name der Umgebung
   • PYTHON_VERSION: Die Python-Version, z. B. 3.11

2. Warten Sie 30 Sekunden bis 1 Minute, bis die Kernel aktualisiert werden.

Start des Basiscontainers aktualisieren

Der Basiscontainer für eine Vertex AI Workbench-Instanz (us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest) startet JupyterLab durch Ausführen von /run_jupyter.sh.

Wenn Sie den Start des Containers in einem abgeleiteten Container ändern, müssen Sie /run_jupyter.sh anhängen, um die Standardkonfiguration von JupyterLab auszuführen.

Hier sehen Sie ein Beispiel dafür, wie das Dockerfile geändert werden könnte:

# 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

JupyterLab-Konfiguration im Basiscontainer aktualisieren

Wenn Sie die JupyterLab-Konfiguration im Basiscontainer ändern müssen, gehen Sie so vor:

• Achten Sie darauf, dass JupyterLab für Port 8080 konfiguriert ist. Unser Proxy-Agent ist so konfiguriert, dass er alle Anfragen an Port 8080 weiterleitet. Wenn der Jupyter-Server nicht auf dem richtigen Port wartet, treten bei der Instanz Bereitstellungsprobleme auf.

• Ändern Sie JupyterLab-Pakete in der jupyterlab-Micromamba-Umgebung. Wir stellen eine separate Paketumgebung für die Ausführung von JupyterLab und seinem Plug-in bereit, um Abhängigkeitskonflikte mit der Kernelumgebung zu vermeiden. Wenn Sie eine zusätzliche JupyterLab-Erweiterung installieren möchten, müssen Sie sie in der Umgebung jupyterlab installieren. Beispiel:

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

Benutzerdefinierte Containermetadaten

Zusätzlich zur Standardliste der Metadaten, die auf eine Vertex AI Workbench-Instanz angewendet werden können, enthalten Instanzen mit benutzerdefinierten Containern die folgenden Metadaten zum Verwalten der Instanziierung des Nutzlastcontainers:

Funktion	Beschreibung	Metadatenschlüssel	Gültige Werte und Standardeinstellungen
Aktiviert Cloud Storage FUSE in einem Container-Image	/dev/fuse wird im Container bereitgestellt und gcsfuse für die Verwendung im Container aktiviert	container-allow-fuse	true: Aktiviert Cloud Storage FUSE false (Standardeinstellung): Cloud Storage FUSE ist nicht aktiviert
Zusätzliche Parameter für die Containerausführung	Fügt nerdctl run zusätzliche Containerparameter hinzu, wobei nerdctl die Containerd-CLI ist.	container-custom-params	Ein String mit Parametern für die Containerausführung. Beispiel: --v /mnt/disk1:/mnt/disk1.
Zusätzliche Flags für die Containerumgebung	Speichert Umgebungsvariablen in einem Flag unter /mnt/stateful_partition/workbench/container_env und hängt es an nerdctl run an.	container-env-file	Ein String mit Container-Umgebungsvariablen. Beispiel: CONTAINER_NAME=derivative-container.

Benutzerdefinierten Container aktualisieren

Wenn Ihre Instanz zum ersten Mal gestartet wird, wird das Container-Image aus einem URI abgerufen, der in den custom-container-payload-Metadaten gespeichert ist. Wenn Sie das Tag :latest verwenden, wird der Container bei jedem Neustart aktualisiert. Der Metadatenwert custom-container-payload kann nicht direkt geändert werden, da es sich um einen geschützten Metadatenschlüssel handelt.

Sie können das benutzerdefinierte Container-Image Ihrer Instanz mit den folgenden Methoden aktualisieren, die von der Google Cloud CLI, Terraform oder der Notebooks API unterstützt werden.

gcloud

Sie können die Metadaten des benutzerdefinierten Container-Images für eine Vertex AI Workbench-Instanz mit dem folgenden Befehl aktualisieren:

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

Terraform

Sie können das Feld container_image in der Terraform-Konfiguration ändern, um die Container-Payload zu aktualisieren.

Informationen zum Anwenden oder Entfernen einer Terraform-Konfiguration finden Sie unter Grundlegende Terraform-Befehle.

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"
    }
  }
}

Notebooks API

Verwenden Sie die Methode instances.patch mit Änderungen an gce_setup.container_image.repository und gce_setup.container_image.tag in der updateMask.

Diagnosetool ausführen

Das Diagnosetool prüft und verifiziert den Status verschiedener Vertex AI Workbench-Dienste. Weitere Informationen finden Sie unter Vom Diagnosetool ausgeführte Aufgaben.

Wenn Sie eine Vertex AI Workbench-Instanz mit einem benutzerdefinierten Container erstellen, ist das Diagnosetool nicht als Skript in der Hostumgebung verfügbar, das Nutzer ausführen können. Stattdessen wird es in eine Binärdatei kompiliert und in einen Google-Laufzeitcontainer geladen, der für die Ausführung von Diagnosediensten in einer Container-Optimized OS-Umgebung entwickelt wurde. Weitere Informationen finden Sie unter Übersicht über Container-Optimized OS.

Führen Sie die folgenden Schritte aus, um das Diagnosetool auszuführen:

1. Stellen Sie eine SSH-Verbindung zur Vertex AI Workbench-Instanz her.

2. Führen Sie im SSH-Terminal den folgenden Befehl aus:

   sudo docker exec diagnostic-service ./diagnostic_tool

3. Führen Sie den folgenden Befehl aus, um sich weitere Befehlsoptionen anzeigen zu lassen:

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

Weitere Informationen zu den Optionen des Diagnosetools finden Sie in der Dokumentation zum Überwachen des Integritätsstatus.

Informationen zum Ausführen des Diagnosetools über die REST API finden Sie in der REST API-Dokumentation.

Auf die Instanz zugreifen

Sie können über eine Proxy-URL auf Ihre Instanz zugreifen.

Nachdem die Instanz erstellt wurde und aktiv ist, können Sie den Proxy-URL mithilfe der gcloud CLI abrufen.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

• INSTANCE_NAME: Der Name Ihrer Vertex AI Workbench-Instanz
• PROJECT_ID: Ihre Projekt-ID.
• LOCATION: Zone, in der sich Ihre Instanz befindet.

Führen Sie folgenden Befehl aus:

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

Der Befehl describe gibt Ihre Proxy-URL zurück. Um auf Ihre Instanz zuzugreifen, öffnen Sie die Proxy-URL in einem Webbrowser.

Weitere Informationen zum Befehl zum Beschreiben einer Instanz über die Befehlszeile siehe gcloud CLI Dokumentation.