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 von Google bereitgestellten Basiscontainer abgeleitet ist. Sie können diesen Basiscontainer ändern, um ein benutzerdefiniertes Container-Image zu erstellen, und mit diesem benutzerdefinierten Container eine Vertex AI Workbench-Instanz erstellen.

Der Basiscontainer ist mit einem Container-Optimized OS auf der virtuellen Hostmaschine (VM) konfiguriert. Der Basiscontainer bietet vorinstallierte Data Science Pakete sowie spezifische Konfigurationen, mit denen sich Ihre Instanz in Google Cloud integrieren lässt.

Der Basiscontainer befindet sich unter gcr.io/deeplearning-platform-release/workbench-container:latest

Beschränkungen

Beachten Sie bei der Planung Ihres Projekts die folgenden Einschränkungen:

• Der benutzerdefinierte Container muss aus dem von Google bereitgestellten Basiscontainer (gcr.io/deeplearning-platform-release/workbench-container:latest) abgeleitet sein. Die Verwendung eines Containers, der nicht vom 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, verwendet ein Container-Optimized OS, was die Interaktion mit dem Hostcomputer einschränkt. Container-Optimized OS enthält beispielsweise keinen Paketmanager. Das bedeutet, dass Pakete, die auf dem Host ausgeführt werden, in einem Container mit Bereitstellungen ausgeführt werden müssen. Das betrifft die Scripts nach dem Start, die von verwalteten Notebook-Instanzen und von vom Nutzer verwalteten Notebook-Instanzen migriert werden, bei denen der Hostcomputer deutlich mehr Tools als Container-Optimized OS enthält.

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

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

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
• Zum Abrufen von Images aus dem Artifact Registry-Repository: 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 vom Von Google bereitgestellten Basiscontainer-Image (gcr.io/deeplearning-platform-release/workbench-container:latest) 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. Der URI könnte beispielsweise 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.

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

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

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

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 öffentlichen IP-Zugriff für Ihre VPC deaktiviert haben, müssen Sie den privater Google-Zugriff aktivieren.

Image-Streaming aktivieren

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

Informationen zu den Anforderungen zum Aktivieren des Bildstreamings finden Sie unter Anforderungen. Oft kann das Bildstreaming mit Vertex AI Workbench-Instanzen verwendet werden, indem die Container File System API aktiviert wird.

Container File System API aktivieren

Ausführen des benutzerdefinierten Containers auf der Host-VM

Anstatt den benutzerdefinierten Container mit Docker auszuführen, verwendet die Host-VM nerdctl unter dem Kubernetes-Namespace, um den Container zu laden und auszuführen. So kann Vertex AI Workbench das Bildstreaming für benutzerdefinierte Container verwenden.

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

Beispielinstallation: benutzerdefinierter Container mit benutzerdefiniertem 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

In benutzerdefinierten Vertex AI Workbench-Containern wird nur ein Datenlaufwerk im Verzeichnis /home/USER jedes Containers bereitgestellt. Dabei ist jupyter der Standardnutzer. Das bedeutet, dass alle Änderungen außerhalb von /home/USER vorübergehend sind und nach einem Neustart nicht mehr vorhanden sind. Wenn installierte Pakete für einen bestimmten Kernel erhalten bleiben 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/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. Warten Sie 30 Sekunden bis eine Minute, bis die Kernel aktualisiert wurden.

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.

Im Folgenden finden 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

# 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öchten, gehen Sie so vor:

• Achten Sie darauf, dass JupyterLab für Port 8080 konfiguriert ist. Unser Proxy-Agent ist so konfiguriert, dass alle Anfragen an Port 8080 weitergeleitet werden. Wenn der Jupyter-Server nicht den richtigen Port überwacht, 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, damit keine Abhängigkeitskonflikte mit der Kernelumgebung auftreten. Wenn Sie eine zusätzliche JupyterLab-Erweiterung installieren möchten, müssen Sie sie in der jupyterlab-Umgebung 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:

Benutzerdefinierten Container aktualisieren

Wenn Ihr benutzerdefinierter Container aktualisiert werden muss, können Sie den Metadatenwert custom-container-payload mit dem neuen Container-URI aktualisieren. Bei jedem Neustart des Containers wird versucht, den Container über den unter custom-container-payload gespeicherten URI abzurufen.

Wenn Sie das :latest-Tag verwenden, wird der Basiscontainer bei jedem Neustart aktualisiert. Sehen Sie sich folgendes Beispiel an:

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

Sie können die Version angeben, um das Aktualisieren des Basiscontainers zu vermeiden. Sehen Sie sich folgendes Beispiel an:

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

Diagnosetool ausführen

Mit dem Diagnosetool wird der Status verschiedener Vertex AI Workbench-Dienste geprüft. Weitere Informationen finden Sie unter Aufgaben des Diagnosetools.

Wenn Sie eine Vertex AI Workbench-Instanz mit einem benutzerdefinierten Container erstellen, ist das Diagnosetool nicht als Script in der Hostumgebung verfügbar, das Nutzer ausführen können. Stattdessen wird es in ein Binärprogramm 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 weitere Befehlsoptionen aufzurufen:

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

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

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: den Namen Ihrer Vertex AI Workbench-Instanz
• PROJECT_ID: Ihre Projekt-ID.
• LOCATION: Zone, in der sich Ihre Instanz befindet.

Führen Sie folgenden Befehl aus:

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

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

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